Package References

Base class

class tethysts.Tethys(remotes: List[Remote] | None = None, cache: Path | None = None)

The base Tethys object.

Parameters:

remotes (list of dict or None) –

list of dict of the S3 remotes to access or None which will parse all public datasets. The dicts must contain: bucket and connection_config.

bucketstr

A string of the bucket name.

connection_configdict or str

A dict of strings of service_name, s3, endpoint_url, aws_access_key_id, and aws_secret_access_key. Or it could be a string of the public_url endpoint.

Return type:

tethys object

Get versions

Tethys.get_versions(dataset_id: str)

Function to get the versions of a particular dataset.

Parameters:

dataset_id (str) – The dataset_id of the dataset.

Return type:

list

Get stations

Tethys.get_stations(dataset_id: str, geometry: dict | None = None, lat: float | None = None, lon: float | None = None, distance: float | None = None, version_date: str | datetime | Timestamp | None = None, from_date: str | datetime | Timestamp | None = None, to_date: str | datetime | Timestamp | None = None)

Method to return the stations associated with a dataset.

Parameters:

  • dataset_id (str) – The dataset_id of the dataset.

  • geometry (dict or None) – A geometry in GeoJSON format. Can be either a point or a polygon. If it’s a point, then the method will perform a nearest neighbor query and return one station. If it’s a polygon, then the method performs an intersection of all stations within the polygon.

  • lat (float or None) – Instead of using the geometry parameter, optionally use lat and lon for the spatial queries. Both lat and lon must be passed for the spatial queries and will override the geometry parameter. If only lat and lon are passed, then the method performs a nearest neighbor query. If distance is passed in addition to lat and lon, then distance is used as a radius buffer and an intersection is performed.

  • lon (float or None) – See lat description.

  • distance (float or None) – See lat description. This should be in decimal degrees not meters.

  • version_date (str in iso 8601 datetime format or None) – The specific version of the stations data. None will return the latest version.

  • from_date (str, Timestamp, datetime, or None) – The start date of the selection.

  • to_date (str, Timestamp, datetime, or None) – The end date of the selection.

Returns:

of station data

Return type:

list of dict

Get results

Tethys.get_results(dataset_id: str, station_ids: str | List[str] | None = None, geometry: dict | None = None, lat: float | None = None, lon: float | None = None, from_date: str | datetime | Timestamp | None = None, to_date: str | datetime | Timestamp | None = None, from_mod_date: str | datetime | Timestamp | None = None, to_mod_date: str | datetime | Timestamp | None = None, version_date: str | datetime | Timestamp | None = None, heights: List[int | float] | int | float | None = None, bands: List[int] | int | None = None, squeeze_dims: bool = False, output_path: str | Path | None = None, compression: str = 'lzf', threads: int = 30)

Function to query the results data given a specific dataset_id and station_ids. Multiple optional outputs.

Parameters:

  • dataset_id (str) – The dataset_id of the dataset.

  • station_ids (str, list of str, or None) – The station_ids of the associated station.

  • geometry (dict or None) – A point geometry in GeoJSON format. If it’s a point, then the method will perform a nearest neighbor query and return one station.

  • lat (float or None) – Instead of using the geometry parameter, optionally use lat and lon for the nearest neighbor spatial query. Both lat and lon must be passed for the spatial query and will override the geometry parameter.

  • lon (float or None) – See lat description.

  • from_date (str, Timestamp, datetime, or None) – The start date of the selection.

  • to_date (str, Timestamp, datetime, or None) – The end date of the selection.

  • from_mod_date (str, Timestamp, datetime, or None) – Only return data post the defined modified date.

  • to_mod_date (str, Timestamp, datetime, or None) – Only return data prior to the defined modified date.

  • version_date (str or Timestamp) – The version date of the results to be returned. Defaults to None which will return the last version.

  • heights (list of int/float, int/float, or None) – The heights to return. If None, then all heights are returned.

  • bands (list of int, int, or None) – The bands to return. If None, then all bands are returned.

  • squeeze_dims (bool) – Should all dimensions with a length of one be removed from the parameter’s dimensions?

  • output_path (str, pathlib.Path, or None) – The optional path to save the results to an hdf5 file. A value of None will not save a file.

  • compression (str or None) – This only applies when output_path is a path string. This is the type of compression used for the output hdf5 file. The options are gzip, lzf, zstd, or None. gzip is compatible with any hdf5 installation (not only h5py), so this should be used if interoperability across platforms is important. lzf is compatible with any h5py installation, so if only python users will need to access these files then this is a better option than gzip. zstd requires the hdf5plugin python package, but is the best compression option if only users of the tethysts package will be using it. None has no compression and is generally not recommended except in niche situations.

  • threads (int) – The number of threads to simultaneously download results chunks. Realistically, this should not exceede 60.

Return type:

xr.Dataset

API Pages