-
Notifications
You must be signed in to change notification settings - Fork 0
Home
Martanto edited this page Jul 17, 2026
·
11 revisions
A Python package for volcanic eruption forecasting from continuous seismic tremor and machine-learning ensembles.
eruption-forecast produces probabilistic eruption likelihoods, not deterministic warnings.
It is a research tool and must not be used as the sole basis for public safety decisions. Always consult qualified volcanologists and official observatory bulletins.
| # | Page | Description |
|---|---|---|
| 1 | Getting Started | Prerequisites, installation, dev commands |
| 2 | Data Sources | SDS archive layout, FDSN web service, local caching |
| 3 | Usage | Quick Start + annotated end-to-end example |
| 4 | Pipeline Walkthrough | Research Workflow (main.py) + Scenarios Workflow (scenarios.py) |
| 5a | Training Workflow |
TrainingModel, classifiers, CV, imbalance, parallelism |
| 5b | Prediction Workflow |
PredictionModel, forecast outputs, consensus |
| 5c | Evaluation Workflow |
EvaluationModel, MetricsEnsemble, ClassifierComparator
|
| 5d | Explanation Workflow |
ExplanationModel, ExplainerEnsemble, per-seed SHAP |
| 6 | Visualization | Plot catalog + output paths |
| 7 | Configuration |
ForecastConfig, YAML save/replay, Telegram, logging |
| 8 | Output Structure | Full directory tree + slug conventions |
| 9 | Architecture | Package layout, class relationships, data flow |
| 10 | API Reference | Constructor + method parameter tables |
| Feature Count Sweep |
Experimental — post-hoc top_n_features recommender (ft/feature-count-sweep) |
×ばつ M seeds) │ ┌────────┴────────┐ ▼ ▼ ┌───────────────────┐ ┌──────────────────────┐ │ PredictionModel │ │ EvaluationModel │ (n_samples ×ばつ n_seeds) │ forecast grid → │ │ MetricsEnsemble + │ y_proba / y_pred CSVs │ probabilities │ │ ClassifierComparator│ aggregate plots └─────────┬─────────┘ └──────────┬───────────┘ │ │ └───────────┬───────────┘ ▼ ┌───────────────────────────┐ │ ExplanationModel │ per-classifier SHAP │ ExplainerEnsemble → │ TreeExplainer-only │ per-seed bar/beeswarm + │ (rf, lite-rf, gb, xgb) │ per-eruption waterfall │ └───────────────────────────┘">
Raw Seismic (SDS / FDSN)
│
▼
┌───────────────────────┐
│ CalculateTremor │ RSAM + DSAR + Shannon Entropy
└──────────┬────────────┘ per frequency band
│
▼
┌───────────────────────┐
│ TrainingModel │ LabelBuilder → FeaturesBuilder → fit
│ (BaseModel) │ multi-seed GridSearchCV
│ │ produces ClassifierEnsemble
└──────────┬────────────┘
│ ClassifierEnsemble (N classifiers ×ばつ M seeds)
│
┌────────┴────────┐
▼ ▼
┌───────────────────┐ ┌──────────────────────┐
│ PredictionModel │ │ EvaluationModel │ (n_samples ×ばつ n_seeds)
│ forecast grid → │ │ MetricsEnsemble + │ y_proba / y_pred CSVs
│ probabilities │ │ ClassifierComparator│ aggregate plots
└─────────┬─────────┘ └──────────┬───────────┘
│ │
└───────────┬───────────┘
▼
┌───────────────────────────┐
│ ExplanationModel │ per-classifier SHAP
│ ExplainerEnsemble → │ TreeExplainer-only
│ per-seed bar/beeswarm + │ (rf, lite-rf, gb, xgb)
│ per-eruption waterfall │
└───────────────────────────┘
The high-level ForecastModel class chains every stage with a fluent API:
from eruption_forecast import ForecastModel ( ForecastModel(station="OJN", channel="EHZ", network="VG", location="00", day_to_forecast=2, n_jobs=4) .calculate(start_date="2025-01-01", end_date="2025-12-31", source="sds", sds_dir="/data/sds") .train(start_date="2025-01-01", end_date="2025-07-26", eruption_dates=["2025-03-20", "2025-04-22", "..."], window_step=6, window_step_unit="hours", classifiers=["rf", "xgb"], seeds=25) .predict(start_date="2025-07-27", end_date="2025-08-22", window_step=10, window_step_unit="minutes", plot_threshold=0.7) .evaluate(model="prediction") .explain(model="prediction", plot_per_seed=True) )
eruption-forecast/
├── src/eruption_forecast/ Package source (74 .py files)
├── wiki/ This wiki (Markdown sources)
├── tests/ Unit tests
├── main.py Research Workflow - single train + predict
├── scenarios.py Scenarios Workflow - loop over date-split scenarios
├── config.example.yaml Annotated ForecastConfig template
├── CLAUDE.md Project rules and architecture cheatsheet
└── WIKI.md Local wiki-rewrite progress tracker