pyhazards 1.0.4

A Python framework for AI-powered hazard prediction and risk assessment

PyHazards

Introduction

PyHazards is a Python framework for AI-powered hazard prediction and risk assessment. It provides a hazard-first API for loading data, building models, running end-to-end experiments, and extending with your own modules.

Core Components

• Datasets: Unified interfaces for tabular, temporal, raster, and graph-style hazard data through DataBundle.
• Models: Built-in hazard models plus reusable backbones/heads via a registry-driven model API.
• Engine: Trainer for fit/evaluate/predict workflows with mixed precision and distributed options.
• Metrics and Utilities: Classification/regression/segmentation metrics, hardware helpers, and reproducibility tools.

Install

pip install pyhazards

Optional CUDA setup:

export PYHAZARDS_DEVICE=cuda:0

Load Data

Example using the implemented ERA5 flood subset loader:

from pyhazards.data.load_hydrograph_data import load_hydrograph_data

print("[Step 1/3] Loading ERA5 dataset...")
data = load_hydrograph_data(
    era5_path="pyhazards/data/era5_subset",
    max_nodes=50,
)
print("[Step 1/3] Dataset loaded.")
print(data.feature_spec)
print(data.label_spec)
print(list(data.splits.keys()))  # ["train"]

Load Model

Example using wildfire_aspp:

from pyhazards.models import build_model

print("[Step 2/3] Building model...")
model = build_model(
    name="wildfire_aspp",
    task="segmentation",
    in_channels=12,
)
print("[Step 2/3] Model built.")
print(type(model).__name__)

Full Test

Short end-to-end example using real ERA5 data and an implemented flood model:

import torch
from pyhazards.data.load_hydrograph_data import load_hydrograph_data
from pyhazards.datasets import graph_collate
from pyhazards.engine import Trainer
from pyhazards.models import build_model

data = load_hydrograph_data("pyhazards/data/era5_subset", max_nodes=50)

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

trainer = Trainer(model=model, mixed_precision=False)
optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)
loss_fn = torch.nn.MSELoss()

print("[Step 3/3] Running one training epoch...")
trainer.fit(
    data,
    optimizer=optimizer,
    loss_fn=loss_fn,
    max_epochs=1,
    batch_size=1,
    collate_fn=graph_collate,
)

print("[Step 3/3] Evaluating on train split...")
metrics = trainer.evaluate(
    data,
    split="train",
    batch_size=1,
    collate_fn=graph_collate,
)
print(metrics)

Quick Verification (test.py)

Run the built-in GPU smoke test:

python test.py

test.py is a validation/smoke test only. It verifies pipeline correctness and integration, not final benchmark performance.

It prints step-by-step status (dataset load, model build, forward pass, train/eval) and ends with:

PASS: end-to-end implementation is working.

Custom Module

To upload and use your own data/model modules:

1. Upload your raw data files to your project path and write a dataset loader that returns a DataBundle.
2. Register your model with register_model and a builder function that returns an nn.Module.
3. Build with build_model(...) and train/evaluate through Trainer.

Implementation details:

• Implementation Guideline
• Contributors Guideline

Star History

How to Cite

If you use PyHazards in your research, please cite:

@software{pyhazards2025,
  title={PyHazards: A Python Framework for AI-Powered Hazard Prediction},
  author={Cheng, Xueqi},
  year={2025},
  url={https://github.com/LabRAI/PyHazards}
}

Documentation

Full documentation is available at: https://labrai.github.io/PyHazards

License

MIT License

Contact

For questions or contributions, please contact [e-mail].