GRASS logo

NAME

t.in.rainfall - Downloads rainfall (GPM IMERG, ERA5, TerraClimate) from the Microsoft Planetary Computer and imports it as space-time raster datasets.

KEYWORDS

temporal, import, precipitation, rainfall, IMERG, ERA5, TerraClimate

SYNOPSIS

t.in.rainfall
t.in.rainfall --help
t.in.rainfall [-el] [source=string] [start=string] [end=string] [step=string] [statistics=string[,string,...]] [wet_threshold=float] [area=north,west,south,east[,north,west,south,east,...]] [output_prefix=string] [resample=string] [cache_dir=name] [max_transfer=float] [rate=integer] [--help] [--verbose] [--quiet] [--ui]

Flags:

-e
Estimate the download for the request, then exit
-l
List the sources, their grids, periods and chunk layout, then exit
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

source=string
Rainfall dataset to read
Options: imerg, era5, terraclimate
Default: imerg
imerg: GPM IMERG Final, precipitationCal, 0.1 degree, half-hourly, 2000-06 to 2021-05
era5: ERA5 total precipitation, 0.25 degree, hourly, 1979 to 2020
terraclimate: TerraClimate precipitation, 1/24 degree, monthly, 1958 to 2021
start=string
First day, YYYY-MM-DD, or first month, YYYY-MM (UTC)
end=string
Last day, YYYY-MM-DD, or last month, YYYY-MM (UTC), inclusive
step=string
Time step of the output maps
Options: native, daily, monthly
Default: monthly
native: The dataset's own step (half-hour, hour or month)
daily: UTC days
monthly: Calendar months
statistics=string[,string,...]
Monthly statistics, one STRDS each (statistics other than total need step=monthly and a sub-daily source)
Options: total, wettest_day, wet_days
Default: total
total: Rainfall total of the step (mm)
wettest_day: Largest daily total of the month (mm)
wet_days: Number of days of the month at or above wet_threshold
wet_threshold=float
Daily total in mm from which a day counts as wet
Default: 1.0
area=north,west,south,east[,north,west,south,east,...]
Bounding box in WGS84 degrees (default the current region, plus one grid cell)
output_prefix=string
Prefix of the output STRDS names, <output_prefix>_<source>[_<statistic>]
Default: rain
resample=string
Resampling method used by r.import when the project is not in WGS84
Options: nearest, bilinear, bicubic, lanczos, bilinear_f, bicubic_f, lanczos_f
Default: nearest
cache_dir=name
Directory to keep the window of every chunk read, reused by later runs and after an interruption (default a temporary directory)
max_transfer=float
Largest estimated download in MB that the module starts without failing (0 = no limit)
Default: 2000
rate=integer
Download rate limit in kB/s (0 = no limit)
Default: 0

Table of contents

DESCRIPTION

t.in.rainfall downloads rainfall from the Microsoft Planetary Computer for an area and a period, aggregates it to the chosen time step and imports it as space-time raster datasets (STRDS). No account is needed: the module asks the Planetary Computer for a short-lived access token for each collection.

Three sources are available, chosen with source:

Source Collection Variable Grid Native step Period on the Planetary Computer
imerg gpm-imerg-hhr precipitationCal (GPM IMERG Final, V06) 0.1 degree half-hour 2000-06-01 to 2021-05-31
era5 era5-pds total precipitation (1-hour accumulation) 0.25 degree hour 1979-01-01 to 2020-12-31
terraclimate terraclimate ppt 1/24 degree (about 4 km) month 1958-01 to 2021-12

The Planetary Computer copies end where the table says, even where the datasets themselves continue at their producers (NASA GES DISC for IMERG, the Copernicus Climate Data Store for ERA5, the University of Idaho for TerraClimate). Use -l to print the table.

Time steps and statistics

step sets the time step of the output maps:

For a sub-daily source and step=monthly, statistics adds monthly statistics computed from the UTC daily totals, each in its own STRDS:

Maps are named _YYYYMM (monthly), _YYYYMMDD (daily) or _YYYYMMDDHHMM (native sub-daily), and are registered with their time interval (start included, end excluded, UTC).

Each native step is assigned to the interval over which the rain fell. IMERG time stamps mark the start of their half-hour, in mm/h, so a half-hour holds half its value. ERA5 time stamps mark the end of their hour, in metres: the UTC day D is the 24 accumulations ending from 01:00 of D to 00:00 of D+1, and the last one is the first step of the next month's store. As the Planetary Computer copy of ERA5 ends with 2020-12, the day 2020-12-31 cannot be completed and is left out, with a warning.

Missing data

Nothing is gap-filled. A cell missing at any native step of a day is null for that day, and for every monthly statistic of its month; days and months cut by the edges of the period are not written. IMERG missing-value codes become null. ERA5 accumulations below zero, which are rounding, become 0.

Area and grid

By default the area is the current region plus one native cell; area sets a box in WGS84 degrees instead. Every native cell whose footprint meets the box is imported, on its native grid (north-up, EPSG:4326). In a project that is not in WGS84, r.import reprojects with resample. The computational region is not changed.

Transfer, rate and cache

The stores are Zarr arrays split into compressed chunks, and a chunk is the smallest unit that can be read. The chunk layout therefore sets the transfer, not the area:

Source Chunk Compressed size Transfer for one month, any small area
imerg 12 half-hours x the whole globe about 50 MB about 6.4 GB
era5 372 hours x 37.5 x 37.5 degrees about 2 MB about 4 MB
terraclimate 12 months x 42.7 x 42.7 degrees about 10 MB about 10 MB a year

Before downloading, the module counts the chunks it needs and measures a few of them; -e prints that estimate and exits. A run whose estimate exceeds max_transfer (MB, default 2000) stops with an error before any download. IMERG is practical over a fast connection only: a year of it is about 75 GB of transfer.

rate caps the download in kB/s, which keeps a slow line usable for other work.

From every chunk only the window of the area is kept. With cache_dir, those windows are stored (a few kB each) and reused by later runs over the same area and dates; a run that was stopped resumes where it was, without downloading again what it had already read.

NOTES

The module reads the Zarr stores directly over HTTPS; it needs numpy, numcodecs and the GDAL Python bindings, but neither xarray nor an Azure file system library.

Progress is reported through the standard GRASS percentage, one step per month (one per request for TerraClimate).

EXAMPLES

Monthly IMERG totals, wettest day and wet days for the current region:

t.in.rainfall source=imerg start=2016-03 end=2016-04 \
    statistics=total,wettest_day,wet_days cache_dir=$HOME/RSDATA/rain_cache \
    max_transfer=15000
t.rast.list rain_imerg_wet_days

Estimate the transfer first:

t.in.rainfall -e source=imerg start=2000-06 end=2021-05

Daily ERA5 rainfall for a box, capped at 300 kB/s:

t.in.rainfall source=era5 step=daily start=2016-03-01 end=2016-03-31 \
    area=26.25,54.65,24.10,56.80 rate=300 cache_dir=$HOME/RSDATA/rain_cache

TerraClimate monthly precipitation since 1958:

t.in.rainfall source=terraclimate start=1958-01 end=2021-12 \
    cache_dir=$HOME/RSDATA/rain_cache

SEE ALSO

t.in.era5, t.rast.aggregate, t.rast.list, t.register

REFERENCES

AUTHORS

Yann Chemin

SOURCE CODE

Available at: t.in.rainfall source code (history)

Accessed: Sunday Nov 15 11:08:35 2026


Main index | Temporal index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.1dev Reference Manual