IOC

The Sea level station monitoring facility website is focused on operational monitoring of sea level measuring stations across the globe on behalf of the Intergovernmental Oceanographic Commission (IOC) aggregating data from more than 170 providers.

A list of IOC stations is provided with the get_ioc_stations() function with various subsetting options.

searvey.ioc.get_ioc_stations(region: Polygon | MultiPolygon | None = None, lon_min: float | None = None, lon_max: float | None = None, lat_min: float | None = None, lat_max: float | None = None) → GeoDataFrame

Return IOC station metadata from: http://www.ioc-sealevelmonitoring.org/list.php?showall=all

If region is defined then the stations that are outside of the region are filtered out.. If the coordinates of the Bounding Box are defined then stations outside of the BBox are filtered out. If both region and the Bounding Box are defined, then an exception is raised.

Note: The longitudes of the IOC stations are in the [-180, 180] range.

Parameters:

  • region – Polygon or MultiPolygon denoting region of interest

  • lon_min – The minimum Longitude of the Bounding Box.

  • lon_max – The maximum Longitude of the Bounding Box.

  • lat_min – The minimum Latitude of the Bounding Box.

  • lat_max – The maximum Latitude of the Bounding Box.

Returns:

pandas.DataFrame with the station metadata

The station data can be retrieved with

searvey.ioc.get_ioc_data(ioc_metadata: ~pandas.core.frame.DataFrame, endtime: str | ~datetime.date | ~datetime.datetime | ~pandas._libs.tslibs.timestamps.Timestamp = 'now', period: float = 1, truncate_seconds: bool = True, rate_limit: ~searvey.rate_limit.RateLimit = <searvey.rate_limit.RateLimit object>, disable_progress_bar: bool = False) → Dataset

Return the data of the stations specified in ioc_metadata as an xr.Dataset.

truncate_seconds needs some explaining. IOC has more than 1000 stations. When you retrieve data from all (or at least most of) these stations, you end up with thousands of timestamps that only contain a single datapoint. This means that the returned xr.Dataset will contain a huge number of NaN which means that you will need a huge amount of RAM.

In order to reduce the amount of the required RAM we reduce the number of timestamps by truncating the seconds. This is how this works:

2014-01-03 14:53:02 -> 2014-01-03 14:53:00 2014-01-03 14:53:32 -> 2014-01-03 14:53:00 2014-01-03 14:53:48 -> 2014-01-03 14:53:00 2014-01-03 14:54:09 -> 2014-01-03 14:54:00 2014-01-03 14:54:48 -> 2014-01-03 14:54:00

Nevertheless this approach has a downside. If a station returns multiple datapoints within the same minute, then we end up with duplicate timestamps. When this happens we only keep the first datapoint and drop the subsequent ones. So potentially you may not retrieve all of the available data.

If you don’t want this behavior, set truncate_seconds to False and you will retrieve the full data.

Parameters:

  • ioc_metadata – A pd.DataFrame returned by get_ioc_stations

  • endtime – The date of the “end” of the data. Defaults to datetime.date.today()

  • period – The number of days to be requested. IOC does not support values greater than 30

  • truncate_seconds – If True then timestamps are truncated to minutes (seconds are dropped)

  • rate_limit – The default rate limit is 5 requests/second.

  • disable_progress_bar – If True then the progress bar is not displayed.