Complete Workflows#

This guide provides complete, step-by-step workflows for earthquake forecasting using PyEEPAS. The tutorial uses the Italy earthquake catalog as an example, but the same workflow can be applied to any seismic region.

Tutorial Example Workflow#

Italy Earthquake Forecasting#

This tutorial demonstrates the complete PyEEPAS workflow using the Italy (CPTI15) earthquake catalog.

Overview#

This workflow demonstrates:

Magnitude anchoring with --ppe-ref-mag mT option
Three-stage optimization for complex parameter spaces
Handling larger spatial grids (177 cells)
Best practices for edge effect management (separate testing/neighborhood regions)

Step-by-Step Execution#

Step 1: PPE Learning

python3 ppe_learning.py --config config_italy_reproduce.json

Expected Output:

Spatial region configuration:
  Testing Region: grid (177 cells)
  Neighborhood Region: polygon (CPTI15)
PPE historical events (CatJ): 312, target events (CatI): 27

✅ Saved: results_italy_reproduce/Fitted_par_PPE_1990_2012.csv
   a=0.616, d=29.64, s≈0

Step 2: Aftershock Fitting

python3 fit_aftershock_params.py \
    --config config_italy_reproduce.json \
    --ppe-ref-mag mT \
    --target-mag mT

Expected Output:

✅ Saved: results_italy_reproduce/Fitted_par_aftershock_1990_2012.csv
   v=0.577, k=0.205

Step 3: EEPAS Learning

python3 eepas_learning_auto_boundary.py \
    --config config_italy_reproduce.json \
    --three-stage \
    --ppe-ref-mag mT \
    --max-rounds 1

Expected Output:

🔄 Stage 1: Optimize am, at, Sa, u
   Fixed parameters: bm=1.00, Sm=0.32, bt=0.40, St=0.23, ba=0.35
   ...
   ✅ Stage 1 completed

🔄 Stage 2: Optimize Sm, bt, St, ba, u
   🎯 Using multi-start search (3 starting points) + Stage 3 quick evaluation
   ...
   ✅ Stage 2 completed

🔄 Stage 3: Joint optimization of all parameters
   ...
   ✅ Stage 3 completed
   Final NLL: 495.394994

✅ Saved: results_italy_reproduce/Fitted_par_EEPAS_1990_2012.csv

Step 4: PPE Forecast

python3 ppe_make_forecast.py \
    --config config_italy_reproduce.json \
    --ppe-ref-mag mT

Step 5: EEPAS Forecast

python3 eepas_make_forecast.py \
    --config config_italy_reproduce.json \
    --ppe-ref-mag mT

Complete Italy Workflow Script#

Save as run_italy_workflow.sh:

#!/bin/bash
# EEPAS Italy Workflow (Reproduce Published Results)

set -e

echo "=== EEPAS Italy Workflow ==="
echo "Configuration: config_italy_reproduce.json"
echo "Mode: Reproduce Biondini et al. (2023) results"
echo ""

# Step 1: PPE Learning
echo "Step 1/5: PPE Learning..."
python3 ppe_learning.py --config config_italy_reproduce.json

# Step 2: Aftershock Parameters (mT anchor)
echo "Step 2/5: Aftershock Parameters..."
python3 fit_aftershock_params.py \
    --config config_italy_reproduce.json \
    --ppe-ref-mag mT \
    --target-mag mT

# Step 3: EEPAS Learning (3-stage, single round)
echo "Step 3/5: EEPAS Learning (3-stage)..."
python3 eepas_learning_auto_boundary.py \
    --config config_italy_reproduce.json \
    --three-stage \
    --ppe-ref-mag mT \
    --max-rounds 1

# Step 4: PPE Forecast
echo "Step 4/5: PPE Forecast..."
python3 ppe_make_forecast.py \
    --config config_italy_reproduce.json \
    --ppe-ref-mag mT

# Step 5: EEPAS Forecast
echo "Step 5/5: EEPAS Forecast..."
python3 eepas_make_forecast.py \
    --config config_italy_reproduce.json \
    --ppe-ref-mag mT

# Step 6: Archive Results (Optional)
echo "Step 6/6: Archiving Results..."
python3 archive_results.py \
    --config config_italy_reproduce.json \
    --results-dir results_italy_reproduce/ \
    --workflow "EEPAS 5-step workflow" \
    --logs step1_ppe.log step2_aftershock.log step3_eepas.log step4_ppe_forecast.log step5_eepas_forecast.log \
    --ppe-ref-mag mT \
    --target-mag mT \
    --three-stage \
    --max-rounds 1

echo ""
echo "=== Workflow Complete! ==="
echo "Results saved in: results_italy_reproduce/"
ls -lh results_italy_reproduce/

End-to-End Automated Pipeline#

This workflow uses config_italy_endtoend.json for a fully automated pipeline with wider optimization boundaries and automatic boundary adjustment (Section 5.2 of the manuscript).

Key differences from the reproduce-published workflow:

m0 = 2.95 (vs 2.45)
bM = 0.764 fixed (vs 1.0)
Aftershock fitting uses --target-mag m0 (not mT)
Auto boundary adjustment with up to 3 rounds

CONFIG=config_italy_endtoend.json

# Step 1: PPE Learning
python3 ppe_learning.py --config $CONFIG --ppe-ref-mag mT

# Step 2: Aftershock Parameters (target-mag m0)
python3 fit_aftershock_params.py --config $CONFIG --ppe-ref-mag mT --target-mag m0

# Step 3: EEPAS Learning (auto boundary, up to 3 rounds)
python3 eepas_learning_auto_boundary.py --config $CONFIG --three-stage --ppe-ref-mag mT

# Step 4: PPE Forecast
python3 ppe_make_forecast.py --config $CONFIG --ppe-ref-mag mT

# Step 5: EEPAS Forecast
python3 eepas_make_forecast.py --config $CONFIG --ppe-ref-mag mT

# Step 7: Verify Forecasts
python3 analysis/verify_forecasts.py \
    --catalog analysis/HORUS_Italy_filtered.mat \
    --source-crs EPSG:7794 \
    $CONFIG

Expected results (Table 2 in manuscript):

NLL = -484.23
aM=3.474, σM=0.308, aT=-1.604, bT=1.200, σT=0.618
bA=1.509, σA=0.010, μ=0.395

Applying to Your Region#

General Workflow Steps#

To apply PyEEPAS to your own seismic region, follow these steps:

Prerequisites

Prepare Data Files:
- Earthquake catalog (.mat format):
  
  Variable name flexible (e.g., HORUS, catalog), matrix format (N_events × 10):
```
Column 1-6:  Date/time (Year, Month, Day, Hour, Minute, Second)
Column 7:    Latitude (degrees N)
Column 8:    Longitude (degrees E)
Column 9:    Depth (km)
Column 10:   Magnitude
```
  See data/README.md for detailed format specification.
- Testing region grid (.mat format):
  
  Variable name flexible (e.g., CELLESD), matrix format (N_cells × 10):
```
Column 1-4:  Grid bounds (lon_min, lon_max, lat_min, lat_max)
Column 5-8:  Reserved/unused
Column 9:    Cell identifier (integer)
Column 10:   Reserved
```
  Only columns 1-4 are used for defining rectangular grid cells.
- Neighborhood region (.mat format):
  
  Grid format (same as testing region): N_cells × 10 matrix
  
  Polygon format: N_vertices × 2 or N_vertices × 4 matrix
```
Columns 1-2: (lon, lat) coordinates of polygon vertices
Columns 3-4: (optional) projected coordinates
```
  Important: Polygon vertices must be in clockwise order with no repetitions. The neighborhood region must strictly contain the testing region to avoid boundary effects (truncation of precursor events outside R that may influence target events near the edge).

Create Configuration File:

Copy config_italy_reproduce.json and modify for your region:

{
  "resultsDir": "results_yourregion",
  "catalogStartYear": YYYY,
  "learnStartYear": YYYY,
  "learnEndYear": YYYY,
  "forecastStartYear": YYYY,
  "forecastEndYear": YYYY,
  "inputFiles": {
    "catalogFile": "your_catalog.mat",
    "neighborhoodRegionFile": "your_neighborhood.mat",
    "testingRegionFile": "your_testing.mat"
  },
  "modelParams": {
    "m0": 2.5,
    "mT": 5.0,
    "B": 1.036
  }
}

Workflow Execution

Run the same 5-step workflow with your configuration:

# Step 1: PPE Learning
python3 ppe_learning.py --config config_yourregion.json

# Step 2: Aftershock Parameters
python3 fit_aftershock_params.py \
    --config config_yourregion.json \
    --ppe-ref-mag mT \
    --target-mag mT

# Step 3: EEPAS Learning (3-stage optimization)
python3 eepas_learning_auto_boundary.py \
    --config config_yourregion.json \
    --three-stage \
    --ppe-ref-mag mT \
    --max-rounds 1

# Step 4: PPE Forecast
python3 ppe_make_forecast.py \
    --config config_yourregion.json \
    --ppe-ref-mag mT

# Step 5: EEPAS Forecast
python3 eepas_make_forecast.py \
    --config config_yourregion.json \
    --ppe-ref-mag mT

Batch Processing#

To process multiple configurations or scenarios:

#!/bin/bash
# Batch process multiple configurations

CONFIGS=(
    "config_region1.json"
    "config_region2.json"
    "config_different_m0.json"
)

for config in "${CONFIGS[@]}"; do
    echo "========================================="
    echo "Processing: $config"
    echo "========================================="

    python3 ppe_learning.py --config "$config"
    python3 fit_aftershock_params.py --config "$config" --ppe-ref-mag mT --target-mag mT
    python3 eepas_learning_auto_boundary.py --config "$config" --three-stage --ppe-ref-mag mT --max-rounds 1
    python3 ppe_make_forecast.py --config "$config" --ppe-ref-mag mT
    python3 eepas_make_forecast.py --config "$config" --ppe-ref-mag mT

    echo "Completed: $config"
    echo ""
done

echo "All configurations processed!"

Advanced Workflows#

Accurate Mode (Final Verification)#

For publication or final verification, use accurate mode instead of fast mode:

# PPE Learning (dblquad integration)
python3 ppe_learning.py --config config.json --accurate

# Aftershock Fitting (accurate mode)
python3 fit_aftershock_params.py --config config.json --accurate

# EEPAS Learning (accurate mode)
python3 eepas_learning_auto_boundary.py --config config.json --accurate

# PPE Forecast (accurate mode)
python3 ppe_make_forecast.py --config config.json --accurate

# EEPAS Forecast (accurate mode)
python3 eepas_make_forecast.py --config config.json --accurate

Warning

Accurate mode is significantly slower than fast mode, but provides < 0.2% difference in results.

Custom Magnitude Threshold#

Override completeness magnitude (m0):

python3 eepas_learning_auto_boundary.py \
    --config config.json \
    --m0 2.05

Custom Optimization Parameters#

Adjust optimization behavior:

# Increase maximum boundary adjustment rounds
python3 eepas_learning_auto_boundary.py \
    --config config.json \
    --max-rounds 5 \
    --tolerance 0.01

# Use specific optimizer
python3 eepas_learning_auto_boundary.py \
    --config config.json \
    --no-multistart

Verification#

Verify Results#

After workflow completion, verify outputs exist:

# Check all output files
ls -lh results/Fitted_par_PPE_*.csv
ls -lh results/Fitted_par_aftershock_*.csv
ls -lh results/Fitted_par_EEPAS_*.csv
ls -lh results/PREVISIONI_3m_PPE_*.mat
ls -lh results/PREVISIONI_3m_EEPAS_*.mat

Check Parameter Values#

# PPE parameters
cat results_yourregion/Fitted_par_PPE_*.csv

# EEPAS parameters
cat results_yourregion/Fitted_par_EEPAS_*.csv

Validate Forecast Lambda Sum#

Use the analysis tool to verify forecast correctness:

python3 analysis/analyze_forecast_lambda.py

Archive Workflow Results#

Archive configuration and logs for reproducibility:

python3 archive_results.py \
    --config config_yourregion.json \
    --results-dir results_yourregion/ \
    --workflow "EEPAS complete workflow" \
    --logs step*.log \
    --ppe-ref-mag mT \
    --target-mag mT

This saves:

config_used.json: Configuration snapshot
execution_info.txt: Execution metadata
execution.log: Combined logs
README_REPRODUCE.md: Reproduction guide

Next Steps#

Configuration Reference - Customize configuration files
Interpreting Results - Interpret forecast results
API Reference - API documentation

Complete Workflows

Contents

Complete Workflows#

Tutorial Example Workflow#

Italy Earthquake Forecasting#

Overview#

Step-by-Step Execution#

Complete Italy Workflow Script#

End-to-End Automated Pipeline#

Applying to Your Region#

General Workflow Steps#

Batch Processing#

Advanced Workflows#

Accurate Mode (Final Verification)#

Custom Magnitude Threshold#

Custom Optimization Parameters#

Verification#

Verify Results#

Check Parameter Values#

Validate Forecast Lambda Sum#

Archive Workflow Results#

Next Steps#