PyHazards: A Python framework for AI-powered hazard prediction

Datasets · Models · Benchmarks · Training Pipelines · Evaluation

Documentation · GitHub · Slack

Overview

PyHazards is built for hazard-AI work that needs more than a single model or paper reproduction. It unifies dataset discovery, model construction, benchmark-aligned evaluation, and experiment plumbing so the same library can support first-run baselines, comparative studies, and contributor extensions.

Intended users:

• Researchers: run benchmark-aligned experiments and compare baselines across hazard tasks.
• Practitioners: reuse hazard-specific workflows for data inspection, model building, and evaluation.
• Contributors: extend datasets, models, and benchmarks through registry and catalog patterns already used in the repo.

Why PyHazards

• Unified datasets: public hazard datasets, forcing sources, and inspection entrypoints live in one curated catalog.
• Benchmark-aligned evaluation: shared benchmark families, smoke configs, and reports keep experiments comparable.
• Registry-based models: published baselines and adapters are built through a consistent model-registry surface.
• Shared training and inference pipelines: one engine layer supports fit, evaluate, predict, and benchmark execution workflows.

Hazard Coverage

• Wildfire: danger forecasting, weekly forecasting, spread baselines, fuels, burn products, and active-fire sources.
• Earthquake: waveform picking, dense-grid forecasting adapters, and linked benchmark ecosystems for picking and forecasting.
• Flood: streamflow and inundation baselines with benchmark-backed evaluation paths.
• Tropical Cyclone: track-and-intensity forecasting baselines plus shared benchmark ecosystems and adapters.

Installation

Install PyHazards from PyPI:

pip install pyhazards

If you need GPU execution, install a compatible PyTorch build first and then select the device as needed:

export PYHAZARDS_DEVICE=cuda:0

Quick Start

Use this as the shortest benchmark-aware starter path: verify the package, build one registered model, and run one smoke benchmark config.

1. Verify the installation:

python -c "import pyhazards; print(pyhazards.__version__)"

2. Build a registered model:

from pyhazards.models import build_model

model = build_model(
    name="hydrographnet",
    task="regression",
    node_in_dim=2,
    edge_in_dim=3,
    out_dim=1,
)
print(type(model).__name__)

3. Run a benchmark-aligned smoke configuration:

python scripts/run_benchmark.py --config pyhazards/configs/flood/hydrographnet_smoke.yaml

4. Continue with the full docs for dataset inspection, benchmark pages, and training workflows.

Project Structure

• pyhazards.datasets - dataset catalog, registry surfaces, and inspection entrypoints.
• pyhazards.models - model registry, builders, and reusable baseline implementations.
• pyhazards.benchmarks - benchmark families, ecosystem mappings, and evaluation contracts.
• pyhazards.engine - shared training, inference, runner, and experiment utilities.
• pyhazards.configs - smoke and example benchmark configurations.
• docs/ and docs/source/ - published documentation, generated catalogs, and contributor guides.

Supported Workflows

• inspect hazard datasets and forcing sources before training,
• build baseline and adapter models through the unified registry,
• run smoke tests and benchmark configs for hazard-specific tasks,
• export benchmark reports and compare metrics across models,
• extend the library with new datasets, models, benchmarks, and catalog entries.

Documentation

Full documentation: https://labrai.github.io/PyHazards

Recommended reading order:

1. Installation
2. Quick Start
3. Datasets
4. Models
5. Benchmarks
6. Implementation Guide

Contributing

If you want to extend PyHazards:

• Contributing guide: GitHub CONTRIBUTING
• Developer implementation guide: Implementation Guide
• Maintainer notes: Maintainer Notes

Roadmap themes:

• more benchmark ecosystems and external data adapters,
• more hazard-specific baselines and evaluation coverage,
• expanded reproducibility, report tooling, and smoke-test coverage,
• stronger examples, tutorials, and contributor automation.

Community

• Slack: RAI Lab Slack Channel

Project activity:

Citation

If you use PyHazards in your research, please cite:

@misc{pyhazards2025,
  title        = {PyHazards: An Open-Source Library for AI-Powered Hazard Prediction},
  author       = {Cheng et al.},
  year         = {2025},
  howpublished = {\url{https://github.com/LabRAI/PyHazards}},
  note         = {GitHub repository}
}

License

MIT License