Precipitation Downloader Module

Download precipitation data for rainfall-weighted flow accumulation.

This module provides functions to download precipitation data (e.g., PRISM) for use in hydrological analysis. Precipitation data enables rainfall-weighted flow accumulation, which produces more realistic discharge estimates than simple cell-count accumulation.

API Reference

Precipitation data downloader module.

Downloads and manages precipitation data from various sources (PRISM, WorldClim, etc.) for hydrological analysis and terrain visualization.

Supports: - PRISM (Parameter-elevation Regressions on Independent Slopes Model) - WorldClim (global climate data) - CHELSA (high-resolution climate data)

src.terrain.precipitation_downloader.download_precipitation(bbox, output_dir, dataset='prism', force_download=False, use_real_data=True)[source]

Download precipitation data for bounding box.

Parameters:

  • bbox (tuple) – Bounding box (min_lat, min_lon, max_lat, max_lon) in WGS84

  • output_dir (str) – Directory to save downloaded data

  • dataset (str, default 'prism') – Dataset to download (‘prism’, ‘worldclim’, ‘chelsa’)

  • force_download (bool, default False) – Force re-download even if cached

  • use_real_data (bool, default True) – If True, download real data from servers. If False, generate synthetic data for testing.

Returns:

Path to downloaded precipitation GeoTIFF

Return type:

Path

Raises:

ValueError – If bbox is invalid or dataset not supported

src.terrain.precipitation_downloader.download_real_worldclim_annual(bbox, output_dir)[source]

Download real WorldClim annual precipitation data.

WorldClim provides global climate data at ~4.5km resolution (2.5 arc-minutes). This function downloads BIO12 (annual precipitation) for the specified bbox.

Uses 2.5m resolution instead of 30s for reasonable download size (~10MB vs 9.7GB).

Parameters:

  • bbox (tuple) – Bounding box (min_lat, min_lon, max_lat, max_lon)

  • output_dir (str) – Output directory

Returns:

  • np.ndarray – Precipitation data (mm/year)

  • Affine – Geographic transform

Raises:

Exception – If download fails or network is unavailable

Return type:

Tuple[ndarray, Affine]

src.terrain.precipitation_downloader.download_real_worldclim_30s_annual(bbox, output_dir)[source]

Download real WorldClim 30-second (~1km) annual precipitation data.

Downloads monthly precipitation data and sums to annual total. File size: ~1GB download for global coverage.

Parameters:

  • bbox (tuple) – Bounding box (min_lat, min_lon, max_lat, max_lon)

  • output_dir (str) – Output directory

Returns:

  • np.ndarray – Precipitation data (mm/year)

  • Affine – Geographic transform

Raises:

Exception – If download fails or network is unavailable

Return type:

Tuple[ndarray, Affine]

src.terrain.precipitation_downloader.download_real_prism_annual(bbox, output_dir)[source]

Download real PRISM annual precipitation data from FTP server.

IMPORTANT: PRISM only covers continental USA. For areas outside USA (e.g., Mexico, Canada), use WorldClim instead via download_real_worldclim_annual().

Parameters:

  • bbox (tuple) – Bounding box (min_lat, min_lon, max_lat, max_lon)

  • output_dir (str) – Output directory

Returns:

  • np.ndarray – Precipitation data (mm/year)

  • Affine – Geographic transform

Raises:

Exception – If download fails or network is unavailable

Return type:

Tuple[ndarray, Affine]

src.terrain.precipitation_downloader.get_prism_annual_precip(bbox, output_dir, use_real_data=False)[source]

Download PRISM annual precipitation for bounding box.

By default, creates synthetic orographic precipitation model for testing. Set use_real_data=True to download actual PRISM data from Oregon State servers.

Parameters:

  • bbox (tuple) – Bounding box (min_lat, min_lon, max_lat, max_lon)

  • output_dir (str) – Output directory

  • use_real_data (bool, default False) – If True, download real PRISM data. If False, generate synthetic data.

Returns:

  • np.ndarray – Precipitation data (mm/year)

  • Affine – Geographic transform

Return type:

Tuple[ndarray, Affine]

src.terrain.precipitation_downloader.validate_precipitation_alignment(dem, precip, dem_shape=None, dem_crs=None, precip_crs=None)[source]

Validate that precipitation data aligns with DEM.

Parameters:

  • dem (np.ndarray, optional) – DEM array

  • precip (np.ndarray, optional) – Precipitation array

  • dem_shape (tuple, optional) – DEM shape if arrays not provided

  • dem_crs (str, optional) – DEM CRS

  • precip_crs (str, optional) – Precipitation CRS

Raises:

ValueError – If shapes or CRS don’t match

Return type:

None

src.terrain.precipitation_downloader.list_available_datasets(include_metadata=False)[source]

List available precipitation datasets.

Parameters:

include_metadata (bool, default False) – Include metadata for each dataset

Returns:

List of dataset names, or dict with metadata if include_metadata=True

Return type:

list or dict

See Also