HyGCS - Hydro-Geochemical Classification Suite
A comprehensive Python toolkit for hysteresis analysis and geochemical phase classification in concentration-discharge (C-Q) relationships.
Version 0.5 (December 2025)
Overview
HyGCS provides tools for analyzing water quality dynamics in catchments, mine drainage systems, and environmental monitoring networks. The package integrates scientifically validated methods for:
Multi-method hysteresis analysis (HARP, Zuecco, Lloyd/Lawler)
CVc/CVq variability analysis (Musolff et al., 2015)
C-Q slope calculation (power-law exponents)
Geochemical phase classification (6-phase hierarchical system)
Comprehensive visualization tools
Key Features
1. Multi-Method Hysteresis Analysis
HARP (Roberts et al., 2023) - Empirical classification based on peak timing and loop geometry
Zuecco Index (Zuecco et al., 2016) - Integration-based index with 9-class classification
Lloyd/Lawler (Lloyd et al., 2016) - Percentile-based indices with symmetric range
2. Geochemical Phase Classification
Six-phase hierarchical system:
F (Flushing): Dilution-dominated, steep C decline during high Q
L (Loading): Enrichment, C increase before peak Q
C (Chemostatic): Buffered, low variability, flat C-Q slope
D (Dilution): Post-flush recovery, declining flow
R (Recession): Late cycle, low connectivity
V (Variable): Ambiguous/mixed patterns
3. Visualization
Phase sequence timelines
C-Q hysteresis loops with phase coloring
Diagnostic plots (CVc/CVq vs. C-Q slope)
Multi-compound comparison plots
Quick Start
Single Event Hysteresis Analysis:
import hygcs as gcs
import pandas as pd
# Load event data
data = pd.read_csv('event_data.csv')
# Calculate all hysteresis metrics
metrics = gcs.calculate_all_hysteresis_metrics(
data,
time_col='datetime',
discharge_col='Q',
concentration_col='C'
)
print(f"HARP Area: {metrics['harp_metrics']['area']:.4f}")
print(f"Zuecco h-index: {metrics['zuecco_metrics']['h_index']:.4f}")
print(f"Lloyd HInew: {metrics['lloyd_metrics']['mean_HInew']:.4f}")
Time Series Classification:
# Load monitoring time series
pcd = pd.read_csv('monitoring_data.csv')
pcd['date'] = pd.to_datetime(pcd['date'])
# Run geochemical phase classification
classified = gcs.classify_geochemical_phase(
pcd,
sites=['Site1', 'Site2'],
ccol='PLI',
qcol='Q_mLs',
use_highres=False
)
# Visualize results
fig = gcs.create_phase_sequence_plot(classified, sites=['Site1'])
fig.show()
Documentation Contents
Scientific Background
Hysteresis Methods
- HARP (Roberts et al., 2023)
Hysteresis Analysis of Rising and falling Peaks - Empirical classification based on peak timing and residuals.
- Zuecco Index (Zuecco et al., 2016)
Integration-based hysteresis index with 9-class classification system.
- Lloyd/Lawler Methods (Lloyd et al., 2016; Lawler et al., 2006)
Percentile-based approach. HInew (difference method) recommended for standard comparisons.
CVc/CVq Framework
Musolff et al. (2015) - Coefficient of variation approach:
CVc/CVq > 1: Chemodynamic (variable C behavior)
CVc/CVq < 1: Chemostatic (buffered C behavior)
C-Q Relationships
Thompson et al. (2011) - C-Q slope interpretation:
b > 0: Dilution/flushing patterns
b < 0: Enrichment/loading patterns
b ≈ 0: Chemostatic buffering
Critical Perspective
Knapp & Musolff (2024) - Critical assessment emphasizing multi-method validation and contextual interpretation.
License
CC-BY 4.0 - Creative Commons Attribution 4.0 International License
You are free to share and adapt this work with appropriate attribution.