-
Notifications
You must be signed in to change notification settings - Fork 0
Architecture
Martanto edited this page Jul 19, 2026
·
17 revisions
This page is the structural reference for eruption_forecast: every module under src/,
the top-level pipeline, how the model and ensemble classes relate, what flows between
stages on disk, and the utility surface that holds the rest together.
×ばつ N seeds) │ ├── classifier_ensemble.py - ClassifierEnsemble (N classifiers) │ ├── metrics_ensemble.py - MetricsEnsemble (metrics engine) │ └── explainer_ensemble.py - ExplainerEnsemble (per-seed SHAP engine) │ ├── features/ │ ├── constants.py │ ├── tremor_matrix_builder.py - TremorMatrixBuilder (windowed alignment) │ ├── features_builder.py - FeaturesBuilder (tsfresh extraction) │ ├── feature_selector.py - FeatureSelector (tsfresh FDR or RF importance) │ └── feature_count_sweep.py - ⚠ Experimental. FeatureCountSweep + sweep_feature_count (post-hoc top_n_features recommender) │ ├── label/ │ ├── constants.py │ ├── label_builder.py - LabelBuilder (sliding window) │ ├── dynamic_label_builder.py - DynamicLabelBuilder (per-eruption build) │ ├── label_data.py - LabelData (CSV wrapper) │ └── label_plots.py - plot_label_distribution │ ├── model/ │ ├── constants.py │ ├── base_model.py - BaseModel ABC (dates, I/O, dual-mode save/load + cache identity) │ ├── forecast_model.py - ForecastModel orchestrator │ ├── training_model.py - TrainingModel(BaseModel) │ ├── prediction_model.py - PredictionModel(BaseModel) │ ├── evaluation_model.py - EvaluationModel(BaseModel) │ ├── explanation_model.py - ExplanationModel(BaseModel) │ ├── classifier_model.py - ClassifierModel (estimator + grid) │ └── classifier_comparator.py - ClassifierComparator (cross-classifier rank) │ ├── plots/ │ ├── styles.py │ ├── tremor_plots.py - plot_tremor │ ├── feature_plots.py - feature-importance plots │ ├── forecast_plots.py - plot_forecast, plot_forecast_from_file │ ├── evaluation_plots.py - ROC, PR, confusion, threshold, importance │ └── explanation_plots.py - SHAP waterfall / beeswarm / bar / aggregate │ ├── sources/ │ ├── base.py - SeismicDataSource ABC │ ├── sds.py - Local SeisComP archive reader │ └── fdsn.py - FDSN client with local SDS caching │ ├── tremor/ │ ├── calculate_tremor.py - CalculateTremor (orchestrator) │ ├── rsam.py, dsar.py, shannon_entropy.py - per-metric kernels │ └── tremor_data.py - TremorData (CSV wrapper) │ └── utils/ ├── array.py, benchmark.py, dataframe.py, date_utils.py ├── formatting.py, ml.py, pathutils.py ├── validation.py, window.py">
src/eruption_forecast/
├── __init__.py - public exports
├── logger.py - loguru wrapper (enable/disable/set_level/set_directory) + per-category error files (register_error_category, get_category_logger; telegram category ships pre-registered)
├── data_container.py - BaseDataContainer ABC for TremorData / LabelData
│
├── config/
│ ├── base_config.py - shared config primitives
│ ├── constants.py - ERUPTION_PROBABILITY_THRESHOLD, defaults
│ ├── forecast_config.py - ForecastConfig + per-stage sub-configs
│ ├── training_config.py - TrainingConfig (standalone TrainingModel)
│ ├── prediction_config.py - PredictionConfig (standalone PredictionModel)
│ ├── evaluation_config.py - EvaluationConfig (standalone EvaluationModel)
│ └── explanation_config.py - ExplanationConfig (standalone ExplanationModel)
│
├── dataclass/
│ ├── station_data.py - StationData (immutable nslc identity)
│ ├── classifier_ensemble_summary.py - ClassifierEnsembleSummary, EruptionWindow, ProbabilityPick
│ └── classifier_explanation.py - SeedExplanation, ClassifierExplanation (SHAP payloads)
│
├── decorators/
│ ├── notify.py - @notify decorator (Telegram success/error notifications)
│ └── timer.py - @timer decorator (elapsed-time logger, optional Telegram forward)
│
├── notification/
│ └── telegram.py - TelegramNotification (send_message / send_document / send_photo / send_media_group)
│
├── ensemble/
│ ├── base_ensemble.py - BaseEnsemble (joblib save/load mixin)
│ ├── seed_ensemble.py - SeedEnsemble (one classifier ×ばつ N seeds)
│ ├── classifier_ensemble.py - ClassifierEnsemble (N classifiers)
│ ├── metrics_ensemble.py - MetricsEnsemble (metrics engine)
│ └── explainer_ensemble.py - ExplainerEnsemble (per-seed SHAP engine)
│
├── features/
│ ├── constants.py
│ ├── tremor_matrix_builder.py - TremorMatrixBuilder (windowed alignment)
│ ├── features_builder.py - FeaturesBuilder (tsfresh extraction)
│ ├── feature_selector.py - FeatureSelector (tsfresh FDR or RF importance)
│ └── feature_count_sweep.py - ⚠ Experimental. FeatureCountSweep + sweep_feature_count (post-hoc top_n_features recommender)
│
├── label/
│ ├── constants.py
│ ├── label_builder.py - LabelBuilder (sliding window)
│ ├── dynamic_label_builder.py - DynamicLabelBuilder (per-eruption build)
│ ├── label_data.py - LabelData (CSV wrapper)
│ └── label_plots.py - plot_label_distribution
│
├── model/
│ ├── constants.py
│ ├── base_model.py - BaseModel ABC (dates, I/O, dual-mode save/load + cache identity)
│ ├── forecast_model.py - ForecastModel orchestrator
│ ├── training_model.py - TrainingModel(BaseModel)
│ ├── prediction_model.py - PredictionModel(BaseModel)
│ ├── evaluation_model.py - EvaluationModel(BaseModel)
│ ├── explanation_model.py - ExplanationModel(BaseModel)
│ ├── classifier_model.py - ClassifierModel (estimator + grid)
│ └── classifier_comparator.py - ClassifierComparator (cross-classifier rank)
│
├── plots/
│ ├── styles.py
│ ├── tremor_plots.py - plot_tremor
│ ├── feature_plots.py - feature-importance plots
│ ├── forecast_plots.py - plot_forecast, plot_forecast_from_file
│ ├── evaluation_plots.py - ROC, PR, confusion, threshold, importance
│ └── explanation_plots.py - SHAP waterfall / beeswarm / bar / aggregate
│
├── sources/
│ ├── base.py - SeismicDataSource ABC
│ ├── sds.py - Local SeisComP archive reader
│ └── fdsn.py - FDSN client with local SDS caching
│
├── tremor/
│ ├── calculate_tremor.py - CalculateTremor (orchestrator)
│ ├── rsam.py, dsar.py, shannon_entropy.py - per-metric kernels
│ └── tremor_data.py - TremorData (CSV wrapper)
│
└── utils/
├── array.py, benchmark.py, dataframe.py, date_utils.py
├── formatting.py, ml.py, pathutils.py
├── validation.py, window.py
×ばつ M cv) │ └──┬───────────────────┬─┘ │ writes │ assembles ▼ ▼ ┌────────────────┐ ┌────────────────────────┐ │ SeedEnsemble ×ばつ │ │ ClassifierEnsemble │ │ N classifiers │ ─► │ (all SeedEnsembles) │ └────────────────┘ └──────────┬─────────────┘ │ ▼ ┌──────────────────────────────┐ │ PredictionModel │ │ build_label → │ │ extract_features → │ │ forecast (per-seed proba) │ └──────────────┬───────────────┘ │ ┌───────────────────────────────────┴──────────────────┐ ▼ ▼ ┌──────────────────────┐ ┌────────────────────────┐ │ EvaluationModel │ │ forecast-results_ │ │ dispatch on .kind: │ │ *.csv + forecast │ │ training | predict │ ── MetricsEnsemble ──► │ PNG/PDF │ └──────────┬───────────┘ └────────────────────────┘ │ writes (n_samples, n_seeds) y_proba / y_pred matrices ▼ ┌──────────────────────┐ │ ClassifierComparator │ ranking_*.csv + comparison figures └──────────────────────┘ ┌────────────────────────────────────────────────────────────────┐ │ ExplanationModel (BaseModel) │ │ dispatch on upstream model.kind: training | prediction │ │ │ │ ExplainerEnsemble │ │ ─ per-seed shap.TreeExplainer (RF / lite-rf / GB / XGB) │ │ ─ ClassifierExplanation.pkl per classifier │ │ ─ per-seed bar + beeswarm under classifiers/{Clf}/figures │ │ ─ per-eruption waterfall under eruptions/{date}/ │ └────────────────────────────────────────────────────────────────┘">
┌──────────────┐ ┌────────────────────┐ ┌─────────────────┐
│ Seismic │ │ CalculateTremor │ │ TremorData │
│ archive │ ──► │ (rsam/dsar/ │ ─► │ (CSV wrapper) │
│ (SDS|FDSN) │ │ entropy/bands) │ │ │
└──────────────┘ └────────────────────┘ └────────┬────────┘
│
┌─────────────────────────── feature pipeline ──────────┴─────┐
│ LabelBuilder TremorMatrixBuilder │
│ DynamicLabelBuilder ──► FeaturesBuilder (tsfresh) │
│ FeatureSelector (FDR or RF) │
└────────────────────────────┬────────────────────────────────┘
▼
┌────────────────────────┐
│ TrainingModel │
│ build_label → │
│ extract_features → │
│ fit (N seeds ×ばつ M cv) │
└──┬───────────────────┬─┘
│ writes │ assembles
▼ ▼
┌────────────────┐ ┌────────────────────────┐
│ SeedEnsemble ×ばつ │ │ ClassifierEnsemble │
│ N classifiers │ ─► │ (all SeedEnsembles) │
└────────────────┘ └──────────┬─────────────┘
│
▼
┌──────────────────────────────┐
│ PredictionModel │
│ build_label → │
│ extract_features → │
│ forecast (per-seed proba) │
└──────────────┬───────────────┘
│
┌───────────────────────────────────┴──────────────────┐
▼ ▼
┌──────────────────────┐ ┌────────────────────────┐
│ EvaluationModel │ │ forecast-results_ │
│ dispatch on .kind: │ │ *.csv + forecast │
│ training | predict │ ── MetricsEnsemble ──► │ PNG/PDF │
└──────────┬───────────┘ └────────────────────────┘
│ writes (n_samples, n_seeds) y_proba / y_pred matrices
▼
┌──────────────────────┐
│ ClassifierComparator │ ranking_*.csv + comparison figures
└──────────────────────┘
┌────────────────────────────────────────────────────────────────┐
│ ExplanationModel (BaseModel) │
│ dispatch on upstream model.kind: training | prediction │
│ │
│ ExplainerEnsemble │
│ ─ per-seed shap.TreeExplainer (RF / lite-rf / GB / XGB) │
│ ─ ClassifierExplanation.pkl per classifier │
│ ─ per-seed bar + beeswarm under classifiers/{Clf}/figures │
│ ─ per-eruption waterfall under eruptions/{date}/ │
└────────────────────────────────────────────────────────────────┘
ForecastModel is the orchestrator that calls every box in sequence.
The dashed arrows are also the method-chain order:
fm.calculate(...).train(...).predict(...).evaluate(...).explain(...).
CalculateTremor reads seismic traces day-by-day from a SeismicDataSource and
dispatches each day to the configured tremor kernels (rsam.py, dsar.py, shannon_entropy.py).
Per-day CSVs are written to tremor/daily/, then concatenated into the merged tremor
CSV at the station root. TremorData is a thin wrapper that exposes df, start_date, end_date,
sampling-rate validation, and the CSV filename / basename / filetype triple.
Two builders share the same output shape (id, is_erupted) but differ in how positives are placed:
-
LabelBuilder- sliding window over the full date range;day_to_forecastcontrols the look-ahead window.include_eruption_date=False(default) still marks the eruption day as positive, givingday_to_forecast + 1positive days per eruption. -
DynamicLabelBuilder- extendsLabelBuilderwith a per-eruption three-phase build: (1) zero frames per eruption, (2) concat + deduplicate datetimes, (3) mark positives per eruption. Solves the issue where overlapping look-ahead windows collide inLabelBuilder.
LabelBuilder - one global window over the full date range
─────────────────────────────────────────────────────────
include_eruption_date=False (default)
0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1
↑ ↑ ↑
dtf start day-before eruption
eruption (also 1)
→ dtf days strictly before eruption + eruption day = dtf+1 positives
include_eruption_date=True
0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1
↑ ↑
dtf start eruption (counted in dtf)
→ exactly dtf days ending on the eruption day
DynamicLabelBuilder - per-eruption build, overlapping windows deduped
─────────────────────────────────────────────────────────────────────
Phase 1: initiate (all zeros)
Eruption A window Eruption B window
[0 0 0 0 0 0 0 0 0 0] [0 0 0 0 0 0 0 0 0 0]
Phase 2: concat + deduplicate datetimes
[0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0] ← unified, sorted, unique
Phase 3: mark positives per eruption
Erup A (2025年03月20日, dtf=2): Mar 18–20 → 1
Erup B (2025年03月23日, dtf=2): Mar 21–23 → 1
[0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1]
↑ ↑
Erup A Erup B
LabelData parses parameters (window_size, window_step, window_step_unit, day_to_forecast)
directly out of the label filename so a CSV alone is enough to rehydrate the build context.
labels (id, is_erupted) tremor_df
│ │
▼ ▼
┌────────────────────────────────────────┐
│ TremorMatrixBuilder │
│ windowed slices aligned to labels │
└────────────────────┬───────────────────┘
▼
┌────────────────────────────────────────┐
│ FeaturesBuilder │
│ tsfresh extraction (per-column) │
│ training: relevance-filter on labels │
│ prediction: no filtering │
└────────────────────┬───────────────────┘
▼
┌────────────────────────────────────────┐
│ FeatureSelector │
│ method="tsfresh": FDR p-value filter │
│ method="random_forest": permutation │
│ importance │
│ → top-N feature names per seed │
└────────────────────────────────────────┘
TremorMatrixBuilder.build() validates sample counts per window against minimum_completion
and skips short windows so tsfresh never sees ragged input.
FeaturesBuilder runs per-column independent extractions so adding a new tremor
band does not invalidate the cached results for the others.
The model layer follows a mixin pattern:
-
BaseModel- abstract base for every stage. Owns the date/window grid, the lazytremor_dataaccessor,output_dirresolution,n_jobsclamping, the content-addressable cache identity helpers (build_identity,compute_hash,_canonicalize,tremor_fingerprint,cache_path), and the dual-mode joblibsave(identity=None, path=None)/ cache-onlyload(stage_dir, identity). Whenidentityis supplied,save()writes to{stage_dir}/{hash}.{ClassName}.pkl(plus a.params.jsonsidecar). Whenidentityis omitted, the legacy{output_dir}/{ClassName}_{basename}.pkljoblib dump is preserved for standalone manual saves. Subclasses implementset_directories,create_directories,validate,describe,to_dict,to_prompt,build_label,extract_features, and overridestage_dir+build_identitywhen they participate in the cache. -
TrainingModel(BaseModel)-build_label → extract_features → fit.fit()runs per-seedGridSearchCVinjoblib.Parallelover the selected classifiers, writes a per-classifier trained-model JSON registry viasave_model_json, bundles every seed into aSeedEnsembleand every classifier into aClassifierEnsemble, then callsself.save(self.build_identity())so the cache pickle lands at{training_dir}/{hash}.TrainingModel.pklwith a matching sidecar. -
PredictionModel(BaseModel)-build_label → extract_features → forecast. Cache identity embeds the upstreamtraining_hash(a constructor param threaded byForecastModel.predict), so re-training automatically invalidates downstream forecasts.forecast()callsself.save(self.build_identity()); cache files live at{prediction_dir}/{hash}.PredictionModel.pkl. -
EvaluationModel(BaseModel)- no cache; dispatches onmodel.kind("training"or"prediction"). Output is namespaced underevaluation/{kind}/so both modes can coexist. -
ExplanationModel(BaseModel)- per-seed SHAP explanations over a fittedClassifierEnsemble. Reuses the upstreamTrainingModelorPredictionModeland dispatches onmodel.kind. Restricted to tree classifiers (RF / lite-rf / GB / XGB); non-tree classifiers are skipped at theExplainerEnsembleloop with a warning. Output is namespaced underexplanation/{kind}/; cache pickles land at{explanation_dir}/{hash}.ExplanationModel.pkl(already mode-namespaced so training-reuse and prediction-reuse caches never collide). -
ForecastModel- the orchestrator. Not aBaseModelsubclass - it ownsCalculateTremor, builds the four stage classes lazily, and captures stage kwargs into aForecastConfigfor round-tripping.
ClassifierModel is the per-classifier descriptor (sklearn estimator + hyperparameter grid + slug).
ClassifierComparator consumes the in-memory MetricsEnsemble cached on EvaluationModel to rank classifiers head-to-head.
×ばつ N classifiers ×ばつ N fitted seeds 1 SeedEnsemble each + per-seed + features (sorted union feature lists across all SeedEnsembles) + features + factories (from_any, from_json, (sorted union from_dict, from_seed_ensembles) across all seeds) MetricsEnsemble (standalone - not a BaseEnsemble subclass) wraps ClassifierEnsemble + features + y_true writes only (n_samples, n_seeds) y_proba / y_pred CSV matrices metrics / y_probas / y_preds stay in memory ExplainerEnsemble (standalone - not a BaseEnsemble subclass) wraps ClassifierEnsemble + features writes per-classifier ClassifierExplanation.pkl + per-seed shap_values/{seed:05d}.pkl + per-seed bar / beeswarm + per-eruption waterfall plots">
BaseEnsemble (joblib save/load mixin)
│
┌────────┴────────┐
▼ ▼
SeedEnsemble ClassifierEnsemble
1 classifier ×ばつ N classifiers ×ばつ
N fitted seeds 1 SeedEnsemble each
+ per-seed + features (sorted union
feature lists across all SeedEnsembles)
+ features + factories (from_any, from_json,
(sorted union from_dict, from_seed_ensembles)
across all
seeds)
MetricsEnsemble (standalone - not a BaseEnsemble subclass)
wraps ClassifierEnsemble + features + y_true
writes only (n_samples, n_seeds) y_proba / y_pred CSV matrices
metrics / y_probas / y_preds stay in memory
ExplainerEnsemble (standalone - not a BaseEnsemble subclass)
wraps ClassifierEnsemble + features
writes per-classifier ClassifierExplanation.pkl
+ per-seed shap_values/{seed:05d}.pkl
+ per-seed bar / beeswarm + per-eruption waterfall plots
MetricsEnsemble and ExplainerEnsemble are both deliberately kept out of ensemble/__init__.py and imported via their full module paths (eruption_forecast.ensemble.metrics_ensemble, eruption_forecast.ensemble.explainer_ensemble) to keep the subpackage free of import cycles back through utils.ml and plots/.
SeismicDataSource is the read interface: get(date) -> obspy.Stream. Two concrete implementations:
-
SDS- pure local read from{root}/{year}/{network}/{station}/{channel}.D/{file}. -
FDSN- pulls from a remote FDSN service, then caches the downloaded MSEED into a local SDS layout (download_dir). Repeat calls with the same date hit the local cache.
apply_nature_style() normalises every figure to a Nature/Science-friendly palette and font stack.
Each plot module is a thin functional wrapper around matplotlib (and seaborn where appropriate) - see Visualization for the catalog and output paths.
ForecastConfig is the round-trip record for ForecastModel. Its six sub-configs match the stage method signatures one-for-one:
ForecastConfig
├── model: BaseForecastConfig
├── calculate: ForecastCalculateConfig | None
├── train: ForecastTrainConfig | None
├── predict: ForecastPredictConfig | None
├── evaluate: ForecastEvaluateConfig | None
└── explain: ForecastExplainConfig | None
TrainingConfig, PredictionConfig, EvaluationConfig, and ExplanationConfig each mirror their stage model's __init__ directly and are the standalone equivalents used when the model runs outside ForecastModel. Every stage model auto-calls save_config() at the end of its main run method (fit() / forecast() / evaluate() / explain()), so a standalone run always leaves a YAML snapshot next to its artefacts. The upstream model parameter on EvaluationConfig and ExplanationConfig is intentionally omitted because it is always a live model instance.
notify(task) wraps a function with success and error Telegram messages (MarkdownV2 body, hostname, elapsed time, exception details). timer(name, send_to=None) logs the wrapped function's elapsed wall-clock time via loguru; passing send_to="telegram" also mirrors the message to Telegram.
Both decorators delegate to TelegramNotification (notification/telegram.py), a fluent-chain client wrapping the Telegram Bot API. It exposes send_message(...), send_document(...), send_photo(...), and send_media_group(...); every send method returns self so calls can be chained (tn.send_message(...).send_document(...)). Credentials are resolved from constructor arguments or the TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID environment variables. Every network failure is logged and swallowed, so a dead network never blocks the caller. scenarios.py uses this class directly to ship each per-scenario forecast PNG next to a title message.
Nine focused modules that the rest of the codebase pulls from - see the table in 6.
×ばつ n_seeds)│ │ │ • from_any / from_json│ │ y_proba / y_pred CSV │ │ │ • from_seed_ensembles │ │ • metrics in memory │ │ └──────────┬─────────────┘ └───────────┬────────────┘ │ │ bundles │ aggregates │ ▼ ▼ ▼ ┌────────────────────────┐ ┌────────────────────────┐ ┌──────────────────┐ │ SeedEnsemble ×ばつ M │ │ ClassifierComparator │ │ ExplainerEnsemble│ │ ───────────────────── │ │ • get_ranking() │ │ • TreeExplainer │ │ • predict_proba │ │ • plot_all() │ │ per seed │ │ • predict_with_ │ └────────────────────────┘ │ • ClassifierExpln│ │ uncertainty │ │ per classifier │ └──────────┬─────────────┘ └──────────────────┘ │ inherits ▼ ┌─────────────────────────┐ │ BaseEnsemble │ │ (joblib save/load) │ └─────────────────────────┘">
┌─────────────────────────┐
│ BaseModel │
│ (ABC) │
│ • dates, output_dir │
│ • tremor_data (lazy) │
│ • n_jobs clamp │
│ • save() / load() │
└────────────┬────────────┘
│ inherits
┌────────────────┬───────────┼───────────────┬────────────────┐
▼ ▼ ▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌──────────────┐ ┌───────────────────┐
│ TrainingModel │ │PredictionModel│ │EvaluationMdl │ │ ExplanationModel │
│ (BaseModel) │ │ (BaseModel) │ │(BaseModel) │ │ (BaseModel) │
│ │ │ │ │ │ │ │
│ build_label → │ │ build_label → │ │ dispatch on │ │ explain → │
│ extract_feat →│ │ extract_feat →│ │ model.kind │ │ ExplainerEns. │
│ fit (N seeds) │ │ forecast │ │ evaluate/ │ │ plot → │
│ │ │ │ │ compare │ │ per-seed + │
│ │ │ │ │ │ │ waterfall │
└────────┬──────┘ └────────┬──────┘ └──────┬───────┘ └────────┬──────────┘
│ produces │ consumes │ uses │ reuses
▼ │ ▼ │
┌────────────────────────┐ │ ┌────────────────────────┐ │
│ ClassifierEnsemble │◄┘ │ MetricsEnsemble │ │
│ ─────────────────── │ │ • (n_samples ×ばつ n_seeds)│ │
│ • from_any / from_json│ │ y_proba / y_pred CSV │ │
│ • from_seed_ensembles │ │ • metrics in memory │ │
└──────────┬─────────────┘ └───────────┬────────────┘ │
│ bundles │ aggregates │
▼ ▼ ▼
┌────────────────────────┐ ┌────────────────────────┐ ┌──────────────────┐
│ SeedEnsemble ×ばつ M │ │ ClassifierComparator │ │ ExplainerEnsemble│
│ ───────────────────── │ │ • get_ranking() │ │ • TreeExplainer │
│ • predict_proba │ │ • plot_all() │ │ per seed │
│ • predict_with_ │ └────────────────────────┘ │ • ClassifierExpln│
│ uncertainty │ │ per classifier │
└──────────┬─────────────┘ └──────────────────┘
│ inherits
▼
┌─────────────────────────┐
│ BaseEnsemble │
│ (joblib save/load) │
└─────────────────────────┘
Scope cheat-sheet:
| Class | Scope (per ...) | Mixin / Inheritance | Cache |
|---|---|---|---|
BaseModel |
- | ABC (cache identity + dual-mode save/load) | self |
BaseEnsemble |
- | mixin | ✗ |
TrainingModel |
One date span | BaseModel |
✓ |
PredictionModel |
One forecast window grid | BaseModel |
✓ |
EvaluationModel |
One trained model | BaseModel |
✗ |
ExplanationModel |
One trained ensemble | BaseModel |
✓ |
SeedEnsemble |
1 classifier ×ばつ N seeds | BaseEnsemble |
✗ |
ClassifierEnsemble |
M classifiers ×ばつ N seeds | BaseEnsemble |
✗ |
MetricsEnsemble |
1 ensemble ×ばつ 1 dataset | standalone | ✗ |
ExplainerEnsemble |
1 ensemble ×ばつ 1 dataset | standalone | ✗ |
ClassifierComparator |
M classifiers, post-eval | standalone | ✗ |
ForecastModel |
Full pipeline | standalone orchestrator | via stages |
| Stage | Driver class | Reads | Writes |
|---|---|---|---|
| Tremor | CalculateTremor |
SeismicDataSource.get(date) |
tremor/daily/*.csv, merged {nslc}_{start}_{end}.csv
|
| Label | LabelBuilder |
Tremor index, eruption dates | training/features/{cv}/features-label_*.csv |
| Tremor matrix | TremorMatrixBuilder |
Tremor CSV + labels |
training/tremor/tremor_matrix_*.csv (+ per_method/) |
| Features | FeaturesBuilder |
Tremor matrix | training/features/{cv}/features-matrix_*.parquet |
| Feature selection | FeatureSelector |
Features + labels |
training/features/{cv}/seed/{seed:05d}.csv + top_N_features.csv
|
| Training fit | TrainingModel |
Selected features + labels |
training/classifiers/{clf}/{cv}/models/*.pkl + SeedEnsemble_*.pkl + ClassifierEnsemble_*.{pkl,json}
|
| Prediction grid | PredictionModel |
Tremor CSV + window grid | prediction/features/features-{matrix,label}_*.csv |
| Forecast | PredictionModel.forecast |
Forecast features + ensemble |
prediction/results/{clf}/{seed:05d}.csv + forecast-results_*.csv + prediction/figures/forecast_*.{png,pdf}
|
| Evaluation | EvaluationModel.evaluate |
y_proba + y_true |
evaluation/{kind}/classifiers/{Clf}/predictions/{y_proba,y_pred}.csv + figures/aggregate/{plot}.{png,csv} + (when plot_per_seed=True) figures/{plot}/{seed:05d}.png
|
| Compare | ClassifierComparator |
Cached MetricsEnsemble
|
evaluation/{kind}/comparison/metrics/ranking_*.csv + comparison/figures/*.png
|
| Explanation | ExplanationModel.explain |
ClassifierEnsemble + features |
explanation/{kind}/classifiers/{Clf}/ClassifierExplanation_*.pkl + shap_values/{seed:05d}.pkl + figures/{bar,beeswarm}/{seed:05d}.png
|
| Waterfalls | ExplainerEnsemble.plot_waterfall |
ClassifierExplanation + eruption dates |
explanation/{kind}/eruptions/{date}/{Clf}_{datetime}_seed=_index=.png |
×ばつ n_seeds) │ │ figures/aggregate/{plot_name}.{png,csv} │ │ figures/{plot_name}/{seed:05d}.png (plot_per_seed=True) │ │ labels/y_true.csv (prediction reuse only)│ │ MetricsEnsemble.pkl (optional, via save()) │ │ comparison/ │ │ metrics/ranking_*.csv │ │ figures/*.png │ └─────────┬─────────────────────────────────────────────────────┘ │ ClassifierEnsemble + features ▼ ┌───────────────────────────────────────────────────────────────┐ │ explanation/{training|prediction}/ │ │ classifiers/{Clf}/ │ │ ClassifierExplanation_{Clf}.pkl │ │ shap_values/{seed:05d}.pkl │ │ figures/{bar,beeswarm}/{seed:05d}.png │ │ eruptions/{YYYY-MM-DD}/ │ │ {Clf}_{datetime}_seed=_index=.png │ └───────────────────────────────────────────────────────────────┘ ┌────────────────────────────────────────────────────────────┐ │ Stage-internal caches (no separate cache/ subtree): │ │ training/{hash}.TrainingModel.pkl + .params.json │ ← BaseModel.save │ prediction/{hash}.PredictionModel.pkl + .params.json │ │ explanation/{kind}/{hash}.ExplanationModel.pkl + sidecar│ └────────────────────────────────────────────────────────────┘">
┌────────────────────────────────────────┐
│ tremor/{nslc}_{start}_{end}.csv │ ← CalculateTremor
└─────────┬──────────────────────────────┘
│ used by Training / Prediction / Evaluation
▼
┌───────────────────────────────────────────────────────────────┐
│ training/ │
│ features/{cv}/ │
│ features-matrix_*.parquet ──► features-label_*.csv │
│ │ │
│ ▼ │
│ seed/{seed:05d}.csv ──► resampled/{seed:05d}.csv │
│ significant_features.csv ──► top_features.csv │
│ ──► top_{N}_features.csv + .png │
│ │
│ classifiers/ │
│ {clf}/{cv}/models/{seed:05d}.pkl │
│ {clf}/{cv}/SeedEnsemble_*.pkl │
│ ClassifierEnsemble_{cv}.{pkl,json} │
└─────────┬─────────────────────────────────────────────────────┘
│ ClassifierEnsemble bundle
▼
┌───────────────────────────────────────────────────────────────┐
│ prediction/ │
│ features/features-matrix_*.parquet + features-label_*.csv │
│ results/{clf}/{seed:05d}.csv │
│ figures/forecast_*.{png,pdf} │
│ forecast-results_*.csv (top-level dump) │
└─────────┬─────────────────────────────────────────────────────┘
│ ClassifierEnsemble + features + y_true (rebuilt or training-derived)
▼
┌───────────────────────────────────────────────────────────────┐
│ evaluation/{training|prediction}/ │
│ classifiers/{Clf}/ │
│ predictions/{y_proba,y_pred}.csv (n_samples ×ばつ n_seeds) │
│ figures/aggregate/{plot_name}.{png,csv} │
│ figures/{plot_name}/{seed:05d}.png (plot_per_seed=True) │
│ labels/y_true.csv (prediction reuse only)│
│ MetricsEnsemble.pkl (optional, via save()) │
│ comparison/ │
│ metrics/ranking_*.csv │
│ figures/*.png │
└─────────┬─────────────────────────────────────────────────────┘
│ ClassifierEnsemble + features
▼
┌───────────────────────────────────────────────────────────────┐
│ explanation/{training|prediction}/ │
│ classifiers/{Clf}/ │
│ ClassifierExplanation_{Clf}.pkl │
│ shap_values/{seed:05d}.pkl │
│ figures/{bar,beeswarm}/{seed:05d}.png │
│ eruptions/{YYYY-MM-DD}/ │
│ {Clf}_{datetime}_seed=_index=.png │
└───────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────┐
│ Stage-internal caches (no separate cache/ subtree): │
│ training/{hash}.TrainingModel.pkl + .params.json │ ← BaseModel.save
│ prediction/{hash}.PredictionModel.pkl + .params.json │
│ explanation/{kind}/{hash}.ExplanationModel.pkl + sidecar│
└────────────────────────────────────────────────────────────┘
A cache hit on TrainingModel short-circuits everything in the training/ box;
a cache hit on PredictionModel short-circuits the prediction/ box;
a cache hit on ExplanationModel short-circuits the per-classifier SHAP pass.
Evaluation is never cached - the on-disk matrices act as the cache and MetricsEnsemble.compute() is idempotent in memory once y_probas is populated.
| Module | Key functions |
|---|---|
utils/array.py |
detect_maximum_outlier, remove_maximum_outlier, remove_outliers, detect_anomalies_zscore, mask_zero_values, filter_nans, count_valid_values, get_completeness, confidence_interval, compute_model_probabilities, save_forecast_seed
|
utils/benchmark.py |
benchmark_feature_selection (side-by-side FeatureSelector method comparison) |
utils/window.py |
construct_windows, calculate_window_metrics, get_windows_information, chunk_daily_data, shannon_entropy, to_safe_array
|
utils/date_utils.py |
to_datetime, normalize_dates, sort_dates, parse_label_filename, to_datetime_index
|
utils/ml.py |
random_under_sampler, resample, load_features_resampled, temporal_train_test_split, get_significant_features, get_classifier_models, grid_search_cv, save_model_json, compute_seed, build_y_true, build_classifier_ensemble_summary, compute_threshold_metrics, compute_aggregate_threshold_metrics
|
utils/validation.py |
validate_random_state, validate_date_ranges, validate_window_step, validate_columns, check_sampling_consistency
|
utils/pathutils.py |
pdf_metadata, resolve_output_dir, ensure_dir, save_figure, save_figure_as_pdf, save_data, load_json, load_pickle, setup_nslc_directories, generate_features_filepaths
|
utils/dataframe.py |
load_label_csv, load_datetime_indexed, load_select_features, load_feature_aliases, update_top_features_csv, concat_features, concat_significant_features, find_common_features, plot_common_features_heatmap, plot_common_features_correlation, get_envelope_values, remove_anomalies, to_series
|
utils/formatting.py |
slugify, slugify_class_name, shorten_feature_name, humanize_feature_name, get_classifier_label
|
utils/ml.save_model_json writes the per-classifier trained-model JSON registry (one record per seed, each with the inline top-N feature list and the path to the seed's .pkl). TrainingModel.build_seed_ensemble reads that registry via SeedEnsemble.from_any to package every seed into a SeedEnsemble, and the per-classifier SeedEnsembles are then merged into a ClassifierEnsemble (build_classifier_ensemble). All three steps run at the end of TrainingModel.fit().
utils/formatting.slugify is what turns "Scenario 1" into scenario-1 for the per-scenario output_dir used in scenarios.py.