NAME

KEYWORDS

SYNOPSIS

DESCRIPTION

For each variable, ERA5-Land (~9km grid, generally preferable for land applications) is tried first via the Copernicus Climate Data Store (CDS); if that fails for a given month (explicit CDS error, no ~/.cdsapirc configured, network issue, or a genuine coverage gap), the module automatically falls back to plain ERA5 (~31km grid, longer historical record) for that month only -- other months/ variables are unaffected. By default that fallback tier is read straight from the public ARCO-ERA5 Google Cloud archive (no CDS account needed at all for it); pass -c to use CDS's own plain-ERA5 product there instead.

One CDS quirk drives part of the ERA5-Land fallback even when ERA5-Land data actually exists: the derived-era5-land-daily-statistics product used for "instantaneous" variables (temperature, wind, pressure, ...) explicitly refuses to compute daily statistics for accumulated variables (precipitation, potential evaporation, solar radiation, snowfall). For those, t.in.era5 requests raw hourly reanalysis-era5-land data instead and sums it to a daily total itself -- still ERA5-Land, just via a different CDS product -- before falling back to the plain-ERA5 tier only if that also fails.

Requests are chunked per (variable, year, month), so a single failure doesn't force re-fetching a whole multi-year request, and repeat runs against the same cache_dir reuse already-downloaded months instead of re-downloading them.

ARCO-ERA5 (Google Cloud) SOURCE

t.in.era5 opens the store with xarray.open_zarr(..., chunks=None, storage_options=dict(token="anon")) -- matching Google's own arco-era5 usage examples for this exact dataset, and confirmed in practice to be both simpler (no dask dependency at all) and faster than chunks="auto", which only adds a dask-array layer that regroups the store's own chunks without reducing what gets transferred.

ARCO-ERA5 is an unmodified GRIB-to-Zarr conversion of the raw archive, so accumulated variables (precipitation, potential evaporation, solar radiation, snowfall) are still in ECMWF's raw forecast-accumulation form and are de-accumulated locally to daily totals, following ECMWF's published conversion guidance for these fields. This is a different correction than the one applied to ERA5-Land's raw hourly data (see above) -- do not assume the two behave the same way.

Reading ARCO-ERA5 requires the gcsfs and zarr Python packages in addition to xarray/netCDF4. make venv (see the Makefile) builds a dedicated virtualenv with all of these under the installed addon's own etc/t.in.era5/venv, which t.in.era5.py detects and uses automatically -- no manual pip install needed, and none is attempted against GRASS's own Python installation (which a plain pip install often can't touch anyway, blocked by PEP 668's externally-managed-environment guard on modern Debian/Ubuntu).

Cost/performance: whole-globe-per-hour chunking, and the world cache

Since keeping the whole globe costs nothing beyond what a bbox-only fetch already pays for, t.in.era5 does exactly that: every ARCO-ERA5 fetch is cached permanently, at full world coverage, under arco_world_cache (default $HOME/RSDATA/ERA5World), keyed only by (variable, reduction, year, month) -- deliberately independent of area, output_prefix, or which run asked for it. The very first request for a given (variable, month) anywhere in the world pays the full download; every later request for that same (variable, month) -- for any region, any project, any future run -- is served from that local file with no network access at all. Confirmed in practice: a second fetch for a different continent's bounding box, same month, dropped from ~82s to ~0.05s. This directory grows over time by design (each cached month is a genuine, reusable slice of world coverage, compressed to a few MB per variable per month for typical fields) and is never pruned automatically -- treat it as a small, permanent local ERA5 mirror you're building up, and manage its size yourself if that ever matters. A handful of days for a brand-new month is still fast (a few minutes, paid once); only a large historical multi-month backfill of variables/months never requested before is slow, and even then only once -- for a true first-time bulk historical load, -c (CDS, which subsets server-side and so is cheaper per single request but never builds up a reusable local archive) may still be preferable.

Estimated arco_world_cache disk usage

Requesting temperature_min/temperature_max in addition to temperature adds separate cache entries each of comparable size (same underlying hourly source, but cached per daily reduction -- mean, min, max are each their own file), roughly tripling the temperature share of this estimate if all three are used.

Data freshness: final vs. preliminary (ERA5T), and the CDS gap-fill

t.in.era5 checks these on every month it fetches from ARCO-ERA5, and caches accordingly:

• Final (within valid_time_stop): cached as <var>_<reduction>_<year><month>.nc -- trusted forever once cached, no re-check on later hits (final data never changes, so there's nothing to gain by re-touching ARCO for it).
• ERA5T / preliminary (beyond valid_time_stop but within valid_time_stop_era5t): cached separately, as <var>_<reduction>_<year><month>_era5t.nc -- this data is real and usable now, but is not guaranteed to be the exact values that will eventually be archived once ARCO ingests the final release for that month. Kept apart so a cache hit never silently serves stale-but-still-present-on-disk provisional data as if it were final: every _era5t cache hit re-checks ARCO's own valid_time_stop (cheap -- metadata only, no data re-fetch), and once the final release has landed, t.in.era5 automatically fetches and caches the real final month and deletes the superseded _era5t file -- no stale provisional data left behind for good cleaning practice, and no manual cleanup needed.
• Not yet ingested at all (beyond valid_time_stop_era5t): ARCO-ERA5 has nothing for this month yet -- not even provisionally. In this case t.in.era5 automatically falls back to the CDS API for that one month only (needs ~/.cdsapirc; a warning is printed), so the run still completes instead of silently producing a gap. Is this the same data ARCO will eventually have for that month? Not verifiably -- CDS and ARCO are independent pipelines (CDS's own ERA5T is itself provisional and can differ in fine detail from what ARCO eventually ingests), so this CDS-sourced fallback is cached under yet another distinct name (<year><month>_arco_gap_cds.nc, in the per-run cache_dir, not the permanent world cache) rather than being trusted as equivalent to genuine ARCO data. It is never reused as a substitute once ARCO does ingest that month -- a later run will fetch and cache the real ARCO version normally.

HOURLY OUTPUT (-h)

Accumulated fields (precipitation, potential_evaporation, solar_radiation, snowfall) are correctly de-accumulated to genuine per-hour amounts, not just relabeled daily totals split evenly -- ECMWF's raw archive stores these as running totals since a periodic reset, not as hourly increments, so getting this right means differencing consecutive raw readings and special-casing the reset hour itself (which is already a genuine 1-hour amount, not a diff). Two DIFFERENT reset schedules are involved, handled separately and correctly for each source:

• ERA5-Land (reanalysis-era5-land, already used by the daily path for accumulated variables too): a single reset per calendar day, at 01 UTC.
• ARCO-ERA5 and plain-ERA5's own raw hourly CDS product: two 12h forecast cycles per day, based at 06 and 18 UTC (first genuine, non-diffed hour at 07 and 19 UTC respectively). Confirmed the same schedule applies to both: ARCO-ERA5 is an unmodified Zarr mirror of this exact same raw ERA5 archive, not a separately-behaving product (see ARCO-ERA5 SOURCE above), so plain-ERA5's raw hourly CDS product (reanalysis-era5-single-levels) reuses the identical ECMWF_CYCLE_RESET_HOURS = {7, 19} de-accumulation, not a separately-derived schedule.

Per-source-tier support

All three source tiers now support -h.

One real, non-obvious request-schema difference found while implementing the plain-ERA5 raw-hourly fetch: unlike reanalysis-era5-land (no ensemble/product-type concept at all), reanalysis-era5-single-levels is part of the same "single-levels" product family as fetch_era5()'s derived-daily-statistics product, and CDS's schema for that family requires an explicit product_type: "reanalysis" request key (distinguishing the deterministic reanalysis from CDS's separate ensemble-member products for the same physical field). fetch_era5_raw_hourly() carries this key, mirroring fetch_era5()'s own existing single-levels request; fetch_era5land_raw_hourly() correctly does NOT, since ERA5-Land has no such family/product-type distinction to make.

VARIABLES

CDS ACCOUNT SETUP

t.in.era5 uses the cdsapi Python package, which reads credentials from ~/.cdsapirc. Create a free account at https://cds.climate.copernicus.eu, accept the ERA5/ERA5-Land dataset licences on the CDS website (one-time, per dataset), then copy your personal access token from your CDS profile page into ~/.cdsapirc:

url: https://cds.climate.copernicus.eu/api
key: <your-personal-access-token>

EXAMPLE

g.region n=34 s=31 e=49 w=47 res=0:06 # ~0.1 deg, matches ERA5-Land's native grid

t.in.era5 variables=precipitation,temperature,potential_evaporation \
  start=2001-06-01 end=2001-08-31 \
  output_prefix=karkheh cache_dir=$HOME/era5_cache

r.hydro.hbv.forcing strds=karkheh_precipitation basins=basins \
  basins_vector=basins_v output_table=karkheh_precip_table

t.in.era5 -h variables=precipitation start=2001-06-01 end=2001-06-07 \
  output_prefix=karkheh_hourly cache_dir=$HOME/era5_cache
# -> karkheh_hourly_precipitation, one raster per hour (168 maps for
#    this 7-day window instead of 7)

SEE ALSO

AUTHOR

SOURCE CODE

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

Accessed: Sunday Sep 13 08:29:49 2026

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

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