GloFAS historical — the intermediate stream¶

The Global Flood Awareness System (GloFAS) river reanalysis on the CEMS Early Warning Data Store ships as two streams of the same CDS dataset (cems-glofas-historical):

Stream	Latency	What it is
consolidated	~2-3 months behind	the final, quality-controlled reanalysis
intermediate	~2-5 days behind	an ERA5T-driven stream filling the recent weeks the consolidated has not reached

earthlens curates the intermediate as its own catalog id, cems-glofas-historical-intermediate, so you can ask for "the latest available" discharge without hand-editing product_type. This notebook downloads it live over the Danube basin, maps the river discharge, and walks through the four variables it exposes.

API: earthlens.core.EarthLens · dataset cems-glofas-historical-intermediate (EWDS endpoint).

Requires a Copernicus token in ~/.cdsapirc and the GloFAS licence accepted once at https://ewds.climate.copernicus.eu/datasets/cems-glofas-historical.

Setup¶

We download to a notebook-relative out/ folder — each variable is only a few tens of KB for this small two-day Danube window, so nothing large lands on disk.

In [ ]:

Copied!

from pathlib import Path

from pyramids.netcdf import NetCDF
from pyramids.plot import Basemap, ColorBar, ColorScaling, Feature

from earthlens.core import EarthLens

DATASET = "cems-glofas-historical-intermediate"
OUT = Path("out")
DANUBE = {"lat_lim": [44.0, 48.5], "lon_lim": [16.0, 22.0]}  # a Danube-basin bbox
from pathlib import Path

from pyramids.netcdf import NetCDF
from pyramids.plot import Basemap, ColorBar, ColorScaling, Feature

from earthlens.core import EarthLens

DATASET = "cems-glofas-historical-intermediate"
OUT = Path("out")
DANUBE = {"lat_lim": [44.0, 48.5], "lon_lim": [16.0, 22.0]}  # a Danube-basin bbox

Quickstart — download river discharge¶

The shortest end-to-end call: two days of mean daily river discharge over the Danube. variables maps the dataset id to the variables you want; download() returns the written file paths.

In [ ]:

Copied!





lens = EarthLens(
    data_source="ecmwf",
    variables={DATASET: ["average-river-discharge-in-the-last-24-hours"]},
    start="2026-06-15",
    end="2026-06-16",
    temporal_resolution="daily",
    path=OUT,
    **DANUBE,
)
discharge_files = lens.download()
discharge_files
lens = EarthLens(
    data_source="ecmwf",
    variables={DATASET: ["average-river-discharge-in-the-last-24-hours"]},
    start="2026-06-15",
    end="2026-06-16",
    temporal_resolution="daily",
    path=OUT,
    **DANUBE,
)
discharge_files = lens.download()
discharge_files

Notice the file name ends in ..._cems-glofas-historical-intermediate.nc — earthlens names the output by the requested catalog id, not the underlying CDS dataset (cems-glofas-historical). That is why the intermediate and consolidated streams never overwrite each other on disk even though they retrieve from the same CDS dataset.

In [ ]:

Copied!

discharge_files[0].name
discharge_files[0].name

Map the discharge¶

Open the NetCDF and plot the mean daily discharge on a log colour scale (discharge spans several orders of magnitude, from headwater cells to the Danube main stem). Zero / land cells are masked.

In [ ]:

Copied!





nc = NetCDF.read_file(discharge_files[0], read_only=True)
dis = nc.get_variable("avg_dis")
stats = dis.stats(approx_ok=False)
print(f"grid {dis.rows} x {dis.columns}, epsg {dis.epsg}")
print(
    f"discharge min/max: {float(stats['min'].iloc[0]):.1f} / "
    f"{float(stats['max'].iloc[0]):.1f} m3 s-1"
)

# Discharge spans several orders of magnitude across a basin, so a log scale is the
# readable one. cleopatra gained ColorScaling.log() in 0.37 (serapeum-org/cleopatra#329).
#
# Country borders give the basin somewhere to sit. They draw over the field, which
# is what this plot needs: every cell carries a value (land reads 0 m3 s-1 rather
# than nodata), so a filled `land` or `relief` layer underneath would be completely
# hidden. Natural Earth `rivers` is deliberately left off -- the raster already is
# the river network, and a second one on top of it would only confuse the two.
dis.plot(
    cmap="Blues",
    color=ColorScaling.log(),
    basemap=Basemap(
        relief=False,
        resolution="50m",
        features=[
            Feature("borders", colors="#3a3a3a", linewidths=0.9),
            Feature("coastline", colors="#222222", linewidths=0.9),
        ],
    ),
    colorbar=ColorBar(label="discharge (m3 s-1)"),
    title="GloFAS intermediate - mean river discharge, 2026-06-15 (Danube basin)",
)
nc.close()  # release the file handle before the next download
nc = NetCDF.read_file(discharge_files[0], read_only=True)
dis = nc.get_variable("avg_dis")
stats = dis.stats(approx_ok=False)
print(f"grid {dis.rows} x {dis.columns}, epsg {dis.epsg}")
print(
    f"discharge min/max: {float(stats['min'].iloc[0]):.1f} / "
    f"{float(stats['max'].iloc[0]):.1f} m3 s-1"
)

# Discharge spans several orders of magnitude across a basin, so a log scale is the
# readable one. cleopatra gained ColorScaling.log() in 0.37 (serapeum-org/cleopatra#329).
#
# Country borders give the basin somewhere to sit. They draw over the field, which
# is what this plot needs: every cell carries a value (land reads 0 m3 s-1 rather
# than nodata), so a filled `land` or `relief` layer underneath would be completely
# hidden. Natural Earth `rivers` is deliberately left off -- the raster already is
# the river network, and a second one on top of it would only confuse the two.
dis.plot(
    cmap="Blues",
    color=ColorScaling.log(),
    basemap=Basemap(
        relief=False,
        resolution="50m",
        features=[
            Feature("borders", colors="#3a3a3a", linewidths=0.9),
            Feature("coastline", colors="#222222", linewidths=0.9),
        ],
    ),
    colorbar=ColorBar(label="discharge (m3 s-1)"),
    title="GloFAS intermediate - mean river discharge, 2026-06-15 (Danube basin)",
)
nc.close()  # release the file handle before the next download

The bright network traces the Danube and its tributaries: discharge accumulates downstream, so the main stem carries the highest values while headwater cells stay faint.

The four variables — and the `timespan` twist¶

The intermediate stream exposes four variables. Two are fluxes / means served under timespan=time_mean, and two are instantaneous states the archive only serves under timespan=instantaneous. earthlens encodes that split per variable, so you never have to remember it:

Variable	NetCDF name	units	`timespan`
`average-river-discharge-in-the-last-24-hours`	`avg_dis`	m³ s⁻¹	`time_mean`
`runoff-water-equivalent`	`rowe`	kg m⁻²	`time_mean`
`snow-depth-water-equivalent`	`sd`	kg m⁻²	`instantaneous`
`soil-wetness-index`	`swir`	1 (index)	`instantaneous`

You can read that straight off the catalog row:

In [ ]:

Copied!

from earthlens.ecmwf import Catalog

for name, var in Catalog().datasets[DATASET].variables.items():
    print(f"{name:44} {var}  timespan={var.extras.get('timespan')}")
from earthlens.ecmwf import Catalog

for name, var in Catalog().datasets[DATASET].variables.items():
    print(f"{name:44} {var}  timespan={var.extras.get('timespan')}")

Download all four at once¶

Ask for every variable in one call. earthlens issues one retrieve per variable and applies the correct timespan to each — the two instantaneous state variables would 400 under time_mean, so getting this right automatically is the point of curating the row.

In [ ]:

Copied!





all_vars = EarthLens(
    data_source="ecmwf",
    variables={
        DATASET: [
            "average-river-discharge-in-the-last-24-hours",
            "runoff-water-equivalent",
            "snow-depth-water-equivalent",
            "soil-wetness-index",
        ]
    },
    start="2026-06-15",
    end="2026-06-16",
    temporal_resolution="daily",
    path=OUT,
    **DANUBE,
).download()
sorted(p.name for p in all_vars)
all_vars = EarthLens(
    data_source="ecmwf",
    variables={
        DATASET: [
            "average-river-discharge-in-the-last-24-hours",
            "runoff-water-equivalent",
            "snow-depth-water-equivalent",
            "soil-wetness-index",
        ]
    },
    start="2026-06-15",
    end="2026-06-16",
    temporal_resolution="daily",
    path=OUT,
    **DANUBE,
).download()
sorted(p.name for p in all_vars)

All four land as separate NetCDFs (one per variable). Each carries its short GRIB variable name (avg_dis, rowe, sd, swir) — the values you would index with pyramids or pyramids.

Takeaway¶

cems-glofas-historical-intermediate gives you GloFAS discharge for the recent weeks the consolidated reanalysis has not caught up to, through the same EarthLens call.
It is a curated alias of cems-glofas-historical, so earthlens routes the retrieve to the real CDS dataset but names the output by the requested id — the two streams coexist on disk.
The four variables carry their real NetCDF names and the correct per-variable timespan, so discharge / runoff (time_mean) and snow-depth / soil-wetness (instantaneous) all download in one call.

See the EWDS reference for the full GloFAS / CEMS-fire / EFAS catalog.

GloFAS historical — the intermediate stream¶

Setup¶

Quickstart — download river discharge¶

Map the discharge¶

The four variables — and the timespan twist¶

Download all four at once¶

Takeaway¶

The four variables — and the `timespan` twist¶