From 7fb97bc02ffb8d11f81b12eab6ea2e40fb4abdc3 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 21 Sep 2021 22:39:10 -0400 Subject: [PATCH 1/9] add geopandas and hvplot to docs --- requirements-docs.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/requirements-docs.txt b/requirements-docs.txt index 532b0ba1..160e0f0e 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -4,3 +4,5 @@ Sphinx~=4.1 sphinxcontrib-fulltoc~=1.2 nbsphinx~=0.8 jinja2<4.0 +geopandas +hvplot From 556b45d0f879affa114986ef0c99361e008caa8a Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 21 Sep 2021 22:42:41 -0400 Subject: [PATCH 2/9] docs: more requirements for rendering notebooks --- docs/tutorials/stac-metadata-viz.ipynb | 41 ++++++++++++++++++++++++++ requirements-docs.txt | 2 ++ 2 files changed, 43 insertions(+) diff --git a/docs/tutorials/stac-metadata-viz.ipynb b/docs/tutorials/stac-metadata-viz.ipynb index f9144113..6ca88f1e 100644 --- a/docs/tutorials/stac-metadata-viz.ipynb +++ b/docs/tutorials/stac-metadata-viz.ipynb @@ -233,6 +233,47 @@ "source": [ "plot_polygons(aoi_gdf) * items_gdf.hvplot.paths(geo=True)" ] + }, + { + "cell_type": "markdown", + "id": "2c8e2be8", + "metadata": {}, + "source": [ + "## Line Plots\n", + "\n", + "Numeric STAC metadata can also be plotted, most often this will be plotted vs the Item `datetime`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d47369b7", + "metadata": {}, + "outputs": [], + "source": [ + "items_df = pd.DataFrame(items)\n", + "\n", + "plot_fields = [\n", + " 'properties.eo:cloud_cover',\n", + " 'properties.view:sun_azimuth',\n", + " 'properties.view:sun_elevation',\n", + " 'properties.sentinel:data_coverage',\n", + " #'properties.landsat:cloud_cover_land'\n", + "]\n", + "\n", + "plots = None\n", + "for f in plot_fields:\n", + " if f in items_df:\n", + " if plots is None:\n", + " plots = items_df.hvplot(y=f, label=f.replace('properties.', ''),\n", + " frame_height=500, frame_width=800)\n", + " else:\n", + " plots = plots * items_df.hvplot(y=f, label=f.replace('properties.', ''))\n", + "\n", + "plots.opts(ylabel='')\n", + "#if plots is not None:\n", + "# plots.opts(ylabel='')" + ] } ], "metadata": { diff --git a/requirements-docs.txt b/requirements-docs.txt index 160e0f0e..a0721fd5 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -6,3 +6,5 @@ nbsphinx~=0.8 jinja2<4.0 geopandas hvplot +cartopy +geoviews From 543117d27053b41dd4a780a5f0c9729f10fae2b0 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 21 Sep 2021 22:56:17 -0400 Subject: [PATCH 3/9] docs: add conda env for building docs --- .readthedocs.yml | 7 +++---- docs/environment.yml | 17 +++++++++++++++++ requirements-docs.txt | 4 ---- 3 files changed, 20 insertions(+), 8 deletions(-) create mode 100644 docs/environment.yml diff --git a/.readthedocs.yml b/.readthedocs.yml index 0a9fe2d4..cf4d02c1 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -18,7 +18,6 @@ formats: # Optionally set the version of Python and requirements required to build your docs python: version: 3.8 - install: - - method: pip - path: . - - requirements: requirements-docs.txt \ No newline at end of file + +conda: + environment: docs/environment.yml \ No newline at end of file diff --git a/docs/environment.yml b/docs/environment.yml new file mode 100644 index 00000000..251ad8e8 --- /dev/null +++ b/docs/environment.yml @@ -0,0 +1,17 @@ +name: pystac-client-docs +channels: + - conda-forge + - defaults +dependencies: + - cartopy + - geoviews + - hvplot + - geopandas + - pip: + - sphinx_rtd_theme==0.5.1 + - ipykernel~=6.2 + - ipython~=7.27 + - Sphinx~=4.1 + - sphinxcontrib-fulltoc~=1.2 + - nbsphinx~=0.8 + - jinja2<4.0 \ No newline at end of file diff --git a/requirements-docs.txt b/requirements-docs.txt index a0721fd5..532b0ba1 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -4,7 +4,3 @@ Sphinx~=4.1 sphinxcontrib-fulltoc~=1.2 nbsphinx~=0.8 jinja2<4.0 -geopandas -hvplot -cartopy -geoviews From ccb3c378d7a91443234f7c327648276ceb4e80b7 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 21 Sep 2021 22:56:42 -0400 Subject: [PATCH 4/9] docs: cleanup stac-metadata-viz notebook --- docs/tutorials/stac-metadata-viz.ipynb | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/docs/tutorials/stac-metadata-viz.ipynb b/docs/tutorials/stac-metadata-viz.ipynb index 6ca88f1e..f1d9b889 100644 --- a/docs/tutorials/stac-metadata-viz.ipynb +++ b/docs/tutorials/stac-metadata-viz.ipynb @@ -236,7 +236,7 @@ }, { "cell_type": "markdown", - "id": "2c8e2be8", + "id": "b0604c84", "metadata": {}, "source": [ "## Line Plots\n", @@ -247,18 +247,16 @@ { "cell_type": "code", "execution_count": null, - "id": "d47369b7", + "id": "c198e261", "metadata": {}, "outputs": [], "source": [ - "items_df = pd.DataFrame(items)\n", + "items_df = pd.DataFrame(items_gdf)\n", "\n", "plot_fields = [\n", " 'properties.eo:cloud_cover',\n", " 'properties.view:sun_azimuth',\n", - " 'properties.view:sun_elevation',\n", - " 'properties.sentinel:data_coverage',\n", - " #'properties.landsat:cloud_cover_land'\n", + " 'properties.view:sun_elevation'\n", "]\n", "\n", "plots = None\n", @@ -270,9 +268,7 @@ " else:\n", " plots = plots * items_df.hvplot(y=f, label=f.replace('properties.', ''))\n", "\n", - "plots.opts(ylabel='')\n", - "#if plots is not None:\n", - "# plots.opts(ylabel='')" + "plots.opts(ylabel='')" ] } ], From f3746df3a6d928faac8efb1af2911207202c76fd Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 21 Sep 2021 23:18:32 -0400 Subject: [PATCH 5/9] docs: readthedocs and conda config --- .readthedocs.yml | 4 ---- docs/environment.yml | 4 +++- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index cf4d02c1..841124e8 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -15,9 +15,5 @@ formats: - pdf - htmlzip -# Optionally set the version of Python and requirements required to build your docs -python: - version: 3.8 - conda: environment: docs/environment.yml \ No newline at end of file diff --git a/docs/environment.yml b/docs/environment.yml index 251ad8e8..93307c1d 100644 --- a/docs/environment.yml +++ b/docs/environment.yml @@ -3,6 +3,7 @@ channels: - conda-forge - defaults dependencies: + - python=3.8 - cartopy - geoviews - hvplot @@ -14,4 +15,5 @@ dependencies: - Sphinx~=4.1 - sphinxcontrib-fulltoc~=1.2 - nbsphinx~=0.8 - - jinja2<4.0 \ No newline at end of file + - jinja2<4.0 + - -e ../ From d94a06bba5518676b962471c18125283b53fe109 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 21 Sep 2021 23:19:40 -0400 Subject: [PATCH 6/9] docs: update conda config --- docs/environment.yml | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/environment.yml b/docs/environment.yml index 93307c1d..fd356407 100644 --- a/docs/environment.yml +++ b/docs/environment.yml @@ -9,11 +9,5 @@ dependencies: - hvplot - geopandas - pip: - - sphinx_rtd_theme==0.5.1 - - ipykernel~=6.2 - - ipython~=7.27 - - Sphinx~=4.1 - - sphinxcontrib-fulltoc~=1.2 - - nbsphinx~=0.8 - - jinja2<4.0 + - -r ../requirements-docs.txt - -e ../ From dd0e1806c6f03b74559b695211a7a457b00130ab Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Wed, 22 Sep 2021 00:03:12 -0400 Subject: [PATCH 7/9] allow errors in notebook rendering --- docs/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 712f032f..5e803552 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -61,6 +61,8 @@ ) } +nbsphinx_allow_errors = True + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] From 0066ee4f72b54cc2ebff1cf959f2d4365fb18489 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Wed, 22 Sep 2021 00:36:49 -0400 Subject: [PATCH 8/9] docs: disable some notebook renders due to complex dependencies --- docs/environment.yml | 4 ---- docs/tutorials.rst | 2 -- 2 files changed, 6 deletions(-) diff --git a/docs/environment.yml b/docs/environment.yml index fd356407..20d8d096 100644 --- a/docs/environment.yml +++ b/docs/environment.yml @@ -4,10 +4,6 @@ channels: - defaults dependencies: - python=3.8 - - cartopy - - geoviews - - hvplot - - geopandas - pip: - -r ../requirements-docs.txt - -e ../ diff --git a/docs/tutorials.rst b/docs/tutorials.rst index 82e40d34..f84a7e0a 100644 --- a/docs/tutorials.rst +++ b/docs/tutorials.rst @@ -15,7 +15,6 @@ STAC Metadata Visualization --------------------------- - :tutorial:`GitHub version ` -- :ref:`Docs version ` This tutorial gives an introduction to using Holeviews and hvplot to visualize STAC metadata and Item geometries on a map. @@ -24,7 +23,6 @@ CQL Filtering --------------------------- - :tutorial:`GitHub version ` -- :ref:`Docs version ` This tutorial gives an introduction to using CQL-JSON filtering in searches to search by arbitrary STAC Item properties. \ No newline at end of file From 2a7da0f7e60ac650641fa7496542c87fc2150d74 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Wed, 22 Sep 2021 02:14:47 -0400 Subject: [PATCH 9/9] docs: minor updates --- docs/quickstart.rst | 2 ++ docs/usage.rst | 35 +++++++++++++++++++++++------------ 2 files changed, 25 insertions(+), 12 deletions(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 9b5232ba..7b575d0b 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -61,6 +61,8 @@ to the server as strings, except for ``gsd`` which it casts to properties these will be sent as strings. Some servers may automatically cast this to the appropriate data type, others may not. +The query filter will also accept complete JSON as per the specification. + :: diff --git a/docs/usage.rst b/docs/usage.rst index 3a9a767b..220fed74 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -172,18 +172,29 @@ section. See the :mod:`Paging ` docs for details on how to Query Filter ------------ -If the server supports the [query filter](https://github.com/radiantearth/stac-api-spec/tree/master/fragments/query) -arbitrary Item properties can be included in the search parameters. The query parameter to :class:`ItemSearch` accepts -a JSON structure as in the STAC API spec, but also accepts an abbreviated syntax. Instead of JSON, a list of strings can -be provided, in which case pystac-client will convert them to the equivalent JSON structure. +If the Catalog supports the `Query +extension `__, +any Item property can also be included in the search. Rather than +requiring the JSON syntax the Query extension uses, pystac-client can use a +simpler syntax that it will translate to the JSON equivalent. Note +however that when the simple syntax is used it sends all property values +to the server as strings, except for ``gsd`` which it casts to +``float``. This means that if there are extensions in use with numeric +properties these will be sent as strings. Some servers may automatically +cast this to the appropriate data type, others may not. -The syntax is simply: +The query filter will also accept complete JSON as per the specification. -``` - -e.g., +:: -eo:cloud_cover<10 -view:off_nadir<50 -platform=landsat-8 -``` + + + where operator is one of `>=`, `<=`, `>`, `<`, `=` + + Examples: + eo:cloud_cover<10 + view:off_nadir<50 + platform=landsat-8 + +Any number of properties can be included, and each can be included more +than once to use additional operators.