Fetching data

Available as climate_toolkit.fetch_climate_data.

climate_toolkit.fetch_data.fetch_data.fetch_data

fetch_data(
    source,
    location_coord=None,
    variables=None,
    date_from=None,
    date_to=None,
    settings=None,
    model=None,
    scenario=None,
    stage="preprocessed",
    verbose=True,
    cache_dir=None,
    refresh_cache=False,
    sites=None,
    sites_csv=None,
    station_id=None,
    workers=1,
)

Fetch climate data through the pipeline (source -> transform -> preprocess).

Also exported as climate_toolkit.fetch_climate_data.

Parameters:

Name	Type	Description	Default
source	str or ClimateDataset	Climate dataset name. Valid values (ClimateDataset enum names): 'agera_5' : ERA5-Land daily aggregates (GEE asset ECMWF/ERA5_LAND/DAILY_AGGR), 0.1 deg (~11 km), 1979-present. Broadest daily variable set: precipitation, max/min/mean temperature, humidity, wind_speed, solar_radiation (request companions explicitly). Recommended default. Earth Engine. 'era_5' : ERA5 daily reanalysis, 0.25 deg (~28 km), from 1979. The static coverage window ends 2020-07-09 (the ECMWF/ERA5/DAILY GEE asset); live GEE coverage is checked at runtime and requests are clipped to it, with a hint to use 'agera_5' for later periods. Precipitation, max/min temperature, wind. Earth Engine. 'terraclimate' : TerraClimate monthly climate/water balance, ~4 km, 1958-present. Monthly cadence. Earth Engine. 'imerg' : GPM IMERG v07 satellite precipitation, 0.1 deg, 2000-present. Precipitation only. Earth Engine. 'chirps_v2' (alias 'chirps') : CHIRPS v2 daily blended satellite-gauge precipitation, 0.05 deg (~5.5 km), 1981-present. Precipitation only. Earth Engine. 'chirps_v3_daily_rnl' : CHIRPS v3 daily precipitation, 0.05 deg, 1981-present. Precipitation only. Earth Engine. 'chirts' : CHIRTS daily satellite-station temperature, 0.05 deg, 1983-2016. Max/min temperature. Earth Engine. 'cmip_6' : NASA GDDP-CMIP6 downscaled projections, 0.25 deg. Precipitation, max/min temperature. Earth Engine. 'nex_gddp' : NEX-GDDP-CMIP6 downscaled projections, 0.25 deg; historical runs end 2014-12-31, scenario runs start 2015-01-01. Requires model and scenario. Precipitation, max/min temperature, humidity. Earth Engine. 'nasa_power' : NASA POWER daily point data, ~0.5 deg, 1984-present. Precipitation, max/min/mean temperature, humidity. Plain HTTPS API; no Earth Engine setup needed. 'tamsat' : TAMSAT v3.1 African rainfall + soil moisture, 0.05 deg (~4 km), Africa only, 1983-present. Direct download; no Earth Engine setup needed. 'ghcn_daily', 'gsod' : point station observations (see station_id). No Earth Engine setup needed. 'soil_grid' (ISRIC SoilGrids, 250 m), 'hwsd' (FAO HWSD v2, ~1 km) : static soil properties (use SoilVariable members). Earth Engine. Full dataset descriptions: see docs/datasets.md (or the "Datasets" page of the documentation site). Legacy aliases such as 'era5', 'agera5', 'nasapower', 'nexgddp', and 'ghcn' are normalised automatically. Earth Engine sources require prior earthengine authenticate and a project ID in the GCP_PROJECT_ID (or GOOGLE_CLOUD_PROJECT / EE_PROJECT_ID) environment variable.	required
location_coord	tuple[float, float]	(latitude, longitude) in decimal degrees for single-site fetches. Required unless sites or sites_csv is given.	None
variables	list	ClimateVariable and/or SoilVariable enum members. Import with from climate_toolkit.fetch_data.source_data.sources.utils.models import ClimateVariable. Valid ClimateVariable names: rainfall, max_temperature, min_temperature, mean_temperature, precipitation, wind_speed, solar_radiation, humidity, soil_moisture. Defaults to a standard climate + soil set (precipitation, max/min temperature, solar radiation, soil moisture, wind speed, humidity, plus SoilGrids properties); for ghcn_daily and gsod the default is precipitation, max_temperature, min_temperature.	None
date_from	date	Inclusive date range. Both default to today. The range is clipped to the source's known coverage window (a warning is printed when clipping occurs; a ValueError is raised if no overlap remains).	None
date_to	date	Inclusive date range. Both default to today. The range is clipped to the source's known coverage window (a warning is printed when clipping occurs; a ValueError is raised if no overlap remains).	None
settings	Settings	Loaded package settings. Auto-loaded via Settings.load() if not provided.	None
model	str	Required only for 'nex_gddp': a GCM name (e.g. 'GFDL-ESM4', 'ACCESS-CM2') and an SSP scenario (e.g. 'ssp245', 'ssp585').	None
scenario	str	Required only for 'nex_gddp': a GCM name (e.g. 'GFDL-ESM4', 'ACCESS-CM2') and an SSP scenario (e.g. 'ssp245', 'ssp585').	None
stage	(raw, transformed, preprocessed)	How far through the pipeline to run: 'raw' downloads only, 'transformed' also standardises column names/units, and 'preprocessed' (default) additionally applies cleaning/QC.	'raw'
verbose	bool	Print progress and diagnostic messages while fetching.	True
cache_dir	str or Path	Project-local cache root for downloaded data (reuse a stable path for fast repeat runs). If omitted, supported sources fall back to their default project-local cache layout.	None
refresh_cache	bool	Bypass any saved cache files and force a cold fetch.	False
sites	list	Many-site input; when given (or sites_csv), the package-native batch path is used instead of location_coord. Each item may be a Site, a dict with name/lat/lon keys, or a (name, lat, lon) tuple. Batch fetching is supported for nex_gddp and the GEE/Xee sources (agera_5, era_5, terraclimate, imerg, chirps_v2, chirps_v3_daily_rnl, chirts, cmip_6).	None
sites_csv	str or Path	Path to a CSV of sites with required columns name, lat, lon. May be combined with sites; duplicates are removed.	None
station_id	str	Station identifier for station-backed sources (ghcn_daily, gsod). If omitted, the nearest station to location_coord is used.	None
workers	int	Bounded worker count for historical GEE/Xee fetch tasks. Mainly useful for multi-site or long-period historical runs.	1

Returns:

Type	Description
DataFrame	For single-site fetches at the default stage: one row per date with a date column plus one column per requested variable (canonical names such as precipitation, max_temperature). Many-site fetches additionally include site, lat, and lon columns (and model/scenario for nex_gddp). stage='raw' returns source-native column names.

Examples:

Daily weather for Nairobi from NASA POWER (no Earth Engine needed):

>>> from datetime import date
>>> import climate_toolkit as ct
>>> from climate_toolkit.fetch_data.source_data.sources.utils.models import (
...     ClimateVariable,
... )
>>> df = ct.fetch_climate_data(
...     source="nasa_power",
...     location_coord=(-1.286, 36.817),
...     variables=[
...         ClimateVariable.precipitation,
...         ClimateVariable.max_temperature,
...         ClimateVariable.min_temperature,
...     ],
...     date_from=date(2020, 1, 1),
...     date_to=date(2020, 12, 31),
... )

NEX-GDDP projections (requires Earth Engine auth and GCP_PROJECT_ID):

>>> df = ct.fetch_climate_data(
...     source="nex_gddp",
...     location_coord=(-1.286, 36.817),
...     variables=[ClimateVariable.precipitation,
...                ClimateVariable.max_temperature],
...     date_from=date(2050, 1, 1),
...     date_to=date(2050, 12, 31),
...     model="GFDL-ESM4",
...     scenario="ssp245",
... )