Sources

Base classes

class climagrid.sources.base.BoundingBox(min_lat=None, max_lat=None, min_lon=None, max_lon=None, **data)[source]

Bases: BaseModel

Geographic bounding box in WGS-84 decimal degrees.

Parameters:
model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

min_lat: float
max_lat: float
min_lon: float
max_lon: float
classmethod from_center(lat, lon, radius_km)[source]

Create a bounding box centered on a point with a radius in km.

Edges are clamped to the valid WGS-84 domain ([-90, 90] latitude, [-180, 180] longitude) so that centers near the poles or the antimeridian still yield a valid box rather than raising.

Return type:

BoundingBox

Parameters:
property center: tuple[float, float]
class climagrid.sources.base.BaseEnvironmentalSource[source]

Bases: ABC

Common interface all data source adapters must implement.

Each adapter fetches raw data for a geographic region and time window, returning a pandas DataFrame with columns conforming to climagrid.schema.

point_based: bool = False
abstract property source_name: str

Short identifier used as a column prefix (e.g. ‘hrrr’, ‘nasa_power’).

abstractmethod fetch(bbox, start_dt, end_dt)[source]

Fetch environmental data for a bounding box over a time range.

Parameters:

  • bbox (BoundingBox) – Geographic extent of the query.

  • start_dt (datetime) – Start of the time range (UTC-aware or naive UTC).

  • end_dt (datetime) – End of the time range (UTC-aware or naive UTC).

Returns:

Rows indexed by (lat, lon, timestamp). Column names must be drawn from climagrid.schema.COLUMN_MAP.

Return type:

DataFrame

fetch_points(points, start_dt, end_dt)[source]

Fetch data for multiple (lat, lon) point locations.

Point-based sources (point_based = True) override this to return one block of rows per location, each tagged with its own lat/lon, so every asset gets weather at its actual position rather than a single shared point. The default raises, since grid and station sources use fetch() with a bounding box instead.

Return type:

DataFrame

Parameters:

NASA POWER

class climagrid.sources.nasa_power.NasaPowerAdapter(timeout=60, session=None)[source]

Bases: BaseEnvironmentalSource

Fetches hourly surface meteorology from NASA POWER for point locations.

For a bounding box query the center point is used. The orchestrator calls fetch_points() to retrieve one location per asset.

Parameters:

  • timeout (int)

  • session (requests.Session | None)

point_based: bool = True
property source_name: str

Short identifier used as a column prefix (e.g. ‘hrrr’, ‘nasa_power’).

fetch_points(points, start_dt, end_dt)[source]

Fetch hourly data for each (lat, lon), one API call per location.

Return type:

DataFrame

Parameters:
fetch(bbox, start_dt, end_dt)[source]

Fetch for the center point of the bounding box.

Return type:

DataFrame

Parameters:
fetch_point(lat, lon, start_dt, end_dt)[source]

Fetch hourly NASA POWER data for a single lat/lon point.

Return type:

DataFrame

Parameters:

NOAA HRRR

class climagrid.sources.noaa_hrrr.HrrrAdapter(product='sfc', fxx=0, save_dir=None)[source]

Bases: BaseEnvironmentalSource

Fetches NOAA HRRR NWP data at 3 km CONUS resolution.

Each call fetches the analysis hour (fxx=0) for every UTC hour in [start_dt, end_dt), subsets to the bounding box, and returns a long-form DataFrame with one row per (lat, lon, timestamp).

Parameters:

  • product (str) – HRRR product type. “sfc” (surface fields) covers all variables needed for grid asset stress analysis.

  • fxx (int) – Forecast hour. Use 0 for analysis (best accuracy for past dates), 1-18 for near-real-time forecasting.

  • save_dir (str | None) – Local directory for GRIB2 file caching. Defaults to ~/data/hrrr.

property source_name: str

Short identifier used as a column prefix (e.g. ‘hrrr’, ‘nasa_power’).

fetch(bbox, start_dt, end_dt)[source]

Fetch environmental data for a bounding box over a time range.

Parameters:

  • bbox (BoundingBox) – Geographic extent of the query.

  • start_dt (datetime) – Start of the time range (UTC-aware or naive UTC).

  • end_dt (datetime) – End of the time range (UTC-aware or naive UTC).

Returns:

Rows indexed by (lat, lon, timestamp). Column names must be drawn from climagrid.schema.COLUMN_MAP.

Return type:

DataFrame

NOAA NCEI

class climagrid.sources.noaa_ncei.NceiAdapter(api_token=None, radius_km=50.0, timeout=30, session=None)[source]

Bases: BaseEnvironmentalSource

Fetches hourly surface observations from NOAA NCEI CDO API.

Finds the nearest NCEI station within the bounding box and returns its hourly observation record for the requested time range.

Parameters:

  • api_token (str | None) – NOAA CDO API token. If None, reads from NOAA_CDO_TOKEN env var.

  • radius_km (float) – Search radius for finding the nearest station (default 50 km).

  • timeout (int)

  • session (requests.Session | None)

point_based: bool = True
property source_name: str

Short identifier used as a column prefix (e.g. ‘hrrr’, ‘nasa_power’).

fetch_points(points, start_dt, end_dt)[source]

Find and fetch the nearest station to each asset location.

Return type:

DataFrame

Parameters:
fetch(bbox, start_dt, end_dt)[source]

Fetch environmental data for a bounding box over a time range.

Parameters:

  • bbox (BoundingBox) – Geographic extent of the query.

  • start_dt (datetime) – Start of the time range (UTC-aware or naive UTC).

  • end_dt (datetime) – End of the time range (UTC-aware or naive UTC).

Returns:

Rows indexed by (lat, lon, timestamp). Column names must be drawn from climagrid.schema.COLUMN_MAP.

Return type:

DataFrame

USDA NRCS

class climagrid.sources.usda_nrcs.NrcsAdapter(max_distance_km=200.0, timeout=30, session=None)[source]

Bases: BaseEnvironmentalSource

Fetches soil and snow data from USDA NRCS SCAN/SNOTEL network.

Finds the nearest active SCAN or SNOTEL station within the bounding box, fetches hourly readings, and returns a climagrid DataFrame.

Parameters:

  • max_distance_km (float) – Maximum search distance for nearest station (default 200 km). SCAN/SNOTEL networks are sparse in some regions.

  • timeout (int)

  • session (requests.Session | None)

point_based: bool = True
property source_name: str

Short identifier used as a column prefix (e.g. ‘hrrr’, ‘nasa_power’).

fetch_points(points, start_dt, end_dt)[source]

Find and fetch the nearest SCAN/SNOTEL station to each asset.

Return type:

DataFrame

Parameters:
fetch(bbox, start_dt, end_dt)[source]

Fetch environmental data for a bounding box over a time range.

Parameters:

  • bbox (BoundingBox) – Geographic extent of the query.

  • start_dt (datetime) – Start of the time range (UTC-aware or naive UTC).

  • end_dt (datetime) – End of the time range (UTC-aware or naive UTC).

Returns:

Rows indexed by (lat, lon, timestamp). Column names must be drawn from climagrid.schema.COLUMN_MAP.

Return type:

DataFrame

USFS WFIGS

class climagrid.sources.usfs_wfigs.WfigsAdapter(timeout=30, session=None)[source]

Bases: BaseEnvironmentalSource

Fetches wildfire perimeter data from NIFC WFIGS for a bounding box.

For each asset location, the joiner can use this data to compute: - Distance to the nearest fire perimeter edge - Whether any active fire is within a configurable radius - Area of the nearest fire

Parameters:

  • timeout (int)

  • session (requests.Session | None)

property source_name: str

Short identifier used as a column prefix (e.g. ‘hrrr’, ‘nasa_power’).

fetch(bbox, start_dt, end_dt)[source]

Fetch current fire perimeters intersecting the bounding box.

Returns a DataFrame with one row per fire, including centroid lat/lon and area. The joiner uses this to compute per-asset proximity scores.

Return type:

DataFrame

Parameters:
climagrid.sources.usfs_wfigs.compute_proximity(asset_lat, asset_lon, fires_df)[source]

Compute wildfire proximity metrics for a single asset location.

Return type:

tuple[float, bool, float]

Parameters: