ochanticipy.datasources.glofas package

Submodules

ochanticipy.datasources.glofas.forecast module

Download and process GloFAS forecast and reforecast river discharge data.

class ochanticipy.datasources.glofas.forecast.GlofasForecast(country_config: CountryConfig, geo_bounding_box: GeoBoundingBox, leadtime_max: int, start_date: date | str = None, end_date: date | str = None, model_version: int = 4)

Bases: Glofas

Class for downloading and processing GloFAS forecast data.

The GloFAS forecast dataset is a global raster presenting river discharge forecast from 26 May 2021 until present day (updated daily), see this paper for more details. While CDS does have version 3 pre-release data from 2020-2021, we understand that there were some small issues that were fixed in the final version, so at this point in time this module does not support downloading the pre-release data.

This class downloads the raw raster data from CDS, and processes it from a raster to a datasets of reporting points from the GloFAS interface. Due to the CDS request size limits, separate files are downloaded per day (that contain all requested lead times).

Parameters:

• country_config (CountryConfig) – Country configuration

• geo_bounding_box (GeoBoundingBox) – The bounding coordinates of the area that should be included

• leadtime_max (int) – The maximum desired lead time D in days. All forecast data for lead times 1 to D days are downloaded

• start_date (Union[date, str], default: date(year=2021, month=5, day=26)) – The starting date for the dataset. If left blank, defaults to the earliest available date

• end_date (Union[date, str], default: date.today()) – The ending date for the dataset. If left blank, defaults to the current date

• model_version (int, default: 4) – The version of the GloFAS model to use, can only be 3 or 4. If in doubt, always use the latest (default).

Examples

Download, process and load GloFAS forecast data for the past month, for a lead time of 15 days.

>>> from datetime import date
>>> from ochanticipy import create_country_config, CodAB, GeoBoundingBox,
... GlofasForecast
>>>
>>> country_config = create_country_config(iso3="npl")
>>> codab = CodAB(country_config=country_config)
>>> codab.download()
>>> admin_npl = codab.load()
>>> geo_bounding_box = GeoBoundingBox.from_shape(admin_npl)
>>>
>>> glofas_forecast = GlofasForecast(
...     country_config=country_config,
...     geo_bounding_box=geo_bounding_box,
...     leadtime_max=15,
...     end_date=date(year=2022, month=10, day=22),
...     start_date=date(year=2022, month=9, day=22)
... )
>>> glofas_forecast.download()
>>> glofas_forecast.process()
>>>
>>> npl_glofas_forecast_reporting_points = glofas_forecast.load()

class ochanticipy.datasources.glofas.forecast.GlofasReforecast(country_config: CountryConfig, geo_bounding_box: GeoBoundingBox, leadtime_max: int, start_date: date | str = None, end_date: date | str = None, model_version: int = 4)

Bases: Glofas

Class for downloading and processing GloFAS reforecast data.

The GloFAS reforecast dataset is a global raster presenting river discharge forecasted from 1999 until 2018, see this paper for more details.

This class downloads the raw raster data from CDS, and processes it from a raster to a datasets of reporting points from the GloFAS interface. Due to the CDS request size limits, separate files are downloaded per month (that contain all requested lead times).

Parameters:

• country_config (CountryConfig) – Country configuration

• geo_bounding_box (GeoBoundingBox) – The bounding coordinates of the area that should be included

• leadtime_max (int) – The maximum desired lead time D in days. All forecast data for lead times 1 to D days are downloaded

• start_date (Union[date, str], default: date(year=1999, month=1, day=1)) – The starting date for the dataset. If left blank, defaults to the earliest available date

• end_date (Union[date, str], default: date(year=2018, month=12, day=31)) – The ending date for the dataset. If left blank, defaults to the last available date

• model_version (int, default: 4) – The version of the GloFAS model to use, can only be 3 or 4. If in doubt, always use the latest (default).

Examples

Download, process and load all available GloFAS reforecast data for a lead time of 15 days.

>>> from ochanticipy import create_country_config, CodAB, GeoBoundingBox,
... GlofasReforecast
>>>
>>> country_config = create_country_config(iso3="npl")
>>> codab = CodAB(country_config=country_config)
>>> codab.download()
>>> admin_npl = codab.load()
>>> geo_bounding_box = GeoBoundingBox.from_shape(admin_npl)
>>>
>>> glofas_reforecast = GlofasReforecast(
...     country_config=country_config,
...     geo_bounding_box=geo_bounding_box,
...     leadtime_max=15
... )
>>> glofas_reforecast.download()
>>> glofas_reforecast.process()
>>>
>>> npl_glofas_reforecast_reporting_points = glofas_reforecast.load()

ochanticipy.datasources.glofas.glofas module

Base class for downloading and processing GloFAS river discharge data.

class ochanticipy.datasources.glofas.glofas.Glofas(country_config: CountryConfig, geo_bounding_box: GeoBoundingBox, cds_name: str, model_version: int, product_type: str | List[str], date_variable_prefix: str, frequency: int, coord_names: List[str], start_date_min: date, end_date_max: date = None, start_date: date | str = None, end_date: date | str = None, leadtime_max: int = None, month_list: List[int] = None)

Bases: DataSource

Base class for all GloFAS data downloading and processing.

Parameters:

• country_config (CountryConfig) – Country configuration

• geo_bounding_box (GeoBoundingBox) – The bounding coordinates of the area that should be included

• cds_name (str) – The name of the dataset in CDS

• model_version (int) – The version of the model to use, can only be 3 or 4. Converted to system_version for the CDS query.

• product_type (str or list) – Which product types from the dataset are requested

• date_variable_prefix (str) – Some dates require a prefix for the CDS API query

• frequency (str) – How to split the query (and thus files): in years, months, or days. Depends on the maximum query size of the product

• coord_names (list) – Coordinate names in the xarray dataset

• start_date_min (date) – The minimum allowed start date

• end_date_max (date, default = None) – The maximum allowed end date

• start_date (Union[date, str], default = None) – The starting date for the dataset

• end_date (Union[date, str], default = None) – The ending date for the dataset

• leadtime_max (int, default = None) – The maximum lead time in days, for forecast or reforecast data

• limit_months (List[int], default = None) – Limit to specific months, required for the version 4 reforecast

download(clobber: bool = False) → List[Path]

Download the GloFAS data by querying CDS.

The raw GloFAS data is available as a global raster in CDS. This method downloads the raster files for the specified region of interest and date range. The files are in GRIB format and are split up either by day, month, or year depending on the GloFAS product.

Parameters:

clobber (bool, default = False) – Overwrite files that were already downloaded

Return type:

A list paths of downloaded files

load() → Dataset

Load the processed GloFAS data as an xarray.DataSet.

Returns:

• A single xarray dataset containing all GloFAS reporting points

• and their associated river discharge

process(clobber: bool = False) → List[Path]

Process the downloaded GloFAS files.

For each raw GRIB file, read it in and extract the river discharge from the reporting point coordinates specified in the configuration file. Saves the output as a NetCDF file, where files are split by day, month or year depending on the GloFAS product.

Parameters:

clobber (bool, default = False) – Overwrite files that were already processed

Return type:

A list paths of processed files

class ochanticipy.datasources.glofas.glofas.SystemVersions

Bases: dict

Class to type the allowed model versions.

ALLOWED_KEYS = {3, 4}

ochanticipy.datasources.glofas.reanalysis module

Download and process GloFAS reanalysis river discharge data.

class ochanticipy.datasources.glofas.reanalysis.GlofasReanalysis(country_config: CountryConfig, geo_bounding_box: GeoBoundingBox, start_date: date | str = None, end_date: date | str = None, model_version: int = 4)

Bases: Glofas

Class for downloading and processing GloFAS reanalysis data.

The GloFAS reanalysis dataset is a global raster presenting river discharnge from 1979 until present day (updated daily), see this paper for more details.

This class downloads the raw raster data from CDS, and processes it from a raster to a datasets of reporting points from the GloFAS interface. Due to the CDS request size limits, separate files are downloaded per year.

Parameters:

• country_config (CountryConfig) – Country configuration

• geo_bounding_box (GeoBoundingBox) – The bounding coordinates of the area that should be included

• start_date (Union[date, str], default: date(1979, 1, 1)) – The starting date for the dataset. If left blank, defaults to the earliest available date

• end_date (Union[date, str], default: date.today()) – The ending date for the dataset. If left blank, defaults to the current date

• model_version (int, default: 4) – The version of the GloFAS model to use, can only be 3 or 4. If in doubt, always use the latest (default).

Examples

Download, process and load all historical GloFAS reanalysis data until the current date, set to Oct 22, 2022 for this example.

>>> from datetime import date
>>> from ochanticipy import create_country_config, CodAB, GeoBoundingBox,
... GlofasReanalysis
>>>
>>> country_config = create_country_config(iso3="bgd")
>>> codab = CodAB(country_config=country_config)
>>> codab.download()
>>> admin_npl = codab.load()
>>> geo_bounding_box = GeoBoundingBox.from_shape(admin_npl)
>>>
>>> glofas_reanalysis = GlofasReanalysis(
...     country_config=country_config,
...     geo_bounding_box=geo_bounding_box,
...     end_date=date(year=2022, month=10, day=22)
... )
>>> glofas_reanalysis.download()
>>> glofas_reanalysis.process()
>>>
>>> npl_glofas_reanalysis_reporting_points = glofas_reanalysis.load()

Module contents

Methods pertaining to GloFAS data.