DPMA: A a Dual-Parameter Molchan Alarm framework for Spatial Earthquake Forecasting in the Alborz Region, Northern Iran

A high-performance, modular Python pipeline for earthquake catalog processing, completeness magnitude ($M_c$) estimation, spatial $b$-value mapping, ETAS Zhuang stochastic declustering, spatial background rate ($\mu$) estimation, Molchan alarm evaluation (Probability Gain $PG$ and Molchan $PD$), and ESRI Shapefile export for prospective forecasting.

---

🌟 Key Features

• Centralized JSON Configuration: Full control over dataset paths, spatial grid resolutions, ETAS declustering parameters, evaluation windows, and forecast scenarios via Configuration_Parameters.json.
• Completeness Magnitude ($M_c$) Stability: Integrated Maximum Curvature (MAXC) and Goodness-of-Fit (GFT) estimators with automatic sample-size validation.
• Spatial $b$-Value Mapping: Aki-Utsu Maximum Likelihood Estimation (MLE) with Shi & Bolt standard error bounds using spatial $k$-d trees.
• Stochastic Declustering: Zhuang ETAS likelihood optimization with optional Numba JIT acceleration and iterative background probability ($\phi$) calculation.
• Prospective Forecasting & Molchan Evaluation: Probability Gain ($PG$), Molchan $PD$ improvement calculation, and dual-threshold optimization.
• GIS Shapefile Export: Automatic generation of polygon alarm grid shapefiles (.shp, .dbf, .shx, .prj) for GIS integration.

---

📁 Repository Structure

ACTA_DL/
├── Configuration_Parameters.json  # Main JSON configuration file
├── README.md                      # Project documentation and usage guide
├── environment.yml                # Conda environment specification
├── requirements.txt               # Pip dependency list
├── main.py                        # Central CLI execution script
│
├── config/                        # Configuration parser module
│   └── config_parser.py
│
├── data/                          # Data directory
│   ├── input/                     # Raw and input earthquake catalog CSV files
│   │   └── 1_28877083600.csv
│   └── output/                    # Generated figures, tables, maps, and GIS shapefiles
│
└── src/                           # Modular source package
    ├── __init__.py
    ├── data_loader.py             # Data ingestion, column mapping, and grid generation
    ├── mc_estimation.py           # Mc calculation and validation routines
    ├── b_value.py                 # Aki-Utsu MLE b-value spatial mapping
    ├── zhuang_declustering.py     # Numba ETAS optimization & background rate (mu) estimation
    ├── forecasting.py             # Alarm threshold sweeps, PG/PD metrics & prospective predictions
    ├── shapefile_exporter.py      # GeoPandas shapefile polygon exporter
    └── visualization.py           # Publication-ready figure and map rendering

---

🔄 Processing Workflow

flowchart TD
    A[Earthquake Catalog CSV] --> B[src/data_loader.py]
    B --> C[Spatial Grid Construction]
    C --> D[src/mc_estimation.py<br/>Mc MAXC + GFT Validation]
    D --> E[src/b_value.py<br/>Aki-Utsu Spatial b-value Map]
    D --> F[src/zhuang_declustering.py<br/>Numba ETAS Log-Likelihood]
    F --> G[Iterative Zhuang Stochastic Declustering]
    G --> H[Spatial Background Rate μ Grid]
    E & H --> I[src/forecasting.py<br/>Molchan Sweeps & PG / PD Metrics]
    I --> J[src/shapefile_exporter.py<br/>GIS Shapefiles .shp]
    I --> K[src/visualization.py<br/>Publication Figures 2, 3, 4, 5]

Loading

---

⚙️ Configuration File (Configuration_Parameters.json)

All operational parameters are maintained in Configuration_Parameters.json. Example structure:

{
  "Project": "ACTA_DL_Seismicity",
  "Version": "1.0.0",
  "InputData": {
    "csv_path": "data/input/1_28877083600.csv",
    "output_dir": "data/output",
    "column_mapping": {
      "longitude": ["longitude", "lon", "lng", "x"],
      "latitude": ["latitude", "lat", "y"],
      "magnitude": ["magnitude", "mag", "m"],
      "time": ["time", "date", "datetime", "origin_time", "origintime"],
      "depth": ["depth", "z"]
    }
  },
  "GridParameters": {
    "grid_res": 0.5
  },
  "BValueParameters": {
    "nearest_N": 100,
    "min_events_for_b": 10,
    "b_value_min": 0.2,
    "b_value_max": 2.0,
    "b_radius_deg": 0.7,
    "bin_width_mc": 0.1
  },
  "ZhuangDeclustering": {
    "np_min_for_mu": 3,
    "eps_min": 0.03,
    "max_iter_mu": 6,
    "time_cut_days": 7,
    "space_cut_deg": 1.0
  },
  "AnalysisWindows": [
    {
      "train_start": 2006,
      "train_end": 2015,
      "forecast_start": 2015,
      "forecast_end": 2024
    },
    {
      "train_start": 2015,
      "train_end": 2024,
      "forecast_start": null,
      "forecast_end": null
    }
  ],
  "ForwardPredictions": [
    {
      "name": "2025-2029",
      "train_period": [2020, 2024],
      "forecast_period": [2025, 2029],
      "coefficients": [0.86]
    }
  ],
  "ForecastEvaluation": {
    "mag_thresholds": [5.0, 5.5],
    "mag_max": 8.0,
    "fig4_mag_min": 5.0,
    "fig4_mag_max": 7.0,
    "fig4_mag_step": 0.1
  }
}

---

🛠️ Installation & Environment Setup

Option 1: Conda (Recommended)

Create and activate the dedicated acta_dl conda environment:

conda env create -f environment.yml
conda activate acta_dl

Option 2: Pip

Installs required dependencies directly:

pip install -r requirements.txt

---

🚀 Usage

To execute the complete analysis pipeline using the default configuration file:

conda run -n acta_dl python main.py --config Configuration_Parameters.json

Or directly in the active environment:

python main.py --config Configuration_Parameters.json

---

📊 Outputs & Generated Artifacts

Results are automatically structured inside data/output/:

• Spatial Maps (.png):
  • map_2006-2015_2015-2024.png: Spatial distributions of $b$-value and background rate $\mu$.
  • figure3_*.png: Molchan diagrams, Probability Gain curves, and $PD$ metrics.
  • figure4_*.png: PG & PD performance as a function of target magnitude.
  • figure5_*.png: 3D surfaces of $PG$ and $PD$ across dual threshold spaces.
  • output5_combined_maps_*.png: Combined alarm region maps overlay.
• GIS Shapefiles (.shp, .dbf, .shx, .prj):
  • output5_alarm_regions_*_alarm_b.shp: High-risk zones filtered by $b$-value.
  • output5_alarm_regions_*_alarm_mu.shp: High-risk zones filtered by background rate $\mu$.
  • output5_alarm_regions_*_alarm_combined.shp: Combined high-risk alarm zones.
• Data & Statistical Summaries (.json, .csv):
  • b_mu_grid_*.csv: Grid cell coordinates with calculated $b$, $\sigma_b$, and $\mu$.
  • output5_detailed_*.json: Full numerical summary table (Threshold, $\tau$, $\nu$, $PG$, $PD$).
  • all_forward_predictions_summary.json: Summary of forward prospective predictions.

---

📜 Citation & License

This codebase is licensed under the MIT License.