madis-data
madis-data is a Python toolkit to download, process, extract, interpolate, and plot Meteorological Assimilation Data Ingest System (MADIS) data. Currently, madis-data operates with the following publicly available MADIS Mesonet data:
- 2 m temperature
- 2 m dewpoint temperature
- 10 m west-east and south-north wind speed
- solar radiation
MADIS data are provided by the National Centers for Environmental Prediction.
Installation
pip
pip install madis-data
conda / mamba
mamba install -c jan.kazil -c conda-forge madis-data
Overview
The package provides a command-line tool that:
- selects stations by geography (a single station by MADIS station identifier, a U.S. state or territory, Regional Transmission Organization/Independent System Operator regions, and the special region CONUS representing the contiguous United States),
- downloads Mesonet observation files for a specified date range, optionally preprocesses the observations
- constructs full-hourly time series for the supported observables,
- and saves the spatially filtered observations and hourly time series in netCDF files.
It also generates a map showing the selected station locations.
Geospatial region selection is based on U.S. Energy Information Administration definitions of Regional Transmission Organization/Independent System Operator footprints and U.S. Census Bureau state and territory boundaries included with the package.
Command-line interface (CLI)
The CLI is exposed as "build-mesonet-dataset" when installed.
Usage:
build-mesonet-dataset START_YEAR START_MONTH START_DAY END_YEAR END_MONTH END_DAY REGION DATA_DIR \
[-n N_JOBS] [--no-preprocess] [--remove-original] [-r] [-v]
Positional arguments
START_YEAR,START_MONTH, andSTART_DAY: Components of the first requested timestamp at 00:00 UTCEND_YEAR,END_MONTH, andEND_DAY: Components of the last requested timestamp at 00:00 UTCREGION: Region or station selector. Use a two-letter U.S. state or territory code,CONUS, an RTO/ISO code, or a MADIS Mesonet station identifierDATA_DIR: Directory where downloaded data and generated outputs will be stored
Options
-n, --n N_JOBS: Number of parallel workers used for downloading, spatial extraction, and interpolation. Values greater than 1 can accelerate processing but may increase memory use or the risk of network errors.--no-preprocess: Use downloaded source files directly instead of preprocessing them. By default, downloaded files are preprocessed.--remove-original: Remove downloaded source files after successful preprocessing.-r, --refresh: Download files even when corresponding local files already exist.-v, --verbose: Print detailed progress information.
The command downloads one additional day before and after the requested interval so observations can bracket its boundary hours during interpolation. It creates a NetCDF file containing the selected record-oriented observations, a map of the selected station locations, and a NetCDF file containing the merged full-hourly UTC time series.
Examples:
# Show usage information:
build-mesonet-dataset --help
# Download and process MADIS Mesonet data for station SMPC2 from 00:00 UTC on January 1, 2026,
# through 00:00 UTC on January 31, 2026, and save the results in /path/to/data:
build-mesonet-dataset -v 2026 1 1 2026 1 31 SMPC2 /path/to/data
# Build datasets for Colorado using 16 parallel workers and remove source files after preprocessing:
build-mesonet-dataset -v 2026 1 1 2026 2 1 CO /path/to/data -n 16 --remove-original
# Build datasets for ERCOT directly from downloaded source files without preprocessing:
build-mesonet-dataset 2026 6 1 2026 7 1 ERCOT /path/to/data --no-preprocess
Workflow (using API)
The detailed workflow is documented in the HowTo Jupyter notebook. The notebook performs the following tasks:
- download MESONET surface observations data files for January 2026 from the MADIS archive,
- extract January 2026 data for stations in the state of Colorado of the following variables:
- 2 m temperature,
- 2 m dewpoint temperature,
- 10 m west-east and south-north wind speed,
- solar radiation
- save the extracted data in a s netCDF file,
- interpolate the data to full-hourly time series,
- save the full-hourly time series in a netCDF file,
- plot the original and the full-hourly interpolated time series at an individual station over select time intervals,
- plot the stations in the state of Colorado on a US map.
Requirements
This notebook requires the Jupyter kernel madis-data, which is automaticaly installed as part of the madis-data conda development environment. The conda development environment can be installed from the root directory of the madis-data distribution with
make setup-dev-env
Development
Code Quality and Testing Commands
make fmt- Runsruff format, which reformats Python files according to the style rules inpyproject.toml.make lint- Runsruff check --fix, which lints the code and auto-fixes what it can.make check- Runs formatting and linting.make type- Currently disabled. Intended to runmypyusing the settings inpyproject.toml.make test- Runspytestwith the test settings configured inpyproject.toml.
Disclaimers
The data accessed by this software are publicly available from NOAA's National Centers for Environmental Prediction (NCEP) and are subject to their terms of use. This project is not affiliated with or endorsed by NOAA.
This software uses U.S. Census Bureau and U.S. Energy Information Administration data, but is neither endorsed nor certified by the U.S. Census Bureau or the U.S. Energy Information Administration.
Author
Jan Kazil - jan.kazil.dev@gmail.com - github.com/jankazil/madis-data
License
BSD-3-Clause
Metadata
Release files for madis-data 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| madis_data-0.1.1.tar.gz | 22.1 MB | Without provenance | Details for madis_data-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| madis_data-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for madis_data-0.1.1-py3-none-any.whl |
Total release size: 44.4 MB
Release files / madis_data-0.1.1.tar.gz
| Download URL | madis_data-0.1.1.tar.gz |
|---|---|
| Size | 22.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d78f3f7c8a0151c4ff7492893e9d6372fbb642a7e45972329ed5d8e105b931ca
|
|
BLAKE2b-256 checksum How to use checksums |
49b17ec477bc8c297d421387caed99b1184bb39a3ab9f608b46cf717213c023e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.13
|
Release files / madis_data-0.1.1-py3-none-any.whl
| Download URL | madis_data-0.1.1-py3-none-any.whl |
|---|---|
| Size | 22.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b1e028a6453abf0ee753c8eee14c6ad0b3181de73359bc3cbfc35408356e7a5c
|
|
BLAKE2b-256 checksum How to use checksums |
3a1912ac793156de5c8dbe1d5c6a1c62734d995397762cafb01cb73e40d78373
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.13
|
Security for madis-data 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.