geoglows.streamflow

THIS MODULE IS DEPRECATED. Please update your code to use the new GEOGLOWS model and data services. Analogous functions to everything in this module is found in the geoglows.data or geoglows.streams modules.

The streamflow module provides a series of functions for requesting forecasted and historical data from the GEOGLOWS ECMWF Streamflow Service for Model and Data Services Version 1.

Forecasted Streamflow

geoglows.streamflow.forecast_stats(reach_id: int, return_format: str = 'csv', forecast_date: str = None, endpoint: str = 'https://geoglows.ecmwf.int/api/', s: Session = False) → DataFrame[source]

Retrieves statistics that summarize the ensemble streamflow forecast for a certain reach_id

Parameters:

  • reach_id – the ID of a stream

  • return_format – ‘csv’, ‘json’, ‘waterml’, ‘url’

  • forecast_date – a string specifying the date to request in YYYYMMDD format

  • endpoint – the endpoint of an api instance

  • s – requests.Session instance connected to the api’s root url

Return Format:

  • return_format=’csv’ returns a pd.DataFrame()

  • return_format=’json’ returns a json

  • return_format=’waterml’ returns a waterml string

  • return_format=’url’ returns a url string for using in a request or web browser

Example

data = streamflow.rst.forecast_stats(12341234)
geoglows.streamflow.forecast_ensembles(reach_id: int, return_format: str = 'csv', forecast_date: str = None, endpoint: str = 'https://geoglows.ecmwf.int/api/', s: Session = False) → DataFrame[source]

Retrieves each ensemble from the most recent streamflow forecast for a certain reach_id

Parameters:

  • reach_id – the ID of a stream

  • return_format – ‘csv’, ‘json’, ‘waterml’, ‘url’

  • forecast_date – a string specifying the date to request in YYYYMMDD format

  • endpoint – the endpoint of an api instance

  • s – requests.Session instance connected to the api’s root url

Return Format:

  • return_format=’csv’ returns a pd.DataFrame()

  • return_format=’json’ returns a json

  • return_format=’waterml’ returns a waterml string

  • return_format=’url’ returns a url string for using in a request or web browser

Example

data = streamflow.rst.forecast_ensembles(12341234)
geoglows.streamflow.forecast_warnings(region: str = 'all', return_format='csv', endpoint='https://geoglows.ecmwf.int/api/', s: Session = False) → DataFrame[source]

Retrieves a csv listing streams likely to experience a return period level flow during the forecast period.

Parameters:

  • region – the name of a region as shown in the available_regions request

  • return_format – ‘csv’, ‘json’, ‘waterml’, ‘request’, ‘url’

  • endpoint – the endpoint of an api instance

  • s – requests.Session instance connected to the api’s root url

Return Format:

  • return_format=’csv’ returns a pd.DataFrame()

  • return_format=’url’ returns a url string for using in a request or web browser

Example

data = streamflow.rst.forecast_warnings('australia-geoglows')
geoglows.streamflow.forecast_records(reach_id: int, start_date: str = None, end_date: str = None, return_format='csv', endpoint='https://geoglows.ecmwf.int/api/', s: Session = False) → DataFrame[source]

Retrieves a csv showing the ensemble average forecasted flow for the year from January 1 to the current date

Parameters:

  • reach_id – the ID of a stream

  • return_format – ‘csv’, ‘json’, ‘waterml’, ‘url’

  • start_date – a string specifying the earliest date to request in YYYYMMDD format

  • end_date – a string specifying the latest date to request in YYYYMMDD format

  • endpoint – the endpoint of an api instance

  • s – requests.Session instance connected to the api’s root url

Return Format:

  • return_format=’csv’ returns a pd.DataFrame()

  • return_format=’json’ returns a json

  • return_format=’waterml’ returns a waterml string

  • return_format=’url’ returns a url string for using in a request or web browser

Example

data = streamflow.rst.forecast_warnings('australia-geoglows')

Historically Simulated Streamflow

geoglows.streamflow.historic_simulation(reach_id: int, return_format='csv', forcing='era_5', endpoint='https://geoglows.ecmwf.int/api/', s: Session = False) → DataFrame[source]

Retrieves a historical streamflow simulation derived from a specified forcing for a certain reach_id

Parameters:

  • reach_id – the ID of a stream

  • return_format – ‘csv’, ‘json’, ‘waterml’, ‘url’

  • forcing – the runoff dataset used to drive the historic simulation (era_interim or era_5)

  • endpoint – the endpoint of an api instance

  • s – requests.Session instance connected to the api’s root url

Return Format:

  • return_format=’csv’ returns a pd.DataFrame()

  • return_format=’json’ returns a json

  • return_format=’waterml’ returns a waterml string

  • return_format=’url’ returns a url string for using in a request or web browser

Example

data = streamflow.rst.historic_simulation(12341234)
geoglows.streamflow.daily_averages(reach_id: int, return_format='csv', forcing='era_5', endpoint='https://geoglows.ecmwf.int/api/', s: Session = False) → DataFrame[source]

Retrieves the average flow for every day of the year at a certain reach_id.

Parameters:

  • reach_id – the ID of a stream

  • return_format – ‘csv’, ‘json’, ‘waterml’, ‘url’

  • forcing – the runoff dataset used to drive the historic simulation (era_interim or era_5)

  • endpoint – the endpoint of an api instance

  • s – requests.Session instance connected to the api’s root url

Return Format:

  • return_format=’csv’ returns a pd.DataFrame()

  • return_format=’json’ returns a json

  • return_format=’waterml’ returns a waterml string

  • return_format=’url’ returns a url string for using in a request or web browser

Example

data = streamflow.rst.seasonal_average(12341234)
geoglows.streamflow.monthly_averages(reach_id: int, return_format='csv', forcing='era_5', endpoint='https://geoglows.ecmwf.int/api/', s: Session = False) → DataFrame[source]

Retrieves the average flow for each month at a certain reach_id.

Parameters:

  • reach_id – the ID of a stream

  • forcing – the runoff dataset used to drive the historic simulation (era_interim or era_5)

  • return_format – ‘csv’, ‘json’, ‘waterml’, ‘url’

  • endpoint – the endpoint of an api instance

  • s – requests.Session instance connected to the api’s root url

Return Format:

  • return_format=’csv’ returns a pd.DataFrame()

  • return_format=’json’ returns a json

  • return_format=’waterml’ returns a waterml string

  • return_format=’url’ returns a url string for using in a request or web browser

Example

data = streamflow.rst.seasonal_average(12341234)
geoglows.streamflow.return_periods(reach_id: int, return_format='csv', forcing='era_5', endpoint='https://geoglows.ecmwf.int/api/', s: Session = False) → DataFrame[source]

Retrieves the return period thresholds based on a specified historic simulation forcing on a certain reach_id.

Parameters:

  • reach_id – the ID of a stream

  • forcing – the runoff dataset used to drive the historic simulation (era_interim or era_5)

  • return_format – ‘csv’, ‘json’, ‘waterml’, ‘url’

  • endpoint – the endpoint of an api instance

  • s – requests.Session instance connected to the api’s root url

Return Format:

  • return_format=’csv’ returns a pd.DataFrame()

  • return_format=’json’ returns a json

  • return_format=’waterml’ returns a waterml string

  • return_format=’url’ returns a url string for using in a request or web browser

Example

data = streamflow.rst.return_periods(12341234)

GEOGLOWS Model Utilities

geoglows.streamflow.available_dates(reach_id: int = None, region: str = None, return_format: str = 'json', endpoint: str = 'https://geoglows.ecmwf.int/api/', s: Session = False) → dict[source]

Retrieves the list of dates of stored streamflow forecasts. You need to specify either a reach_id or a region.

Parameters:

  • reach_id – the ID of a stream

  • region – the name of a hydrologic region used in the model

  • endpoint – the endpoint of an api instance

  • return_format – ‘json’ or ‘url’

  • s – requests.Session instance connected to the api’s root url

Return Format:

  • return_format=’json’ (default) returns {‘available_dates’: [‘list_of_dates’]}

  • return_format=’url’ returns a url string for using in a request or web browser

Example

data = streamflow.rst.available_dates(12341234)