BASINGRID: A distributed 40-year spatiotemporal hydrology dataset for U.S. basins

Overview

BASINGRID is a large-sample, spatially distributed hydrology dataset covering 9,067 basins across the contiguous United States (CONUS) over a 40-year period from 1985 to 2024.

The dataset was developed to support spatially explicit hydrological modeling, climate analysis, and geospatial machine learning. Unlike traditional large-sample hydrological datasets that represent each basin using basin-averaged forcings or lumped attributes, BASINGRID preserves within-basin spatial structure by providing basin-aligned raster patches with corresponding basin masks.

All source variables are harmonized to a common Daymet reference grid, approximately 1 km, before basin-level extraction. Basin-specific data are then extracted as fixed-size 64 × 64 spatial patches using basin windows and pixel-level masks. This creates a standardized basin-normalized representation that preserves basin shape, within-basin spatial variability, and cross-variable alignment while enabling direct use in machine-learning workflows.

Because basins differ in geographic extent, the 64 × 64 patch product standardizes tensor shape rather than physical ground resolution. The effective spatial support of each patch pixel therefore varies across basins. Users requiring native-grid spatial interpretation, exact area-based quantities, or alternative basin extraction strategies should use the provided aligned source rasters and basin metadata.

Key Features

• Spatial coverage: 9,067 GAGES-II basins across CONUS

• Temporal coverage: 1985–2024

• Reference grid: Harmonized to the Daymet grid, approximately 1 km

• Patch representation: Basin-normalized 64 × 64 raster patches

• Basin masks: Binary masks for identifying valid in-basin pixels

• Temporal resolution:

  • Daily meteorological variables

  • Annual land cover and PET

  • Static physiographic and hydrogeological variables

• Storage format: Chunked, compressed Zarr stores

• Access modes: Zenodo archive, web interface, REST API, and open-source processing code

• Intended applications: Hydrological modeling, climate analysis, geospatial machine learning, deep learning, and large-sample basin studies

Data Content

BASINGRID integrates daily, annual, and static environmental variables from publicly available sources.

Daily meteorological variables

• Precipitation

• Minimum temperature

• Maximum temperature

• Vapor pressure

• Snow water equivalent

• Shortwave radiation

Annual variables

• Land cover

• Potential evapotranspiration (PET)

PET is derived using the temperature-based Hargreaves formulation. Daily PET is first computed and then aggregated to annual sums.

Static variables

• Digital elevation model (DEM)

• Clay fraction

• Silt fraction

• Sand fraction

• Bulk density

• Near-surface permeability

• Hydraulic conductivity

• Agricultural tile drainage information

These variables are harmonized to the common spatial framework and extracted into basin-aligned patches.

Data Organization

BASINGRID is distributed in Zarr format. Each variable is stored as an independent Zarr store, allowing users to access only the variables needed for a specific analysis.

The general array structure is:

(basin, year, time, channel, height, width)

For daily variables:

(N, Y, 365, 1, 64, 64)

For annual variables:

(N, Y, 1, 1, 64, 64)

For static variables:

(N, 1, 1, C, 64, 64)

where:

• N is the number of basins

• Y is the number of years

• time is the intra-annual temporal dimension

• channel is the variable or depth-layer dimension

• height and width are the spatial patch dimensions

Example directory structure:

BASINGRID/
├── precip.zarr/
├── tmax.zarr/
├── tmin.zarr/
├── vp.zarr/
├── swe.zarr/
├── srad.zarr/
├── pet.zarr/
├── land_cover.zarr/
├── dem.zarr/
├── clay.zarr/
├── silt.zarr/
├── sand.zarr/
├── bdod.zarr/
├── permeability.zarr/
├── hydr_cond.zarr/
├── masks/
├── metadata/
└── gages-ii/

Supporting files include basin masks, basin index tables, basin geometries, basin-window metadata, and other metadata needed to link array indices to USGS/GAGES-II basin identifiers.

Important Usage Notes

Each basin patch includes raster values and a corresponding binary basin mask. Users should apply the basin mask when computing basin-level summaries or excluding out-of-basin pixels.

The normalized 64 × 64 patch representation is designed for machine-learning-ready spatial tensors. It does not imply that every patch pixel has the same physical ground resolution across basins. The effective patch resolution varies with basin size and extraction-window extent.

For applications involving exact physical area, volumetric quantities, fine-scale gradients, precipitation volumes, land-cover area fractions, or native-grid spatial analysis, users should use the provided aligned source rasters together with basin geometries and metadata.

Categorical variables, such as land cover, should be treated as categorical data. Users should avoid continuous averaging or interpolation of class labels unless the data are first converted into an appropriate categorical or one-hot representation.

Sample and Subset Access

This Zenodo record provides BASINGRID data products and supporting metadata. Users can access selected variables, basins, and years through the BASINGRID web interface and REST API without downloading the full dataset archive.

Project web interface:

https://basingrid.ciwre.msu.edu/

REST API:

https://basingrid.ciwre.msu.edu/api/

These services support subset access for selected variables, years, basin indices, basin masks, and supporting metadata.

Code and Reproducibility

The source code used to generate BASINGRID is available at:

https://github.com/Muhammad-Talha-MT/BasinGrid

The repository includes scripts for:

• Raster harmonization

• Basin indexing

• Basin-window construction

• Basin mask generation

• Patch extraction

• Zarr data organization

• API-based data access

The workflow is configuration-driven and supports reproducible construction of BASINGRID data products from the original public source datasets.

Citation

Please cite the Zenodo dataset record when using BASINGRID:

Muhammad Talha, A. Pouyan Nejadhashemi, Xiaofeng Liu, and Yuan Yang. BASINGRID: A distributed 40-year spatiotemporal hydrology dataset for U.S. basins. Zenodo, 2026.

https://doi.org/10.5281/zenodo.19358585

Contact

Muhammad Talha
Michigan State University
Email: talhamuh@msu.edu