Quake Statistics

An open-source Python toolkit for reproducible statistical analysis of earthquake inter-event times, depth sensitivity, and adjacent-magnitude dependence. It converts the original Sunda-region research notebook into a tested library and command-line workflow while retaining the notebook as the historical research record.

Scientific capabilities

• Validate and chronologically order earthquake catalogues.
• Calculate inter-event times in seconds, days, or fixed 30.5-day months.
• Compare disjoint regional and reference distributions with a two-sample KS test.
• Fit a zero-location Gamma model to positive inter-event times.
• Evaluate depth sensitivity and depth/time parameter surfaces as tidy tables.
• Test adjacent-magnitude dependence against a seeded shuffled-order null model.
• Report sample sizes, effect measures, null uncertainty, and empirical p-values.

Read SCIENTIFIC_METHOD.md before interpreting results. This tool is exploratory research software, not an earthquake forecast or official hazard assessment.

Install

git clone https://github.com/ZuhairQuakes/Statistical-Modelling.git
cd Statistical-Modelling
python -m venv .venv
source .venv/bin/activate
python -m pip install .

Python 3.10 or newer is required. On Windows PowerShell, activate the environment with .venv\Scripts\Activate.ps1.

Command-line example

The repository includes a small synthetic catalogue for testing the workflow; it is not observational evidence.

quake-stats compare examples/sample_catalog.csv \
  --start-date 1990-01-01 \
  --reference-mode complement \
  --output outputs/ks-comparison.json

quake-stats magnitude-dependence examples/sample_catalog.csv \
  --start-date 1990-01-01 \
  --time-thresholds 1,5,9 \
  --magnitude-thresholds 0.1,0.25,0.5,0.75 \
  --permutations 1000 \
  --seed 42 \
  --output outputs/magnitude-dependence.csv

Use quake-stats --help for all options.

Python example

import pandas as pd
from quake_statistics import compare_inter_event_times, depth_sensitivity

catalog = pd.read_csv("data/SUeq_data.csv")

comparison = compare_inter_event_times(
    catalog,
    minimum_magnitude=6.0,
    start_date="1976-01-01",
    region_min_latitude=-1.0,
)

depth_results = depth_sensitivity(
    catalog,
    depth_thresholds_km=[20, 30, 40, 50, 60, 70, 80, 90],
)

Input data

The required columns are:

Column	Meaning
DATE	Event origin date/time parseable by pandas; interpreted as UTC
MW	Moment magnitude
DEPTH	Hypocentral depth in kilometres
LAT	Latitude in decimal degrees

The original catalogue is not distributed. See data/README.md for provenance and completeness requirements.

Historical notebook

stats3_Sunda.ipynb contains the exploratory analysis that motivated this package. Its randomisation cell is preserved for provenance, but it has no fixed seed and contains ambiguous shuffled-variable logic. Use the tested magnitude_dependence function for new scientific work.

Repository map

Path	Purpose
src/quake_statistics/	reusable validated analysis library and CLI
tests/	deterministic unit and command-line tests
examples/	synthetic catalogue and executable example
stats3_Sunda.ipynb	historical exploratory workflow
SCIENTIFIC_METHOD.md	assumptions, null models, and interpretation limits
data/README.md	input schema and provenance contract
environment.yml	Conda development environment

Develop and contribute

python -m pip install -e ".[dev,notebook]"
ruff check .
pytest
python -m build
python tools/validate_repository.py

Scientific contributions are welcome. Read CONTRIBUTING.md, follow the Code of Conduct, report vulnerabilities through the security policy, and add user-visible changes to the changelog.

Quake Statistics is available under the permissive MIT License. Research users can cite the project using CITATION.cff.