era5-cds-point-download

name

era5-cds-point-download

description

Download Copernicus CDS ERA5 single-level point time-series climate forcing for non-US or non-NLDAS EcoSIM sites from longitude/latitude coordinates. Use when a paper-derived site is outside the NLDAS domain, lacks AmeriFlux/FLUXNET curated forcing, or needs global ERA5 variables such as 2m temperature, dewpoint temperature, surface pressure, solar radiation, precipitation, and 10m wind components for EcoSIM preprocessing.

ERA5 CDS Point Download

Overview

Use this skill to retrieve ERA5 single-level point time-series data from the Copernicus Climate Data Store (CDS) for literature sites outside the US/NLDAS workflow. The coordinate convention is longitude first, latitude second, with longitude in [-180, 180] and latitude in [-90, 90].

For US sites inside the NLDAS domain (-125 <= lon <= -67, 25 <= lat <= 53), prefer nldas-gesdisc-point-download unless the user explicitly asks for ERA5 or the paper requires an ERA5-consistent forcing source.

Required Setup

Use the CDS API instructions at https://cds.climate.copernicus.eu/how-to-api when credentials or local configuration are missing. The user must register or log in to locate their API key and configure cdsapi appropriately, usually through ~/.cdsapirc.

Prefer $HOME/.cdsapirc when it exists with url and key entries. This repository also supports fallback credentials from environment variables after sourcing ~/.bashrc: ERA5_USR and ERA5_PSSWD. Accept ERA5_PASSWD as a spelling fallback. If shell sourcing does not expose the values, the bundled script may directly parse simple export KEY=value assignments in ~/.bashrc; this handles unquoted API keys containing shell metacharacters such as &. Current CDS API setup expects the personal-access token without a deprecated <UID>: prefix, so pass ERA5_PSSWD or ERA5_PASSWD as the cdsapi.Client key only when using --credential-source env, and keep ERA5_USR only for compatibility/presence checks. Never print, persist, or echo API keys in result files or responses.

Install cdsapi only when needed. If network or package installation is required, request approval according to the active sandbox policy.

Default Variables

Download these variables for EcoSIM climate forcing preparation:

• 2m_dewpoint_temperature
• surface_pressure
• surface_solar_radiation_downwards
• 2m_temperature
• total_precipitation
• 10m_u_component_of_wind
• 10m_v_component_of_wind

Default dataset: reanalysis-era5-single-levels. This is the current CDS catalogue entry for ERA5 hourly single-level data. The older point-timeseries short name reanalysis-era5-single-levels-timeseries may be tested with --dataset reanalysis-era5-single-levels-timeseries --request-style timeseries, but if CDS returns endpoint or authorization errors, use the default gridded dataset with a small lon/lat bounding box and extract the nearest grid cell downstream.

Default date range, when the user does not specify a period: 1940-01-01/2025-10-01.

Bundled Script

Prefer the bundled script for repeatable requests and manifest writing:

python .agents/skills/era5-cds-point-download/scripts/download_era5_point_cds.py \
  --site-id Forbonnet-peatland \
  --lon 6.1722 \
  --lat 46.8264 \
  --date 1940-01-01/2025-10-01 \
  --output result/era5/Forbonnet-peatland_era5_single_levels_timeseries

For a current CDS single-levels smoke test, request one day from a small bounding box around the point:

python .agents/skills/era5-cds-point-download/scripts/download_era5_point_cds.py \
  --site-id Forbonnet-peatland \
  --lon 6.1722 \
  --lat 46.8264 \
  --date 2020-01-01/2020-01-01 \
  --output result/era5/Forbonnet-peatland_era5_20200101_test.grib

If the CDS credentials are stored in ~/.bashrc, source it in the shell that launches the script:

source ~/.bashrc >/dev/null 2>&1
python .agents/skills/era5-cds-point-download/scripts/download_era5_point_cds.py \
  --site-id Forbonnet-peatland \
  --lon 6.1722 \
  --lat 46.8264 \
  --date 2020-01-01/2020-01-02 \
  --output result/era5/Forbonnet-peatland_era5_test.grib

To force a source, use --credential-source cdsapirc or --credential-source env. By default, --credential-source auto prefers $HOME/.cdsapirc and falls back to the ERA5 environment variables or simple ~/.bashrc assignments.

Use --dry-run first when checking a paper extraction or CDS setup:

python .agents/skills/era5-cds-point-download/scripts/download_era5_point_cds.py \
  --site-id Forbonnet-peatland \
  --lon 6.1722 \
  --lat 46.8264 \
  --dry-run

The script writes a JSON manifest next to the downloaded file. The manifest records the dataset, variables, location, requested date range, output path, and timestamp, but never records credentials.

Convert to EcoSIM

After downloading the CDS point time-series ZIP, convert it to EcoSIM hourly climate forcing with:

.venv-cmip6/bin/python .agents/skills/era5-cds-point-download/scripts/convert_cds_era5_to_ecosim.py \
  --input result/era5/Forbonnet-peatland_era5_timeseries_19400101_20251001.zip \
  --output result/era5/Forbonnet-peatland_ecosim_climate_1940_2024.nc \
  --site-id Forbonnet-peatland \
  --lon 6.1722 \
  --lat 46.8264 \
  --quality-report result/era5/Forbonnet-peatland_ecosim_climate_1940_2024_quality.json \
  --forcing-yaml result/Forbonnet-peatland/Forbonnet-peatland_forcing.yaml

The converter accepts either the CDS ZIP or the extracted NetCDF. By default, it writes only complete UTC calendar years and drops partial first or last years, because EcoSIM climate arrays are annual year/day/hour blocks and partial years leave fill values inside a simulation year. Use --include-incomplete-years only when a partial-year diagnostic file is explicitly needed, and document the missing hours in the quality report.

The converter maps:

• t2m K to TMPH degC.
• sqrt(u10^2 + v10^2) to WINDH m s^-1.
• tp m to RAINH mm h^-1.
• d2m K to vapor pressure DWPTH kPa.
• ssrd J m^-2 hourly accumulation to SRADH W m^-2 by dividing by 3600.
• sp Pa to PATM kPa.

For US grids in the same auxiliary-data domain used by the US/AmeriFlux workflow (-125 <= lon <= -67, 25 <= lat <= 53), the converter defaults to --add-us-chemistry auto and adds annual EcoSIM precipitation chemistry variables from NADP rasters under data/nadp_data_grids:

• PHRG: pH in precipitation.
• CN4RIG: NH4-N concentration in precipitation.
• CNORIG: NO3-N concentration in precipitation.
• CSORG: SO4-S concentration in precipitation.
• CCARG: Ca concentration in precipitation.
• Other template chemistry variables supported by Tools/create_ecosim_climate_forcing.py, including CMGRG, CNARG, CKARG, and CCLRG when NADP source rasters exist.

NADP values are validated the same way as US/AmeriFlux climate forcing: reject NoData, non-finite, negative concentrations, and pH outside 0-14; fill annual gaps by linear interpolation with nearest-edge filling; if no valid PHRG exists, use neutral PHRG=7 and record the fallback. Use --add-us-chemistry never to skip this for a US grid, or --add-us-chemistry always to force it. Use --chemistry-input to point to another NADP raster directory and --chemistry-output to set the intermediate JSON path.

For non-US grids, do not silently add NADP-derived chemistry. Leave the annual chemistry variables absent unless the user supplies an appropriate regional precipitation-chemistry source or asks for a site-specific mapping. When a non-US site needs annual EcoSIM precipitation chemistry, use global-aux-climate-chemistry to stage CAMS first, then EBAS/EANET station overrides or MERRA-2 fallback context as appropriate.

Use .venv-cmip6/bin/python for conversion because it includes xarray and netCDF4.

Minimal CDS API Pattern

When writing a one-off Python snippet, use this request shape:

import cdsapi

def download_era5_climate(lon=123.75, lat=44.75):
    dataset = "reanalysis-era5-single-levels-timeseries"
    request = {
        "variable": [
            "2m_dewpoint_temperature",
            "surface_pressure",
            "surface_solar_radiation_downwards",
            "2m_temperature",
            "total_precipitation",
            "10m_u_component_of_wind",
            "10m_v_component_of_wind",
        ],
        "location": {"longitude": lon, "latitude": lat},
        "date": ["1940-01-01/2025-10-01"],
    }

    client = cdsapi.Client()
    client.retrieve(dataset, request).download()

EcoSIM Unit Cautions

Before converting ERA5 output to EcoSIM NetCDF, inspect the returned file metadata because CDS response format and accumulation conventions can differ by service version.

Core conversions commonly needed:

• 2m_temperature: K to degC for TMPH.
• 10m_u_component_of_wind and 10m_v_component_of_wind: scalar wind speed sqrt(u^2 + v^2) for WINDH.
• 2m_dewpoint_temperature: derive vapor pressure in kPa for DWPTH.
• surface_pressure: Pa to kPa for PATM.
• surface_solar_radiation_downwards: if accumulated energy in J m^-2, divide by the accumulation interval in seconds for SRADH in W m^-2.
• total_precipitation: convert accumulated water depth to hourly RAINH; check whether source units are meters of water equivalent or another accumulation convention.

Run physical range checks before writing EcoSIM forcing:

• TMPH: -90 to 60 degC.
• WINDH: 0 to 75 m s^-1.
• RAINH: non-negative.
• DWPTH: 0 to 15 kPa.
• SRADH: 0 to 1400 W m^-2.
• PATM: 50 to 110 kPa.

Reporting

For any delivered ERA5 extraction, report:

• Dataset name and requested date range.
• Requested longitude/latitude.
• Variables requested.
• Output path and manifest path.
• Whether cdsapi credentials were configured through $HOME/.cdsapirc, ERA5_USR/ERA5_PSSWD, or ERA5_USR/ERA5_PASSWD, without revealing credential values.
• Any unresolved unit or format assumptions that must be checked before EcoSIM conversion.