Visualization Functions

The gcs_visualization module provides plotting functions for classification results, hysteresis loops, diagnostic plots, and phase sequences.

Phase Visualization

create_phase_sequence_plot(results: DataFrame, sites: List[str], gccol: str = 'geochemical_phase') → Figure[source]

Create timeline showing phase transitions per site.

Parameters:

  • results (pd.DataFrame) – Classification results

  • sites (list of str) – Sites to plot

  • gccol (str) – Column holding classified phase name

Returns:

Timeline plot with phase colors

Return type:

go.Figure

Create timeline showing geochemical phase sequence for one or more sites.

Displays phases as colored horizontal bars over time, allowing visual inspection of temporal patterns and inter-site comparison.

create_diagnostic_plot(results: DataFrame, manual_labels: DataFrame | None = None, title: str = 'Geochemical Phase Classification Diagnostic', show_unlabeled: bool = True) → Figure[source]

Create two-panel diagnostic plot for phase classification.

Left: CVc/CVq vs C-Q Slope Right: ΔQ vs ΔC phase space

Parameters:

  • results (pd.DataFrame) – Classification results

  • manual_labels (pd.DataFrame, optional) – Manual labels for validation

  • title (str) – Plot title

  • show_unlabeled (bool) – Show segments without manual labels (faded)

Returns:

Two-panel diagnostic plot

Return type:

go.Figure

Create diagnostic scatter plot in CVc/CVq vs. C-Q slope space.

Points colored by geochemical phase, helps validate classification logic and identify phase clustering in mechanistic space.

Hysteresis Visualization

create_hysteresis_plot(data: DataFrame, sites: List[str], ccol: str, qcol: str, compound: str, conc_unit: str = 'mg L⁻¹', flow_unit: str = 'L s⁻¹', hi_method: str = 'zuecco', show_timeline: bool = True, line_style_method: str = 'zuecco') → Figure[source]

Create hysteresis plot for a single compound.

Parameters:

  • data (pd.DataFrame) – Classification results from classify_geochemical_phase()

  • sites (list of str) – Sites to plot

  • ccol (str) – Concentration and flow column names

  • qcol (str) – Concentration and flow column names

  • compound (str) – Compound name for labeling

  • conc_unit (str) – Units for labeling

  • flow_unit (str) – Units for labeling

  • hi_method (str) – Hysteresis method for line thickness (‘zuecco’, ‘lloyd’, ‘harp’)

  • show_timeline (bool) – Whether to show timeline subplot

  • line_style_method (str) – Hysteresis method for line style (‘zuecco’, ‘lloyd’, ‘harp’)

Returns:

Hysteresis plot figure

Return type:

go.Figure

Create C-Q hysteresis loops for classified segments.

Plots concentration vs. discharge with:

  • Phase-based coloring

  • Hysteresis index-based line thickness

  • Time-based point coloring

  • Load-informed point sizing (optional)

create_multi_compound_hysteresis_plot(data: DataFrame, Qx: DataFrame, sites: List[str], ccols: List[str], compounds: List[str], conc_units: List[str], qcol: str, flow_unit: str = 'L s⁻¹', hi_method: str = 'zuecco', cxmin: List[float] | None = None, cxmax: List[float] | None = None, qxmin: float | None = None, qxmax: float | None = None, line_style_method: str = 'zuecco') → Figure[source]

Create multi-compound hysteresis comparison plot.

Each compound is analyzed with its own concentration ranges.

Parameters:

  • data (pd.DataFrame) – Input data

  • Qx (pd.DataFrame) – High-resolution discharge timeseries

  • sites (list) – Sites to plot

  • ccols (list) – Concentration columns (one per compound)

  • compounds (list) – Compound names for labeling

  • conc_units (list) – Units for each compound

  • qcol (str) – Flow column name

  • flow_unit (str) – Flow unit

  • hi_method (str) – Hysteresis method for line thickness

  • cxmin (list of float, optional) – Concentration ranges per compound

  • cxmax (list of float, optional) – Concentration ranges per compound

  • qxmin (float, optional) – Flow range (shared)

  • qxmax (float, optional) – Flow range (shared)

  • line_style_method (str) – Hysteresis method for line style

Returns:

Multi-panel plot

Return type:

go.Figure

Create multi-panel hysteresis comparison across compounds and sites.

Useful for comparing hysteresis patterns between different analytes (e.g., metals, nutrients) at the same sites.

create_hysteresis_timeline(results: DataFrame, sites: List[str], compound: str, hi_method: str = 'zuecco') → Figure[source]

Create timeline visualization of hysteresis behaviors.

Parameters:

  • results (pd.DataFrame) – Classification results from classify_geochemical_phase()

  • sites (list of str) – Sites to plot

  • compound (str) – Compound name for title

  • hi_method (str) – Hysteresis method

Returns:

Timeline plot

Return type:

go.Figure

Create timeline visualization of hysteresis indices over time.

Shows temporal evolution of HARP, Zuecco, or Lloyd indices alongside flow and concentration data.

Summary Statistics

create_hysteresis_summary_stats(results: DataFrame, sites: List[str], ccol: str, hi_method: str = 'zuecco') → DataFrame[source]

Generate summary statistics for hysteresis behavior.

Parameters:

  • results (pd.DataFrame) – Classification results from classify_geochemical_phase()

  • sites (list of str) – Sites to analyze

  • ccol (str) – Compound column name

  • hi_method (str) – Hysteresis method

Returns:

Summary with phase frequencies, durations, and HI statistics

Return type:

pd.DataFrame

Generate summary statistics table for classified data.

Returns DataFrame with:

  • Phase percentages by site

  • Mean hysteresis indices per phase

  • Phase duration statistics

  • Transition frequencies

Style and Color Functions

get_line_style_from_hi_class(seg: Series, method: str = 'zuecco') → str[source]

Determine line style from hysteresis classification.

Parameters:

  • seg (pd.Series) – Segment data with hysteresis classifications

  • method (str) – Which HI method to use (‘zuecco’, ‘lloyd’, ‘harp’)

Returns:

Plotly dash style: ‘solid’, ‘2px 1px’, or ‘1px 1px’

Return type:

str

Get Plotly line style string based on hysteresis index and classification.

Used internally to style hysteresis loop plots based on direction and magnitude.

calculate_log_thickness(hi_values: ndarray, min_thickness: float = 3, max_thickness: float = 8) → ndarray[source]

Calculate log-normalized line thickness for visualization.

Parameters:

  • hi_values (array-like) – Absolute hysteresis index values

  • min_thickness (float) – Thickness range

  • max_thickness (float) – Thickness range

Returns:

Thickness values scaled between min and max

Return type:

np.ndarray

Calculate log-normalized line thickness for visualization.

Converts hysteresis index magnitudes to appropriate line widths for plotting.

Color Schemes

phase_colors

Dictionary mapping geochemical phase codes to colors:

{
    'F': '#E69F00',  # Flushing - orange
    'L': '#56B4E9',  # Loading - sky blue
    'C': '#009E73',  # Chemostatic - green
    'D': '#F0E442',  # Dilution - yellow
    'R': '#0072B2',  # Recession - blue
    'V': '#D55E00'   # Variable - red-orange
}
phase_names

Dictionary mapping phase codes to descriptive names:

{
    'F': 'Flushing',
    'L': 'Loading',
    'C': 'Chemostatic',
    'D': 'Dilution',
    'R': 'Recession',
    'V': 'Variable'
}
hyphase_colors

Alternative color scheme for hydrological phases (if used).

Usage Examples

Phase Sequence Plot:

import hygcs as gcs

# After classification
classified = gcs.classify_geochemical_phase(pcd, sites=['Site1', 'Site2'], ...)

# Create phase timeline
fig = gcs.create_phase_sequence_plot(classified, sites=['Site1', 'Site2'])
fig.update_xaxes(range=['2020-01-01', '2022-12-31'])
fig.show()

Diagnostic Plot:

# CVc/CVq vs C-Q slope space
fig_diag = gcs.create_diagnostic_plot(classified)
fig_diag.show()

Hysteresis Plot:

fig_hyst = gcs.create_hysteresis_plot(
    classified,
    sites=['Site1'],
    ccol='PLI',
    qcol='Q_mLs',
    compound='PLI',
    conc_unit='µg/L'
)
fig_hyst.show()

Multi-Compound Comparison:

fig = gcs.create_multi_compound_hysteresis_plot(
    pcd, Qx,
    sites=['Site1', 'Site2'],
    ccols=['Cd_mgL', 'Zn_mgL', 'Fe_mgL'],
    compounds=['Cd', 'Zn', 'Fe'],
    conc_units=['mg/L', 'mg/L', 'mg/L'],
    qcol='Q_mLs',
    flow_unit='mL/s',
    hi_method='zuecco'
)
fig.show()

Summary Statistics:

stats = gcs.create_hysteresis_summary_stats(
    classified,
    sites=['Site1', 'Site2', 'Site3'],
    ccol='PLI',
    hi_method='zuecco'
)
print(stats[['site_id', 'phase_name', 'percentage',
             'mean_duration_days']])

Customization

All plotting functions return Plotly Figure objects that can be customized:

fig = gcs.create_phase_sequence_plot(classified, sites=['Site1'])

# Update layout
fig.update_layout(
    template='plotly_white',
    title='Geochemical Phase Evolution',
    height=400
)

# Update axes
fig.update_xaxes(title='Time')
fig.update_yaxes(title='Site')

# Save figure
fig.write_html('phase_sequence.html')
fig.write_image('phase_sequence.pdf', width=1200, height=400)

Notes

Plotly Rendering

All visualizations use Plotly for interactive plotting. Figures can be:

  • Displayed interactively in Jupyter notebooks

  • Saved as HTML for sharing

  • Exported as static images (requires kaleido: pip install kaleido)

Color Accessibility

Color schemes are chosen to be distinguishable for most types of color vision deficiency. For publications, consider using shape/pattern variations in addition to color.

See Also