ProbShakeRank

Probabilistic GMM ranking with explicit source uncertainty propagation

ProbShakeRank is a Python workflow for ranking Ground Motion Models (GMMs) against observed seismic records (PGA, PGV, SA). Unlike traditional ranking approaches, it explicitly quantifies and propagates earthquake source uncertainty (magnitude, hypocenter location, strike/dip/rake) into the ranking process. This enables dynamic updating of GMM performance as source characterization improves, making ProbShakeRank suitable for quasi-real-time applications.

The workflow is built on top of ProbShakemap (Stallone et al., 2025) and extends it with:

1. Automatic retrieval of event information from the Engineering Strong Motion (ESM) database (Luzi et al., 2016)
2. GMM performance evaluation using multiple ranking metrics:
   • Parametric and KDE Log-likelihood score (LLH)
   • Parametric and KDE parimutuel Gambling Score (PGS)
   • Multi-IM average KDE-LLH score
3. An interactive dashboard for exploring ranking results

Reference article: "Dynamic ranking of Ground Motion Models (GMMs) accounting for source uncertainty" (Stallone et al., coming soon)

---

Table of Contents

• Workflow
• Installation
• Input Configuration
• Dynamic ranking update with scenario weights
• Run the example
• Output Structure
• Dashboard
• Dependencies
• Citation

---

Workflow

1. Download strong-motion data from the ESM database
2. Generate an ensemble of rupture scenarios with SeisEnsMan
3. Run ProbShakemap to compute predictive ground-motion distributions at recording stations
4. Rank GMMs using parametric/KDE LLH and PGS
5. Launch interactive dashboard

See the scripts in example/emilia_2012/ for workflow examples.

---

Installation

1. Clone the repository

git clone https://github.com/INGV/ProbShakeRank.git
cd ProbShakeRank

2. Set up the Conda environment

conda env create -f probshakerank_environment.yml
conda activate probshakerank

3. Set up SeisEnsMan

(skip this step if source scenarios already exist or are generated independently)

Follow the installation instructions in the ProbShakemap repository.

---

Input Configuration

Example workflow input parameters

Parameter	Description	Example
IMT	Intensity measure type	PGA, PGV, SA
T	SA period (ESM format)	1_000 (SA 1.0 s)
EV_ID	ESM event ID	IT-2012-0011
FAULT_MULTIPLIER	Station distance scaling factor	1
STATIONS_MAX_DIST	Max station distance (km)	20
N_SCENS	Number of rupture scenarios	1000
NUM_GMFs	Number of realizations per scenario per GMM	20
DOWNLOAD_DATA	Download (True) or reuse data (False)	false
BOOTSTRAP_SAMPLES	Number of bootstrap samples	100

INPUT_FILES/gmpes.conf — GMM configuration

Defines the sets of GMMs to rank and their associated horizontal components. Each GMM is identified by an acronym and mapped to its OpenQuake GSIM class name.

input_file.txt — ProbShakemap configuration

Parameter	Description
TectonicRegionType	Tectonic regime (e.g., Active Shallow Crust)
Magnitude_Scaling_Relationship	Magnitude scaling relation (e.g., WC1994)
Rupture_aratio	Rupture aspect ratio
Vs30file	Path to Vs30 grid file (optional; defaults to 760 m/s)
CorrelationModel	Spatial correlation model (e.g., JB2009CorrelationModel)
CrosscorrModel	Cross-correlation model accepted for OpenQuake compatibility
truncation_level	Truncation level for ground-motion sampling
seed	Random seed for reproducibility

See ProbShakemap repository for more details.

Notes:

1. As for the Vs30file, an example file, global_italy_vs30_clobber.grd (Michelini et al., 2020), is available at this link. To run the packaged Emilia example without editing input_file.txt, place this file in example/emilia_2012/INPUT_FILES/vs30/.
2. CrosscorrModel is accepted for OpenQuake compatibility only, but cross-correlation among IMs is not used as, currently, the algorithm processes one IM at a time. The Multi-IM score is an average over IM-specific LLH-KDE contributions, not a joint multi-IM likelihood.

---

Dynamic ranking update with scenario weights

ProbShakeRank supports dynamic updates of GMM rankings by re-weighting rupture scenarios based on updated source information.

Scenario weights are computed using Kagan angle similarity and a decay factor BETA, following Cordrie et al. (2025) and implemented in pyPTF_data_update.

---

Run the example

This repository comes with the example folder example/emilia_2012/ for the Mw 6.0 Emilia-Romagna (northern Italy) earthquake of 29 May 2012. The subfolder OUTPUT contains outcomes for PGA only (except the heatmap) to keep the example lightweight.

Before running the example, make sure the Vs30 grid named in INPUT_FILES/input_file.txt is available in example/emilia_2012/INPUT_FILES/vs30/.

To run the main workflow:

cd example/emilia_2012
bash run_probshakerank.sh

To run weighted ranking:

cd example/emilia_2012
bash run_probshakerank_weights.sh

This skips data retrieval and ensemble generation, and directly updates:

• scenario weights (weights.txt)
• ground-motion distributions via ProbShakemap (--fileScenariosWeights)
• GMM ranking

Parameter	Description	Example
BETA	Decay factor controlling scenario weighting	5

---

Output Structure

All outputs are written to OUTPUT/<EV_ID>/:

OUTPUT/
└── <EV_ID>/
    ├── metadata.txt                               # Event Mw, time, coordinates
    ├── RANK/
    │   ├── LLH_Standard_Score_<IMT>.txt           # Per-GMM standard parametric LLH scores
    │   ├── LLH_KDE_Score_<IMT>.txt                # Per-GMM KDE non-parametric LLH scores
    │   ├── Gambling_Parametric_Score_<IMT>.txt    # Per-GMM parametric PGS scores
    │   ├── Gambling_KDE_Score_<IMT>.txt           # Per-GMM KDE non-parametric PGS scores
    │   ├── MultiIMs_LLH_KDE.txt                   # Multi-IM average KDE-LLH scores
    │   └── POI_ll_storage.npy                     # Accumulated per-site log-likelihoods (multi-IM)
    │   └── BOOTSTRAP/
    │       ├── Bootstrap_LLH_Standard_Score_<IMT>.txt/png
    │       ├── Bootstrap_LLH_KDE_Score_<IMT>.txt/png
    │       ├── Bootstrap_Gambling_Parametric_Score_<IMT>.txt/png
    │       └── Bootstrap_Gambling_KDE_Score_<IMT>.txt/png
    └── OUTPUT_<GMM>_<IMT>/
        ├── <IMT>_<GMM>_mean_total_stdev_scens_OQ.npy
        ├── <IMT>_<GMM>_mean_total_stdev_scens.npy
        ├── npyFiles/
        │   └── <IMT>_<GMM>_vector_stat.npy      # Mean and dispersion at all POIs
        ├── STATISTICS/
        │   ├── Stat_Mean.png                    # Spatial map of predicted mean
        │   └── Stat_Dispersion.png              # Spatial map of predicted dispersion
        ├── RANK_FIGURES/
        │   ├── Normalized_Residuals.png         # Pointwise residual map
        │   ├── Normalized_Residuals_Histogram.png
        │   ├── POI_LLH_Standard.png             # Pointwise standardized-residual LLH map
        │   ├── POI_LLH_KDE.png                  # Pointwise KDE LLH map
        │   ├── POI_Gambling_Parametric.png      # Pointwise parametric PGS contribution map
        │   └── POI_Gambling_KDE.png             # Pointwise KDE PGS contribution map
        └── LOGS/
            └── setup_<timestamp>.log

---

Dashboard

After the ranking completes, an interactive dashboard is launched automatically, which displays five tabs: Overview, Rankings, Maps, Residuals, and Run Info.

To relaunch the dashboard manually at any moment:

conda activate probshakerank
streamlit run src/dashboard.py

If launching it from inside the example folder, use the repository-level source path:

cd example/emilia_2012
streamlit run ../../src/dashboard.py

Example outputs

GMM ranking heatmap for the Emilia 2012 example (IMTs: PGA and SA(1.0s)):

Additional example figures:

• Dashboard main tabs
• Bootstrap LLH-KDE ranking uncertainty
• Normalized residual map for Lanzano et al. (2019)
• KDE pointwise log-likelihood map for Lanzano et al. (2019)

---

Dependencies

• OpenQuake hazardlib
• ProbShakemap

---

Citation

If you use ProbShakeRank in your research, please cite:

(Stallone et al., coming soon)
Dynamic ranking of Ground Motion Models (GMMs) accounting for source uncertainty

and the underlying ProbShakemap toolbox:

@article{stallone2025probshakemap,
  title={ProbShakemap: A Python toolbox propagating source uncertainty to ground motion prediction for urgent computing applications},
  author={Stallone, Angela and Selva, Jacopo and Cordrie, Louise and Faenza, Licia and Michelini, Alberto and Lauciani, Valentino},
  journal={Computers \& Geosciences},
  volume={195},
  pages={105748},
  year={2025},
  publisher={Elsevier}
}

---

Contact

Angela Stallone
Istituto Nazionale di Geofisica e Vulcanologia (INGV), Bologna, Italy
angela.stallone@ingv.it

---

License

This project is licensed under the terms described in LICENSE.txt.