Hurricane Recovery Potential

Probabilistic tropical-cyclone damage (CLIMADA) + multi-hazard scaling + simplified recovery simulations (pyrecodes light) for US Atlantic- and Gulf-coast counties. Reproduces all figures, tables and reported numbers of the manuscript on recovery burden.

Naming note. The manuscript metrics map onto legacy identifiers kept in the code and data files: repair demand D_e,c [weighted units affected, WUA] = weighted_damage; expected annual repair demand EARD [WUA/yr] = eaua; recovery burden B_e,c [months] = recovery_potential_months; expected annual recovery burden EARB [months/yr] = earp_months_per_year. Event-level medians are computed over damaging events only (D_e,c > 0).

Environment

conda env create -f environment.yml
conda activate climada_env

Repository layout

batch/       SLURM submission scripts (cluster stages)
data/        committed inputs and small model outputs (see below)
modules/     shared Python modules (imported by scripts and notebooks)
notebooks/   the two analysis notebooks that generate all manuscript display items
scripts/     pipeline stages (exposure, hazard, impacts, recovery, county metrics)
tables/      manuscript LaTeX tables (written by notebooks/historical_analysis.ipynb)
figures/     manuscript figures (written by the notebooks; not committed)
analysis_output/  county-level metric CSVs (pipeline outputs; core CSVs committed)

Manuscript display items

All display items are generated by the two notebooks:

Notebook	Display items
notebooks/probabilistic_analysis.ipynb	Fig. 2 annual_3panel.png, Fig. 3 recovery_drivers_annual_vs_median.png, Fig. 4 bivariate_map_B_risk_vs_capacity.png; SI: na_coast_hazard_overview.png, median_event_3panel.png, max_event_3panel.png, recovery_drivers_annual_max.png, skewness_wd.png, and the NRI evaluation (table_nri_evaluation.tex, table_divergent_counties.tex, nri_*.csv)
notebooks/historical_analysis.ipynb	Fig. 1 hist_AL132020_4panel_focus.png (Laura) and table_laura_main.tex; SI: hist_AL142018_4panel_focus.png (Michael), table_laura_SI.tex, table_damage_distribution.tex, table_damage_normalized.tex, table_scaling_robustness.tex, table_huang_thresholds.tex

Figures are written to figures/, LaTeX tables to tables/, CSV results to analysis_output/.

Both notebooks run from the committed repository data alone: the historical notebook skips its compute steps (hazard, impacts) when the cached outputs are present, and the probabilistic notebook only needs the committed county-level metric CSVs, except for two SI items that need larger local inputs (na_coast_hazard_overview.png needs the hazard .mat matrices; the NRI EARC comparison needs data/impact/per_event/; both cells state this).

Data

Committed (inputs): data/US_counties.{shp,shx,dbf}, data/county_region.csv, data/CAPRA_TO_BEM_TC_WIND_IMPACT_FUNCTIONS.csv, data/Dmat_region_all.csv, data/scaling_relative.npz, data/scaling_relative_historical.npz, data/selected_states_counties_with_permits.csv (construction capacity), data/huang_recovery_by_county_event.csv (Huang et al. 2025 county-event table), data/fema_ia/fema_damage_by_county.csv (OpenFEMA IA damage, see scripts/fetch_openfema_damage.py), data/exposure_units_by_county.csv (slimmed from analysis_output/county_exposed_housing_units.csv).

Committed (small model outputs, so the notebooks reproduce without cluster runs): data/hazard/gori_historical.hdf5 (historical CLIMADA hazard, 10 storms), data/impact_historical/per_event/ (historical per-event impact CSVs), data/recovery/recovery_potential.csv and data/recovery_historical/recovery_potential.csv (pyrecodes-light outputs), and the five county-level metric CSVs in analysis_output/.

External inputs (not committed; paths configurable, see the table):

Item	Expected location	Notes
Gori TC wind-field .mat files (~5018 events)	<CLIMADA_DATA>/hazard/tropical_cyclone/gori/	Gori et al. (2025); Stage 2
Historical blended wind fields + best-track file	<CLIMADA_DATA>/hazard/tropical_cyclone/gori/historical/	only to rebuild gori_historical.hdf5
Hazard matrices max{windmat,elev_coastcounty}_ncep_reanal.mat, ptot_rain_county_ncep_reanal.mat	data/hazard/	scaling (Stage 3) and SI hazard overview
Raw ACS/Census housing CSVs	cluster path in scripts/make_state_exposures.py	Stage 1
Per-state exposure HDF5	data/exposure/states/	Stage 1 output
Per-event impact CSVs (probabilistic)	data/impact/per_event/	Stage 4 output
FEMA NRI county table	data/NRI_Table_Counties.csv	download from https://hazards.fema.gov/nri/

<CLIMADA_DATA> defaults to ~/climada/data and can be overridden with the CLIMADA_DATA environment variable (used by the historical notebook). The Stage 1–2 scripts and batch/ files contain cluster (SLURM) paths; adapt them to your system before rerunning those stages.

Pipeline

The stages below produce the inputs the notebooks consume. Stages 1, 2 and 4 are cluster jobs (CLIMADA, large data); Stages 5–6 run locally in minutes.

Stage 1 — Exposure

Build CLIMADA Exposures HDF5 files from raw ACS housing CSVs.

sbatch batch/sbatch_make_state_exposures.sh   # -> data/exposure/states/*.hdf5
sbatch batch/sbatch_make_NA_exposure.sh       # -> NA_coast_exposure.hdf5 (combined)

Stage 2 — Hazard

Build the CLIMADA TropCyclone hazard from the Gori wind-field .mat files.

sbatch batch/sbatch_make_haz_gori_array.sh
python scripts/concat_haz_gori_chunks.py \
    --pattern 'tc_ncep_reanal_chunk*.hdf5' \
    --output <CLIMADA_DATA>/hazard/tropical_cyclone/gori/tc_ncep_reanal.hdf5

Stage 3 — Multi-hazard scaling

County-level scaling factors from wind, rainfall and surge matrices; the output data/scaling_relative.npz is committed. The historical variant (data/scaling_relative_historical.npz) is built inside notebooks/historical_analysis.ipynb (Step 3).

Stage 4 — Impacts

CLIMADA impact calculation per state and event, merged to per-event scaled CSVs.

bash batch/submit_calc_impacts_per_chunk.sh      # -> data/impact/per_event/
python scripts/extract_exposure_units_by_county.py
# -> analysis_output/county_exposed_housing_units.csv

Stage 5 — Recovery (pyrecodes light)

Per-county, per-event recovery burden: recovery = max(floor, demand / capacity) with HAZUS repair-time weights tau = (1, 1, 3, 6) months for DS1-DS4 and capacity = average monthly building permits. Implemented in modules/recovery_utils.py; see the module docstring for the method.

python scripts/run_pyrecodes_light.py
# -> data/recovery/recovery_potential.csv

python scripts/compute_recovery_potential.py
# -> analysis_output/earp_per_county.csv  (EARB: frequency-weighted sum)

Stage 6 — County metrics

python scripts/analyze_event_frequency_damage.py
# -> analysis_output/county_event_frequency_damage_metrics.csv  (EARD inputs)

python scripts/compare_median_vs_max_events.py
# -> analysis_output/median_vs_max_event_comparison.csv

python scripts/analyze_recovery_distributions.py
# -> analysis_output/county_distribution_metrics.csv  (skewness)

Stage 7 — Manuscript display items

Run the two notebooks (order does not matter):

jupyter lab notebooks/probabilistic_analysis.ipynb
jupyter lab notebooks/historical_analysis.ipynb

The historical notebook also documents its own pipeline (Steps 1-5: historical hazard, scaling, impacts, recovery), which reruns only when the cached data files are deleted.

OpenFEMA damage data (historical evaluation)

data/fema_ia/fema_damage_by_county.csv (committed) holds the FEMA-verified owner real-property damage per county and storm, aggregated from the OpenFEMA HousingAssistanceOwners endpoint. Rebuild with:

python scripts/fetch_openfema_damage.py

Module dependencies

Module	Used by
modules/exposure_utils.py	make_NA_exposure.py, make_state_exposures.py
modules/hazard_utils.py	make_haz_gori_chunks.py, historical notebook (Step 2)
modules/scaling_utils.py	historical notebook (Step 3)
modules/impact_utils.py	calc_state_impact.py, historical notebook (Step 4)
modules/impfunc_utils.py	calc_state_impact.py, historical notebook (Step 4)
modules/recovery_utils.py	run_pyrecodes_light.py, historical notebook (Step 5)