From 88486ac25884c31b8c53ad71da4796ff8b8a2b1e Mon Sep 17 00:00:00 2001 From: Mike Kittridge Date: Tue, 13 Sep 2022 22:55:11 -0600 Subject: [PATCH] updated docs --- sphinx/source/usage_a.rst | 35 +++++++++++++++++++++++++++++++---- 1 file changed, 31 insertions(+), 4 deletions(-) diff --git a/sphinx/source/usage_a.rst b/sphinx/source/usage_a.rst index bda2dfe..50da5a8 100644 --- a/sphinx/source/usage_a.rst +++ b/sphinx/source/usage_a.rst @@ -172,14 +172,41 @@ In Tethys version 4, the results have been saved into multiple chunks. These chu Dataset versions ---------------- -If a version_date is not passed to the get_results method, then the latest dataset version will be returned. If you'd like to list all the dataset versions and to choose which version you'd like to pass to the get_results method, then you can use the get_versions method. +If a version_date is not passed to the get_results or get_stations method, then the latest dataset version will be returned. If you'd like to list all the dataset versions and to choose which version you'd like to pass to the get_results or get_stations method, then you can use the get_versions method. .. ipython:: python versions = ts.get_versions(dataset_id) versions +Handling geometries +--------------------- +Depending data request, Tethys will either return geometries as GeoJSON or Well-Known Binary (WKB) hexadecimal geometries. If you're not familiar with how to handle these formats, I recommend using `Shapely `_ to convert into and out of geometry formats and to provide a range of geospatial processing tools. Shapely is used as the geoprocessing tool behind `geopandas `_. -Tethys web API --------------- -The `Tethys web API `_ uses all of the same function names and associated input parameters as the Python package. But in most cases, users should use the Python package instead of the web API as it will be faster, more flexible, and won't put load on the VM running the web API. +For example if you've made a get_stations request and returned GeoJSON geometries, then you could convert them to shapely objects and put them into a dictionary with station_ids as keys: + +.. ipython:: python + from shapely.geometry import shape + + dataset_id = 'b5d84aa773de2a747079c127' + + stations = ts.get_stations(dataset_id) + stns_geo = {s['station_id']: shape(s['geometry']) for s in stations} + stns_geo['f9c61373e7ca386c1fab06db'] + + +Or you could convert the WKB hex of results into a list of shapely objects: + +.. ipython:: python + from shapely import wkb + + station_ids = [station_id, '96e9ff9437fc738b24d10b42'] + + results = ts.get_results(dataset_id, station_ids) + geo_list = [wkb.loads(g, hex=True) for g in results.geometry.values] + geo_list + + +.. Tethys web API +.. -------------- +.. The `Tethys web API `_ uses all of the same function names and associated input parameters as the Python package. But in most cases, users should use the Python package instead of the web API as it will be faster, more flexible, and won't put load on the VM running the web API.