Examples

Example Jupyter notebooks demonstrating HyGCS functionality.

Available Notebooks

demo_gcs_core_function.ipynb

Comprehensive hysteresis method demonstration

This notebook provides an in-depth tutorial on:

  1. Single Event Analysis

    • Loading example datasets

    • Calculating HARP, Zuecco, and Lloyd/Lawler metrics

    • Interpreting results from each method

    • Comparing method outputs

  2. Visual Analysis

    • HARP C-Q loop visualization with peak markers

    • Zuecco differential area plots

    • Lloyd/Lawler percentile sampling plots

  3. Comparative Analysis

    • Analyzing multiple datasets

    • Creating summary comparison tables

    • Multi-panel hysteresis loop plots

  4. Method Comparison

    • Understanding convergent evidence

    • Identifying method disagreements

    • Interpreting complex patterns

Data:

Uses reference datasets from HARP and Zuecco packages (hysteresis_examples.xlsx)

Best for:

Learning the three hysteresis methods and understanding how they complement each other.

test_gcs.ipynb

Real-world GCS classification demonstration

This notebook demonstrates time series classification on real mine drainage monitoring data:

  1. Data Loading

    • Real geochemical monitoring data (test_gc.csv)

    • High-resolution hydrological data (test_hyd.csv)

  2. Classification Workflow

    • Running classify_geochemical_phase() on multiple sites

    • Interpreting classification results

    • Examining confidence scores

  3. Visualization

    • Phase sequence timelines across sites

    • Diagnostic plots (CVc/CVq vs C-Q slope)

    • Hysteresis plots colored by phase

    • Multi-compound comparison plots

  4. Summary Statistics

    • Phase percentages by site

    • Temporal pattern analysis

    • C-Q slope time series

Data:

Real monitoring data from legacy mine sites analyzing PLI (Pollution Load Index) and individual metals (Cd, Zn, Fe).

Best for:

Understanding how to apply GCS to real monitoring data and interpret results.

Running the Notebooks

Install Jupyter

If you haven’t already:

pip install jupyter notebook ipywidgets

Launch Jupyter

From the HyGCS directory:

jupyter notebook

Navigate to examples/ and open the desired notebook.

Or launch directly:

jupyter notebook examples/demo_gcs_core_function.ipynb

Interactive Execution

The notebooks are designed to be run cell-by-cell. Each cell can be executed with Shift+Enter. Follow the narrative flow and experiment with parameters.

Example Workflows

Workflow 1: Analyze Single Storm Event

import hygcs as gcs
import pandas as pd

# Load event data
event = pd.read_csv('my_storm_event.csv')

# Calculate all hysteresis metrics
metrics = gcs.calculate_all_hysteresis_metrics(
    event,
    time_col='datetime',
    discharge_col='Q',
    concentration_col='NO3'
)

# Interpret convergence
harp_area = metrics['harp_metrics']['area']
zuecco_hi = metrics['zuecco_metrics']['h_index']
lloyd_hi = metrics['lloyd_metrics']['mean_HInew']

print(f"HARP area: {harp_area:.3f}")
print(f"Zuecco h-index: {zuecco_hi:.3f}")
print(f"Lloyd HInew: {lloyd_hi:.3f}")

# Check agreement
if all([x > 0 for x in [harp_area, zuecco_hi, lloyd_hi]]):
    print("✓ All methods agree: Clockwise hysteresis")
elif all([x < 0 for x in [zuecco_hi, lloyd_hi]]):
    print("✓ Methods agree: Counter-clockwise hysteresis")
else:
    print("⚠ Methods disagree: Complex pattern, investigate")

Workflow 2: Multi-Site Classification

# Load monitoring data
pcd = pd.read_csv('monitoring_data.csv')
pcd['date'] = pd.to_datetime(pcd['date'])

# Define sites
sites = pcd['site_id'].unique()

# Classify
classified = gcs.classify_geochemical_phase(
    pcd,
    sites=sites,
    ccol='concentration',
    qcol='discharge',
    use_highres=False
)

# Summary by site
for site in sites:
    site_data = classified[classified['site_id'] == site]

    print(f"\n{site}:")
    print(f"  Total segments: {len(site_data)}")
    print(f"  Mean confidence: {site_data['phase_confidence'].mean():.2f}")

    # Phase distribution
    phase_counts = site_data['geochemical_phase'].value_counts()
    for phase, count in phase_counts.items():
        pct = 100 * count / len(site_data)
        print(f"  {phase}: {count} ({pct:.1f}%)")

Workflow 3: Multi-Compound Comparison

# Prepare compound list
compounds = ['NO3', 'DOC', 'Ca']

# Run classification for each compound
results = {}
for compound in compounds:
    classified = gcs.classify_geochemical_phase(
        pcd,
        sites=['Site1'],
        ccol=compound,
        qcol='Q',
        use_highres=False
    )
    results[compound] = classified

# Create multi-compound hysteresis plot
fig = gcs.create_multi_compound_hysteresis_plot(
    pcd, None,  # No high-res Q
    sites=['Site1'],
    ccols=compounds,
    compounds=compounds,
    conc_units=['mg/L', 'mg/L', 'mg/L'],
    qcol='Q',
    hi_method='zuecco'
)
fig.show()

Workflow 4: CVc/CVq Analysis

# Compute CVc/CVq for different window sizes
windows = [5, 10, 20]

for w in windows:
    cvc_cvq = gcs.compute_cvc_cvq_windows(
        pcd,
        qcol='Q',
        ccol='NO3',
        window=w
    )

    print(f"\nWindow = {w} samples:")
    print(f"  Mean CVc/CVq: {cvc_cvq['CVc_CVq'].mean():.2f}")

    # Classify behavior
    chemostatic = (cvc_cvq['CVc_CVq'] < 1).sum()
    chemodynamic = (cvc_cvq['CVc_CVq'] >= 1).sum()

    pct_chemostatic = 100 * chemostatic / len(cvc_cvq)
    print(f"  Chemostatic: {pct_chemostatic:.1f}%")
    print(f"  Chemodynamic: {100 - pct_chemostatic:.1f}%")

Expected Outputs

From demo_gcs_core_function.ipynb

  • HARP, Zuecco, Lloyd metrics for 4 example datasets

  • Interactive C-Q loop plots for each method

  • Comparative summary table

  • Multi-panel hysteresis visualization

From test_gcs.ipynb

  • Classified time series DataFrame with phases and confidence

  • Phase sequence timeline plot showing temporal evolution

  • Diagnostic scatter plot in CVc/CVq vs C-Q slope space

  • Hysteresis loops colored by geochemical phase

  • Multi-compound comparison showing different analytes

  • Summary statistics tables

Troubleshooting

Notebook Won’t Open

Ensure Jupyter is installed:

pip install jupyter notebook

Plots Don’t Display

For Plotly in Jupyter, you may need:

pip install ipywidgets
jupyter nbextension enable --py widgetsnbextension

Then restart Jupyter.

Module Import Errors

Ensure HyGCS is installed or on your Python path:

import sys
sys.path.append('../hygcs')
import gcs

Missing Data Files

Ensure you’re in the examples/ directory or adjust file paths:

data = pd.read_csv('examples/test_gc.csv')

Further Resources

Next Steps

After working through the examples:

  1. Try on your own data

  2. Experiment with parameters

  3. Compare method outputs

  4. Validate against known events

  5. Consult the API reference for advanced usage