Changelog

Version 0.5 (December 2025)

Major Restructuring Release

Package Organization

  • Eliminated gcs_analysis.py - functions merged into gcs_core.py

  • Renamed gcs_v5.py → gcs.py for cleaner imports

  • Reorganized classification functions into dedicated module

  • Moved classify_cq_behavior_simple() from core to classification module

  • Improved module coherence and logical organization

Function Changes

Renamed Functions:

  • classify_with_highres_logic() → classify_segment_phase()

  • More descriptive, clearer purpose

New Functions:

  • calculate_log_thickness() - Log-normalized line thickness for hysteresis plots

  • get_line_style_from_hi_class() - Method-specific line styling

Improved Functions:

  • calculate_all_hysteresis_metrics() - Now returns comprehensive dictionary

  • compute_cvc_cvq_windows() - Added window size parameter

  • All visualization functions updated with improved styling

Bug Fixes

Critical:

  • Fixed Lloyd/Lawler NaN bug in percentile sampling

  • Fixed event-scale hysteresis duplication in window analysis

  • Resolved import coherency issues

Minor:

  • Suppressed Lloyd/Lawler “Mean of empty slice” warnings

  • Fixed thickness calculation in hysteresis plots

  • Corrected line style assignment logic for different HI classifiers

Visualization Improvements

  • Classifier-based line styles - Different patterns for HARP/Zuecco/Lloyd

  • Log thickness scaling - Better visual representation of HI magnitudes

  • Phase color consistency - Unified color scheme across all plots

  • Improved legends - Clearer labels and better organization

Documentation

  • Added comprehensive README.md

  • Created GETTING_STARTED.md quick start guide

  • Detailed PACKAGE_CONTENTS.md structure reference

  • Complete API documentation in docstrings

  • Added VISUALIZATION_LINE_STYLE_UPDATE.md technical doc

  • Created IMPORT_FIX.md troubleshooting guide

Testing

  • New comprehensive import test (test_imports_v05.py)

  • Verifies all 8 test categories

  • Checks for removed old function names

  • Validates version metadata

GitHub Readiness

  • Added setup.py for pip installation

  • Created requirements.txt with all dependencies

  • Added .gitignore for Python projects

  • Full CC-BY 4.0 LICENSE text included

  • Example notebooks cleaned and documented

Version 4.0 (Previous)

Original Monolithic Version

  • Combined hysteresis analysis and classification

  • Single large module structure

  • Event-scale hysteresis only

  • Basic visualization functions

  • Known issues with Lloyd NaN and event duplication

Known Issues in v4.0

  • Lloyd function generates numpy warnings

  • Event-scale hysteresis creates artifacts in time series

  • Import structure confusing

  • Documentation scattered

  • No formal package structure

Migration from v4.0 to v0.5

Breaking Changes

Import Changes:

Old:

from gcs_v5 import classify_geochemical_phase
from gcs_analysis import some_function

New:

import hygcs as gcs
classified = gcs.classify_geochemical_phase(...)

Function Renames:

Old Name

New Name

classify_with_highres_logic()

classify_segment_phase()

gcs_v5.py (module)

gcs.py

Removed Functions:

Functions in gcs_analysis.py were merged into gcs_core.py. Direct imports from gcs_analysis will fail.

Migration Guide:

# Old v4.0 code
from gcs_v5 import classify_geochemical_phase
from gcs_analysis import calculate_all_hysteresis_metrics

# New v0.5 code
import hygcs as gcs
classified = gcs.classify_geochemical_phase(...)
metrics = gcs.calculate_all_hysteresis_metrics(...)

Deprecated Features

None - this is a major restructuring, old structure fully replaced.

Future Plans

Version 0.6 (Planned)

Potential improvements:

  • PyPI package release

  • Additional hysteresis methods

  • Improved confidence scoring algorithms

  • Machine learning phase classification option

  • Expanded test suite

  • Performance optimizations

Version 1.0 (Planned)

Stable API release:

  • Frozen API for backwards compatibility

  • Complete test coverage

  • Comprehensive benchmarking

  • Publication of methodology paper

  • Community contribution guidelines

Reporting Issues

Found a bug? Have a suggestion?

Contributing

We welcome contributions! Please:

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes with tests

  4. Submit a pull request

See CONTRIBUTING.md (to be added) for detailed guidelines.

Version Numbering

HyGCS follows semantic versioning principles:

  • Major version (X.0.0): Breaking API changes

  • Minor version (0.X.0): New features, backwards compatible

  • Patch version (0.0.X): Bug fixes, backwards compatible

Current version: 0.5.0