r.noaa.atlas14 - GRASS manual

NAME

r.noaa.atlas14 - Downloads and imports NOAA Atlas 14 precipitation-frequency data from the PFDS point service or official GIS grid packages.

KEYWORDS

raster, hydrology, precipitation, vector, rainfall, NOAA, Atlas 14

SYNOPSIS

r.noaa.atlas14

r.noaa.atlas14 --help

r.noaa.atlas14 [-lkcio] mode=string [statistic=string] [units=string] [series=string] [bound=string] [coordinates=lon,lat[,lon,lat,...]] [vector_output=name] [output=string] [format=string] [float_format=string] [region=string] [archive_url=string] [durations=string[,string,...]] [aris=integer[,integer,...]] [output_prefix=string] [resample=string] [base_gis_url=string] [separator=string] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-l: List matching grid archives and exit (mode=grid)
-k: Keep downloaded archives
-c: Print point result to stdout even if output file is written
-i: Use r.import instead of r.in.gdal for grid import
-o: Override projection check when using r.in.gdal
--overwrite: Allow output files to overwrite existing files
--help: Print usage summary
--verbose: Verbose module output
--quiet: Quiet module output
--ui: Force launching GUI dialog

Parameters:

mode=string [required]: Data acquisition mode; Options: point, grid
statistic=string: Statistic to request/import; Options: depth, intensity; Default: depth
units=string: Units for point queries; output units for grid rasters (does not filter grids); Options: english, metric; Default: english
series=string: Time series type for point queries or for filtering grids; Options: pds, ams; Default: pds
bound=string: Bound to return/import; Options: expected, upper, lower, all; Default: expected
coordinates=lon,lat[,lon,lat,...]: Longitude,Latitude pair(s) in decimal degrees for mode=point; if omitted, the center of the computational region is used
vector_output=name: Optional output vector point map for mode=point
output=string: Optional path for point output file (.json or .csv) or grid manifest CSV
format=string: Output format for mode=point; Options: json, csv; Default: json
float_format=string: Python format string for CSV numeric output in mode=point; Default: .3f
region=string: Atlas 14 grid region code, e.g. sw, orb, pr, hi, nmi, ch, ko, pp, nk, pg, yp, wl, ul, pl, rm, as, gu, wki, ak, mw, se, ne, tx, inw
archive_url=string: Direct URL to a NOAA grid ZIP archive or a directory listing page; overrides autodiscovery in mode=grid
durations=string[,string,...]: Duration filters for mode=grid, e.g. 5min,10min,24hr,2day
aris=integer[,integer,...]: Average recurrence intervals in years for mode=grid, e.g. 2,10,100
output_prefix=string: Prefix for imported raster names in mode=grid; Default: a14
resample=string: Resampling method used by r.import in mode=grid; Options: nearest, bilinear, bicubic, lanczos; Default: nearest; nearest: Nearest-neighbor interpolation; bilinear: Bilinear interpolation; bicubic: Bicubic interpolation
base_gis_url=string: Base HTTPS directory for NOAA Atlas 14 GIS data; used for grid autodiscovery; Default: https://hdsc.nws.noaa.gov/pub/hdsc/data
separator=string: Separator for CSV-like outputs where relevant; Options: comma, pipe, tab, space; Default: comma

DESCRIPTION
NOTES
EXAMPLES
REFERENCES
SEE ALSO
AUTHORS

DESCRIPTION

r.noaa.atlas14 downloads and imports NOAA Atlas 14 precipitation-frequency data into GRASS. It supports two acquisition modes:

mode=point queries the NOAA Precipitation Frequency Data Server (PFDS) point-query endpoint for one or more longitude/latitude pairs and writes the returned precipitation-frequency estimates as JSON or CSV. Optionally, a GRASS vector point map is created with the expected/upper/lower tables stored as JSON attributes.
mode=grid discovers, downloads, and imports NOAA Atlas 14 GIS-compatible grid archives (ZIP) for a given Atlas 14 volume/subregion, optionally filtered by duration, average recurrence interval (ARI), bound, statistic, units, and series. A manifest CSV describing the imported rasters can be written.

The module retrieves data directly from NOAA's public services:

PFDS point query: https://hdsc.nws.noaa.gov/cgi-bin/new/fe_text.csv
GIS grid archives: https://hdsc.nws.noaa.gov/pub/hdsc/data/ (autodiscovery), or any user-supplied archive_url=.

NOTES

Point mode

Point results include the expected value and the upper/lower bounds of the 90% confidence interval, for each duration/return-period combination published by NOAA. Use bound=expected|upper|lower|all to select the table(s).

coordinates= accepts one or more lon,lat pairs, e.g. coordinates=-78.6382,35.7796,-81.0,29.5. When coordinates= is omitted, the module queries the center of the current computational region; the region bounds are reprojected to WGS84 lon/lat via g.region -b so this works from any GRASS location CRS.

NOAA Atlas 14 precipitation-frequency curves for Raleigh, NC

Figure: Precipitation-frequency (depth vs. duration) curves for Raleigh, North Carolina, produced from an r.noaa.atlas14 mode=point query to the NOAA Precipitation Frequency Data Server. Each curve is the expected value for the labeled return period.

When multiple points are queried, JSON output is emitted as a list of per-point result objects, and CSV output prepends lon,lat,bound columns so rows from different points and bounds can be disambiguated. Single-point output keeps the original unwrapped format for backward compatibility.

The statistic option controls whether PFDS returns precipitation depth or intensity. The units option (english or metric) and series option (pds or ams — partial-duration or annual-maximum series) are passed through to PFDS.

If vector_output= is given, the module creates a vector point map with one feature per queried point and columns lon, lat, expected_json, upper_json, lower_json. Point geometries are reprojected from WGS84 into the current project's CRS, while the lon/lat columns keep the original WGS84 coordinates. The JSON columns contain the full per-duration tables so they can be queried later with v.db.select / db.select.

Grid mode

NOAA organizes Atlas 14 GIS archives under per-volume subdirectories of base_gis_url=, e.g. https://hdsc.nws.noaa.gov/pub/hdsc/data/se/ for Volume 9 Southeastern States. When region= is given, autodiscovery fetches the listing at <base_gis_url>/<region>/ and parses every *.zip href.

Filenames follow a compact convention <region><ari>yr<NN><unit>a[l|u][_ams].zip, e.g.:

se2yr24ha.zip — Southeastern, 2-year ARI, 24-hour, expected, PDS
orb1000yr30mau_ams.zip — Ohio River Basin, 1000-year, 30-minute, upper bound, AMS
se1000yr60dal.zip — Southeastern, 1000-year, 60-day, lower bound, PDS

where <unit> is m, h, or d (minute/hour/day), bound is absent for the expected value and l/u for the lower/upper 90% confidence bounds, and _ams marks the annual-maximum series (absent = partial-duration series).

If autodiscovery fails or a custom mirror is used, pass archive_url= directly with either a .zip URL or a directory listing URL that contains the ZIPs.

The -l flag lists matching archives (as JSON lines) without downloading them.

Filtering behavior:

durations= and aris= are strict: candidates whose duration or ARI could not be inferred from the filename are rejected.
bound= and series= are permissive: a candidate with an unknown attribute is allowed through, to avoid discarding rasters whose filenames do not encode every attribute.
statistic= and units= do not filter archives in grid mode. NOAA only publishes depth in english units, so the module always downloads that and rescales the imported rasters to the requested statistic/units as output targets.

Rasters are imported with r.in.gdal by default; pass -i to use r.import (which supports reprojection via resample=). Pass -o to override the projection check when using r.in.gdal. Imported raster names follow the pattern <output_prefix>_<statistic>_<bound>_<duration>_<ari>yr_<units>_<series>_<region>, with missing parts omitted.

Value encoding

NOAA Atlas 14 GIS grids encode precipitation depth as integer 1000ths of an inch in the raw archives. Grid mode converts the imported rasters automatically, so no manual rescaling is needed: depth is written in inches (or mm with units=metric) and intensity in in/hr (or mm/hr), according to the requested statistic and units. The raster units and title set by r.support describe the converted values. NODATA cells become GRASS NULLs on import, so the sentinel value (which varies by volume) does not need to be handled.

r.noaa.atlas14 mode=point coordinates=-78.6382,35.7796 \
    statistic=intensity units=english series=pds bound=expected \
    format=csv output=/tmp/raleigh_idf.csv

Point query to JSON and create a vector point

r.noaa.atlas14 mode=point coordinates=-78.6382,35.7796 \
    statistic=depth units=english series=pds bound=all \
    format=json output=/tmp/raleigh_atlas14.json \
    vector_output=atlas14_raleigh

Multiple points as a single CSV and a multi-point vector

r.noaa.atlas14 mode=point \
    coordinates=-78.6382,35.7796,-80.8431,35.2271,-77.8868,34.2257 \
    statistic=depth units=english series=pds bound=expected \
    format=csv output=/tmp/nc_cities_idf.csv \
    vector_output=atlas14_nc_cities

Query the center of the current computational region

g.region raster=elevation
r.noaa.atlas14 mode=point format=json bound=expected

List matching grid archives without importing

r.noaa.atlas14 mode=grid region=se -l

Import a known archive directly

r.noaa.atlas14 mode=grid \
    archive_url="https://hdsc.nws.noaa.gov/pub/hdsc/data/se/se100yr24ha.zip" \
    output_prefix=a14 -i

Import filtered subset and write a manifest

r.noaa.atlas14 mode=grid region=se \
    durations=24hr,2day aris=10,100 bound=expected \
    output_prefix=a14 output=/tmp/a14_manifest.csv -i

REFERENCES

Bonnin, G. M., D. Martin, B. Lin, T. Parzybok, M. Yekta, and D. Riley (2004–2019), NOAA Atlas 14: Precipitation-Frequency Atlas of the United States. NOAA, National Weather Service, Silver Spring, Maryland.
NOAA Precipitation Frequency Data Server (PFDS): https://hdsc.nws.noaa.gov/pfds/

AUTHORS

Corey T. White, NCSU GeoForAll Lab

SOURCE CODE

Available at: r.noaa.atlas14 source code (history)

Latest change: Wednesday Jun 03 10:49:06 2026 in commit: cb384e4f5e3ed4a44746946bc5ecc66a81f8858c