v3.2.0

Eventdisplay-ML - a toolkit to interface and run machine learning methods together with the Eventdisplay software package for gamma-ray astronomy data analysis.

Stereo (direction and energy) reconstruction tested and validated on both VERITAS and CTAO simulations plus VERITAS data.

Compatible with:

• Eventdisplay for CTAO simulations v5.18.1
• Eventdisplay for VERITAS v4.92 (not released yet)

New Features

• Add gamma/hadron classification training options to balance signal/background zenith-bin distributions and to omit ze_bin as a stress-test feature. Add zenith-uniformity summary metrics and multi-training comparison plots for gamma/hadron performance diagnostics. (#72)
• Introduce --model_prefix_high_multiplicity parameter for stereo analysis to use different models for 2-tel and >2-tel multiplicity events. (#73)
• Change training weights for stereo reconstruction, to avoid extreme weights leading to early training abortion. (#74)

Maintenance

• Reduce peak memory usage during chunked data loading and regression training. (#70)
• Address numpy deprecation warnings. (#71)

v3.1.0

Eventdisplay-ML - a toolkit to interface and run machine learning methods together with the Eventdisplay software package for gamma-ray astronomy data analysis.

Stereo (direction and energy) reconstruction tested and validated on both VERITAS and CTAO simulations plus VERITAS data.

Compatible with:

• Eventdisplay for CTAO simulations v5.18.1
• Eventdisplay for VERITAS v4.92 (not released yet)

Bugfixes

• Fix classification feature mismatch during application (E5): process_file_chunked now uses
  features_tmva_style when tmva_style=True, matching the training branch. (#63)
• Fix AttributeError in configure_training when energy_bins_log10_tev is absent from
  model parameters (E6): changed fallback default from [] (list, no .get) to {}. (#63)

New Features

• Move default XGBoost hyperparameters from hard-coded Python dicts into versioned JSON files
  (src/eventdisplay_ml/configs/default_hyperparameters_stereo.json and
  src/eventdisplay_ml/configs/default_hyperparameters_classification.json). The hyper_parameters module now always loads
  from a file — either the bundled default or a user-supplied --hyperparameter_config path —
  so the full training configuration is captured in a single auditable artifact. (#66)

Maintenance

• Add comprehensive unit-test suite covering all production modules (config, data_processing,
  diagnostic_utils, evaluate, features, geomag, hyper_parameters, models, optimize_classification,
  utils). Overall line coverage exceeds 90 %. (#63)

v3.0.0

Eventdisplay-ML - a toolkit to interface and run machine learning methods together with the Eventdisplay software package for gamma-ray astronomy data analysis.

Stereo (direction and energy) reconstruction tested and validated on both VERITAS and CTAO simulations plus VERITAS data.

Compatible with:

• Eventdisplay for CTAO simulations v5.18.1
• Eventdisplay for VERITAS v4.92 (not released yet)

New Features

• Add script to optimize gamma/hadron cut value using Li & Ma significance. Introduce fine binning for cut values and allow to take different source strengths and source spectral shapes into account. (#56)
• Add energy-bin interpolation support to the gamma/hadron classification application pipeline and improve the cut-optimization utilities by validating/interpolating rate/efficiency surfaces over energy and zenith (via 1/cos(ze) or cos(ze)). Add SHAP summary for gamma/hadron classification. (#57)
• Add TMVA-style gamma/hadron separation with the same features as TMVA BDT classification analysis. (#58)
• Improve classification hyperparameters with a focus on robustness, and add user-facing plotting CLI options for selecting --model_dir/--output_dir and --energy-bin. (#60)
• Add calculation and plotting of zenith-angle dependent signal and background efficiencies (classification mode). (#61)

v2.0.0

Eventdisplay-ML - a toolkit to interface and run machine learning methods together with the Eventdisplay software package for gamma-ray astronomy data analysis.

Stereo (direction and energy) reconstruction tested and validated on both VERITAS and CTAO simulations plus VERITAS data.

Compatible with:

• Eventdisplay for CTAO simulations v5.17.0
• Eventdisplay for VERITAS v4.92 (not released yet)

Changelog

New Features

• Add --max_tel_per_type 10 argument to restrict the number of telescope parameters per telescope type.
  Fix bug in indexing arrays with non-continuous telescope identifiers. (#49)

• Improve stereo reconstruction by adding the geometrical feature img2_ang.
  Change clipping min for size to '1' (applicable for small images in SSTs).
  Add preview_rows as command line parameter to allow flexible printout for debugging. (#51)

• Algorithm improvements

  • Switch to residual learning (predict corrections to baseline reconstructions)
  • Add target standardization for balanced multi-target training
  • Introduce energy-bin weighting with low-statistics suppression
  • Refine XGBoost training (regularization, early stopping, updated hyperparameters)

• New features

  • Training diagnostics with cached metrics (generalization gap, residual normality)
  • SHAP feature importance caching per target
  • Diagnostic scripts and CLI tools for evaluation and interpretability
  • Reproducible diagnostics via model metadata reconstruction
  • Expanded test suite and improved error handling

  (#53)

Maintenance

• Update g/h separation to new sorting scheme of telescope-dependent variables. (#45)
• Add early stopping to classification. Increase number of estimators. (#48)
• Add detailed copilot instructions. (#50)

Bugfixes

• Correct log10 handling for energy residuals
• Fix scaler loading/inversion in apply pipeline
• Fix energy-bin weighting logic
• Ensure safe energy validation (ErecS) without dropping rows
• Align evaluation metrics with residual formulation
• Resolve pandas/sklearn warnings and compatibility issues

v1.0.0

Eventdisplay-ML - a toolkit to interface and run machine learning methods together with the Eventdisplay software package for gamma-ray astronomy data analysis.

First fully stable release of Eventdisplay-ML for stereo (direction and energy) reconstruction.
Tested and validated on both VERITAS and CTAO simulations plus VERITAS data.

Compatible with:

• Eventdisplay for CTAO simulations v5.17.0
• Eventdisplay for VERITAS v4.92 (not released yet)

v0.5.0

Eventdisplay-ML - a toolkit to interface and run machine learning methods together with the Eventdisplay software package for gamma-ray astronomy data analysis.

Changelog

New Features

• Introduces telescope type handling for CTAO simulations by updating the stereo reconstruction pipeline to work with telescope-dependent variables across different telescope configurations. The key architectural change is moving from training separate models per telescope multiplicity (2, 3, 4 telescopes) to a single unified model that handles all multiplicities together. This is a major change applicable for both stereo and classification tasks. (#29)
• Add a telescope presence flag (tel_active) and implement combined weighting for both energy and telescope multiplicity in the training process. (#34)
• Introduced sorting of telescope-dependent variables by mirror area (as proxy to telescope type) and size. (#38)
• Add CTAO-specific support for telescope indexing/sorting and geomagnetic angle calculation by introducing an observatory configuration, new geomagnetic field presets, and updated sorting behavior (mirror area first, then size). (#39)
• Reduces reliance on elevation/azimuth-derived coordinates and expands per-telescope feature set by adding channel-count features. (#41)

Maintenance

• Migrate the data loading pipeline from pandas to Awkward Array for improved performance when processing the ROOT files. Enable parallel decompression through ThreadPoolExecutor (use --max_cores argument). (#31)

What's Changed

• Awkard by @GernotMaier in #31
• Introduce telescope types by @GernotMaier in #29
• fix renaming by @GernotMaier in #32
• AI disclosure by @GernotMaier in #33
• Add presence flag and change weights for multiplicity. by @GernotMaier in #34
• Changing weights by @GernotMaier in #35
• Fix Disp variable mapping to use tel_list_matrix before distance sorting by @Copilot in #37
• Order by size by @GernotMaier in #38
• Order by distance by @GernotMaier in #36
• Geomag ctao sorting by @GernotMaier in #39
• Decrease dependency on elevation / azimuth by @GernotMaier in #41

New Contributors

• @Copilot made their first contribution in #37

Full Changelog: v0.4.0...v0.5.0

v0.4.0

Eventdisplay-ML - a toolkit to interface and run machine learning methods together with the Eventdisplay software package for gamma-ray astronomy data analysis.

Changelog

v0.4.0 - 2026-01-20

New Features

• Apply unified clipping settings to feature variables. (#28)
• Add angle between pointing direction and geomagnetic field vector as feature. (#28)

What's Changed

• Stereo improvements: improved features, hyper parameters. by @GernotMaier in #26
• apply clip intervals by @GernotMaier in #28
• v0.4.0-rc by @GernotMaier in #30

Full Changelog: v0.3.0...v0.4.0

v0.3.0

Eventdisplay-ML - a toolkit to interface and run machine learning methods together with the Eventdisplay software package for gamma-ray astronomy data analysis.

Changelog

New Features

• Calculation classification thresholds for signal efficiencies and fill as boolean to classification trees. (#18)
• Add plotting scripts for classification efficiency.
  Add plotting scripts to compare TMVA and XGB performance for classification (#21)

Maintenance

• Add Zenodo entry to: https://doi.org/10.5281/zenodo.18117884 . (#17)
• Improve memory efficiency of training: loading and flattening data frames per file. (#24)

v0.2.0

Eventdisplay-ML - a toolkit to interface and run machine learning methods together with the Eventdisplay software package for gamma-ray astronomy data analysis.

Changelog

New Features

• add classification routines for gamma/hadron separation.
• add pre-training quality cuts.

(#13)

Maintenance

• refactoring code to minimize duplication and improve maintainability.
• unified command line interface for all scripts.
• unit tests are disabled for now due to rapid changes in the codebase.

(#13)

v0.1.1

Eventdisplay-ML - a toolkit to interface and run machine learning methods together with the Eventdisplay software package for gamma-ray astronomy data analysis.

Changelog

Maintenance

• Add PyPI project. (#12)