src/eruption_forecast/
├── tremor/ # Seismic tremor processing
│ ├── calculate_tremor.py # CalculateTremor — main orchestrator
│ ├── rsam.py # Real Seismic Amplitude Measurement
│ ├── dsar.py # Displacement Seismic Amplitude Ratio
│ ├── shanon_entropy.py # Shannon Entropy metric
│ └── tremor_data.py # TremorData — wraps tremor CSV
├── label/ # Training label generation
│ ├── label_builder.py # LabelBuilder — sliding window labelling
│ └── label_data.py # LabelData — wraps label CSV
├── features/ # Feature extraction & selection
│ ├── features_builder.py # FeaturesBuilder — tsfresh extraction
│ ├── feature_selector.py # FeatureSelector — 3-method selection
│ └── tremor_matrix_builder.py # TremorMatrixBuilder — windowed alignment
├── model/ # ML model training & prediction
│ ├── forecast_model.py # ForecastModel — full pipeline orchestrator
│ ├── model_trainer.py # ModelTrainer — multi-seed training
│ ├── model_predictor.py # ModelPredictor — inference & forecasting
│ ├── model_evaluator.py # ModelEvaluator — single-seed evaluation
│ ├── multi_model_evaluator.py # MultiModelEvaluator — aggregate evaluation
│ └── classifier_model.py # ClassifierModel — classifier + grid management
├── sources/ # Seismic data source adapters
│ ├── sds.py # SDS reader (SeisComP Data Structure)
│ └── fdsn.py # FDSN web service client with local caching
├── config/ # Pipeline configuration
│ └── pipeline_config.py # PipelineConfig + sub-config dataclasses
├── plots/ # Visualization utilities
│ ├── tremor_plots.py
│ ├── feature_plots.py
│ ├── evaluation_plots.py
│ └── shap_plots.py
├── utils/ # Focused utility modules
│ ├── array.py # Z-score outlier detection
│ ├── window.py # Sliding window construction
│ ├── date_utils.py # Date validation and conversion
│ ├── dataframe.py # DataFrame validation
│ ├── ml.py # Resampling and feature utilities
│ ├── pathutils.py # Path resolution relative to root_dir
│ └── formatting.py # Text formatting
└── decorators/ # Function decorators
└── notify.py # Telegram notification decorator
Principle
What it means in practice
Single Responsibility Each module has one purpose — rsam.py only computes RSAM, date_utils.py only handles dates
Explicit Imports No hidden re-exports; import exactly what you need: from eruption_forecast.utils.date_utils import to_datetime
Minimal Dependencies Each utility module imports only its own direct dependencies
Fluent API All pipeline classes support method chaining via return self
Data Leakage Prevention Train/test split always happens before resampling and feature selection
Cached Properties
TremorData and LabelData use @cached_property so attributes are computed once
ForecastModel
├── uses CalculateTremor (or load_tremor_data)
├── uses LabelBuilder
├── uses TremorMatrixBuilder
├── uses FeaturesBuilder
│ └── uses FeatureSelector
├── uses ModelTrainer
│ └── uses ClassifierModel (grid + CV)
└── uses ModelPredictor
├── uses ModelEvaluator (evaluation mode)
└── aggregates predictions (forecast mode)
MultiModelEvaluator
├── reads trained_model_*.csv (registry from ModelTrainer)
└── reads metrics/*.json (per-seed metrics from ModelEvaluator)
Stage
Input
Output
CalculateTremorRaw SDS/FDSN waveforms
tremor_*.csv — DateTime index, RSAM/DSAR/entropy columns
LabelBuilderDate range + eruption dates
label_*.csv — DateTime index, id, is_erupted columns
TremorMatrixBuildertremor DataFrame + label DataFrame
tremor_matrix_*.csv — long-format with id, datetime, tremor columns
FeaturesBuildertremor matrix + labels
all_extracted_features_*.csv, label_features_*.csv
ModelTrainerfeatures CSV + labels CSV
models/*.pkl, trained_model_*.csv, metrics files
ModelPredictor
trained_model_*.csv + new tremor
predictions.csv, eruption_forecast.png
Module
Key Functions
utils/array.py
detect_maximum_outlier(), remove_outliers() — Z-score based
utils/window.py
construct_windows(), calculate_window_metrics()
utils/date_utils.py
to_datetime(), validate_date_ranges(), validate_window_step()
utils/ml.py
random_under_sampler(), get_significant_features()
utils/pathutils.py
resolve_output_dir() — resolves relative paths against root_dir
utils/dataframe.pyDataFrame shape/column validation helpers
utils/formatting.pyHuman-readable text formatting (elapsed time, file sizes, etc.)
Configuration Dataclasses PipelineConfig holds sub-configs for each pipeline stage:
Dataclass
Stage it covers
ModelConfig
ForecastModel constructor parameters
CalculateConfig
calculate() parameters
BuildLabelConfig
build_label() parameters
ExtractFeaturesConfig
extract_features() parameters
TrainConfig
train() parameters
ForecastConfig
forecast() parameters
Configs are serialised to YAML or JSON via PipelineConfig.save() and loaded via ForecastModel.from_config(). See the Configuration wiki page.