tools.geetools

class tools.geetools.CMIPDownloader(var, starty, endy, shape, processes=10, dir='./')[source]

Class to download spatially averaged CMIP6 data for a given period, variable, and spatial subset.

download()[source]: Runs a subset routine for CMIP6 data on GEE servers to create ee.FeatureCollections for all years in the requested period. Downloads individual years in parallel processes to increase the download time.

class tools.geetools.CMIPDownloaderManifest(starty, endy, catchment, variables=None, dir='./', manifest_concurrent=6, download_workers=10, block_size_years=None, config_path=None, show_progress=True)[source]

Fast CMIP6 downloader using the /cmip6-manifest endpoint.

The MATILDA webservice generates signed Earth Engine download URLs. This helper downloads those files directly in parallel and saves them with the same filenames expected by CMIPProcessor.

class tools.geetools.CMIPDownloaderWebservice(starty, endy, catchment, variables=None, dir='./', max_concurrent=6, block_size_years=None, config_path=None, show_progress=True)[source]

Download spatially averaged CMIP6 yearly CSV files from the MATILDA webservice.

This class mirrors the output of the local CMIPDownloader, but uses the /cmip6-data endpoint. It is designed as a low-disruption bridge so that CMIPProcessor can remain unchanged.

Parameters:

starty (int) – First year to request.
endy (int) – Last year to request.
catchment (dict or geopandas.GeoDataFrame or shapely geometry) – Catchment geometry to send to the webservice.
variables (list of str, optional) – Variables to request. Default is [“tas”, “pr”].
dir (str, optional) – Output directory for yearly CSV files.
max_concurrent (int, optional) – Concurrency passed to the webservice endpoint.
block_size_years (int or None, optional) – If given, split each variable request into year blocks of this size. If None, request each variable over the full time period.
config_path (str or Path, optional) – Optional path to webservices.ini.
show_progress (bool, optional) – Whether to print progress information.

download()[source]

Download all requested variables and save yearly CSV files locally.

Returns:: Summary of downloaded years by variable.
Return type:: dict

class tools.geetools.CMIPProcessor(var, file_dir='.')[source]

Class to read and pre-process CSV files downloaded by the CMIPDownloader class.

append_df(var, file_dir='.', hist=True)[source]: Reads CMIP6 CSV files of individual years and concatenates them into dataframes for the full downloaded period. Historical and scenario datasets are treated separately. Converts precipitation unit to mm.

get_results()[source]: Concatenates historical and scenario data to combined dataframes of the full downloaded period. Arranges the models in alphabetical order.

process_dataframes()[source]: Separates the two scenarios and drops models not available for both scenarios and the historical period.

read_cmip(filename)[source]: Reads CMIP6 CSV files and drops redundant columns.

tools.geetools.authenticate_and_initialize_ee(cloud_project)[source]

Robustly authenticates and initializes Earth Engine for local/notebook environments.

It attempts to initialize Earth Engine: 1. Using existing credentials if available and valid for the project. 2. If a permission error occurs, it forces a new interactive browser-based

authentication suitable for notebooks.

Parameters:: cloud_project (str) – The Google Cloud Project ID to use for Earth Engine.
Raises:: RuntimeError – If Earth Engine initialization ultimately fails after retries.

tools.geetools.delineate_catchment_local(lat, lon, dem_filename, catchment_filename, asset_id, buffer_m=40000, bbox=None, snap_acc_threshold=1000, config_path=None)[source]

Delineate a catchment locally with pysheds after downloading a DEM.

The function uses the MATILDA DEM webservice to download a DEM either for a default square around the outlet point or for a custom bounding box. It then performs local delineation with pysheds.

If the resulting catchment touches the DEM boundary, the DEM extent is likely too small and the function raises an error asking the user to provide a custom lat/lon bounding box.

Parameters:

lat (float) – Latitude of the outlet / pour point.
lon (float) – Longitude of the outlet / pour point.
dem_filename (str or Path) – Output path for the downloaded DEM GeoTIFF.
catchment_filename (str or Path) – Output path for the delineated catchment GeoJSON.
asset_id (str) – Earth Engine asset ID of the DEM to download.
buffer_m (int or float, optional) – Buffer radius in meters for the default DEM download box. Ignored when bbox is provided.
bbox (list or tuple, optional) – Custom bounding box in geographic coordinates: [xmin, ymin, xmax, ymax].
snap_acc_threshold (int or float, optional) – Accumulation threshold used to snap the outlet point to the channel network. Default is 1000.
config_path (str or Path, optional) – Optional path to webservices.ini.

Returns:

(catchment_gdf, info)

catchment_gdfgeopandas.GeoDataFrame: Delineated catchment polygon.
infodict: Dictionary with useful diagnostics: - dem_filename - catchment_filename - snapped_lon - snapped_lat - bbox_used - edge_touched

Return type:

tuple

Raises:

RuntimeError – If delineation fails or if the DEM extent appears too small.
ValueError – If bbox is invalid.

tools.geetools.delineate_catchment_mghydro(lat, lon, watershed_output_path, rivers_output_path=None, precision='high', plot=False, timeout=120, fallback_to_local=False, fallback_dem_asset_id='MERIT/DEM/v1_0_3', fallback_dem_filename='dem_gee.tif', fallback_buffer_m=40000, fallback_bbox=None, dem_config_path=None)[source]

Delineate a catchment and fetch upstream rivers from the MG Hydro / Global Watersheds API.

This helper uses the public API of the Global Watersheds web app: https://mghydro.com/watersheds/

API/help documentation: https://mghydro.com/watersheds/help.html

Python demo notebook by the author: https://mghydro.com/demo-use-the-global-watersheds-api-and-python-to-automatically-delineate-watersheds/

Author / maintainer: Matthew Heberger (mheberger) https://github.com/mheberger https://mghydro.com/author/mheberger/

Notes

The Global Watersheds app and API are based on global hydrographic datasets including MERIT-Hydro / MERIT-Basins and provide fast watershed delineation and upstream river extraction. The service is very useful for rapid catchment screening, but results should always be checked visually before further use in analysis workflows.

Parameters:

lat (float) – Latitude of the outlet / pour point.
lon (float) – Longitude of the outlet / pour point.
watershed_output_path (str or Path) – Output path for the watershed GeoJSON.
rivers_output_path (str or Path, optional) – Output path for the upstream rivers GeoJSON. If None, a filename based on watershed_output_path is created.
precision (str, optional) – Delineation precision, either ‘low’ or ‘high’. Default is ‘high’. For very large basins, the service may automatically fall back to lower precision.
plot (bool, optional) – If True, create a quick visual check plot with catchment boundary, river network, and outlet point.
timeout (int, optional) – Timeout in seconds for each API request.
fallback_to_local (bool, optional) – If True, fall back to local pysheds delineation when the MG Hydro request fails. Default is False.
dem_asset_id (str, optional) – Earth Engine asset ID of the DEM used for local fallback delineation.
dem_filename (str or Path, optional) – DEM filename used for local fallback delineation.
fallback_buffer_m (int or float, optional) – Default buffer radius in meters for local fallback delineation.
fallback_bbox (list or tuple, optional) – Optional custom bounding box [xmin, ymin, xmax, ymax] for local fallback delineation. If None, the user is prompted for a bbox.
dem_config_path (str or Path, optional) – Optional path to webservices.ini for local DEM download.

Returns:

(watershed_gdf, rivers_gdf)

Return type:

tuple

Raises:

ValueError – If precision is invalid.
RuntimeError – If the API request fails or returns invalid data.

tools.geetools.download_dem_for_bbox(bbox, output_path, asset_id, config_path=None)[source]

Download a DEM for a custom geographic bounding box.

Parameters:

bbox (list or tuple) – Bounding box as [xmin, ymin, xmax, ymax] in lon/lat coordinates.
output_path (str or Path) – Local output path for the downloaded GeoTIFF.
asset_id (str) – Earth Engine asset ID of the DEM.
config_path (str or Path, optional) – Optional path to webservices.ini.

Returns:

Path to the saved GeoTIFF file.

Return type:

Path

Raises:

ValueError – If bbox is invalid.

tools.geetools.download_dem_webservice(output_path, asset_id, lat=None, lon=None, buffer_m=None, geometry=None, config_path=None)[source]

Download a DEM GeoTIFF from the MATILDA webservice and save it locally.

Parameters:

output_path (str or Path) – Local output path for the downloaded GeoTIFF.
asset_id (str) – Earth Engine asset ID of the DEM.
lat (float, optional) – Latitude of the pour point. Must be used together with lon.
lon (float, optional) – Longitude of the pour point. Must be used together with lat.
buffer_m (int or float, optional) – Buffer radius in meters used to create the request box when using lat/lon input.
geometry (dict or geopandas.GeoDataFrame or shapely geometry, optional) – Polygon geometry to send directly to the webservice. This is the preferred option when a catchment outline is already available.
config_path (str or Path, optional) – Optional path to webservices.ini.

Returns:

Path to the saved GeoTIFF file.

Return type:

Path

Raises:

ValueError – If neither a valid point+buffer nor a valid geometry is provided.
RuntimeError – If the webservice request fails or returns unexpected content.

tools.geetools.get_climate_data_webservice(catchment, date_range, config_path=None, show_progress=True, max_concurrent=6)[source]

Request spatially aggregated ERA5-Land forcing data from the MATILDA webservice and return them as a pandas DataFrame.

The webservice streams one JSON record per year (NDJSON).

tools.geetools.get_geopotential_webservice(catchment, config_path=None, asset_id=None, band=None, show_progress=True)[source]

Request catchment-mean geopotential and reference elevation from the MATILDA webservice.

Parameters:

catchment (dict or geopandas.GeoDataFrame or shapely geometry) – Catchment geometry as a GeoJSON FeatureCollection, GeoDataFrame, or shapely geometry. If a GeoDataFrame or shapely geometry is provided, it will be converted to a FeatureCollection payload.
config_path (str or Path, optional) – Optional path to webservices.ini.
asset_id (str, optional) – Optional override of the geopotential Earth Engine asset.
band (str, optional) – Optional override of the band name.
show_progress (bool, optional) – If True, show a simple live status message while the request runs.

Returns:

Dictionary with keys: - “geopotential_mean” - “elevation_m”

Return type:

dict

Raises:

RuntimeError – If the webservice request fails or returns malformed output.

tools.geetools.load_webservice_config(config_path=None, section='GOOGLE', prompt_for_api_key=True)[source]

Load settings from webservices.ini.

Parameters:

config_path (str or Path, optional) – Path to webservices.ini. If None, defaults to repo_root/webservices.ini assuming this file lives in repo_root.
section (str, optional)
prompt_for_api_key (bool, optional) – If True and section is [GOOGLE], prompt interactively for an API key when neither MATILDA_API_KEY nor PUBLIC_API_KEY is available.

Returns:

Dictionary with keys and values from the requested section.

Return type:

dict

Raises:

FileNotFoundError – If the config file does not exist.
KeyError – If the requested section is missing.
ValueError – If required keys for the section are missing.

tools.geetools.resolve_api_key(config=None, env_var='MATILDA_API_KEY', prompt_if_missing=True)[source]

Resolve the MATILDA webservice API key.

Priority

MATILDA_API_KEY environment variable
PUBLIC_API_KEY from webservices.ini
Interactive prompt (optional)