QuakeLiq

QuakeLiq is an open-source tool for near-real-time regional assessment of earthquake-induced surface liquefaction manifestations.

Workflow

1. Search the USGS catalog and select a target earthquake.
2. Download PGA and PGV for the selected event.
3. Define the prediction domain from PGA.
4. Prepare PGV, LPI, groundwater-table depth (GWTD), distance to persistent water (Dist2Water), and land cover.
5. Run the five-predictor brms model.
6. Write predictor maps, posterior summaries, and a quicklook figure.

Predictor	Unit	Source resolution	Processing
PGV	cm/s	~1 km	USGS ShakeMap
LPI	dimensionless	~90 m	Liquefaction potential index; Calculated from event PGA and magnitude
GWTD	m	~1 km	Groundwater-table depth; truncated at -20 m
Dist2Water	km	~30 m	Distance to persistent surface water; truncated at 10 km for the model
Land cover	categorical	~100 m	Urban, cropland, vegetated, or other

Project files

• Input.txt: all reusable paths and numerical settings.
• QuakeLiq.ipynb: the only user entry point.
• src/QuakeLiq_main.py: complete workflow.
• src/define_file_path.py: reads and checks Input.txt.
• src/search_earthquake_events.py: searches the USGS catalog and displays event IDs.
• src/download_PGA_PGV.py: downloads and combines ShakeMap rasters.
• src/create_liquefaction_affected_area.py: creates the prediction domain from PGA map.
• src/feature_extraction.py: prepares the five predictors.
• src/model_prediction.py: runs the R model and writes probability rasters.
• src/plot_utils.py: creates the quicklook figure.
• r/: R environment setup and brms prediction scripts.
• model/: final fitted model.
• data/: documented locations for external data; large third-party files are not distributed.

Installation and data

Python 3.10 or newer is recommended.

python -m pip install -r requirements.txt

Install R 4.2 or newer. If Rscript is not on PATH, enter its absolute path under RscriptExe in Input.txt. The notebook can install the required R packages in the project-local .r-library.

Download the external rasters listed in data/README.md. Their required paths are already given in Input.txt. The final model is included at model/quakeliq_hbm_20260707.rds.

Settings and run

Edit Input.txt before a run. The default settings are:

• DomainMode = threshold
• PGAThreshold = 0.1 g
• N_DRAWS = 200

threshold predicts only cells with PGA at or above the configured threshold. rectangle predicts all valid reference-grid cells inside the bounding rectangle of that threshold area.

Start Jupyter in the project directory, open QuakeLiq.ipynb, set the USGS event ID, and run all cells.

Outputs

Each run is written to results/<run_id>/:

• ShakeMap/: PGA and PGV inputs.
• feature_maps/: five predictor rasters and the prediction-domain mask.
• prediction_input.parquet and prediction_quantiles.parquet.
• assessment_results/: posterior probability rasters and quicklook figure.
• run_metadata.json, posterior_draw_metadata.csv, and run.log.

The result is the probability that a ~250 m cell contains at least one mapped surface liquefaction manifestation. It does not estimate subsurface liquefaction.