updated documentation to make supported SlideRule region format clearer

SlideRuleEarth · Oct 16, 2023 · 93035cc · 93035cc
1 parent 839c29f
commit 93035cc
Show file tree

Hide file tree

Showing 2 changed files with 52 additions and 22 deletions.
diff --git a/clients/python/sliderule/sliderule.py b/clients/python/sliderule/sliderule.py
@@ -1221,29 +1221,59 @@ def toregion(source, tolerance=0.0, cellsize=0.01, n_clusters=1):
     dict
         a list of longitudes and latitudes containing the region of interest that can be used for the **poly** and **raster** parameters in a processing request to SlideRule.
 
-        region = {"poly": [{"lat": <lat1>, "lon": <lon1> }, ...], "clusters": [[{"lat": <lat1>, "lon": <lon1>}, ...], [{"lat": <lat1>, "lon": <lon1>}, ...]], "raster": {"data": <geojson file as string>, "length": <length of geojson file>, "cellsize": <parameter cellsize>}}
+        region = {
+
+            "gdf": <GeoDataFrame of region>
+            
+            "poly": [{"lat": <lat1>, "lon": <lon1> }, ...], 
+            
+            "raster": {"data": <geojson file as string>, 
+
+            "clusters": [[{"lat": <lat1>, "lon": <lon1>}, ...], [{"lat": <lat1>, "lon": <lon1>}, ...]] }
 
     Examples
     --------
-        >>> from sliderule import icesat2
-        >>> # Region of Interest #
-        >>> region_filename = sys.argv[1]
-        >>> region = sliderule.toregion(region_filename)
-        >>> # Configure SlideRule #
-        >>> icesat2.init("slideruleearth.io", False)
-        >>> # Build ATL06 Request #
-        >>> parms = {
-        ...     "poly": region["poly"],
-        ...     "srt": icesat2.SRT_LAND,
-        ...     "cnf": icesat2.CNF_SURFACE_HIGH,
-        ...     "ats": 10.0,
-        ...     "cnt": 10,
-        ...     "len": 40.0,
-        ...     "res": 20.0,
-        ...     "maxi": 1
-        ... }
-        >>> # Get ATL06 Elevations
-        >>> atl06 = icesat2.atl06p(parms)
+    >>> import sliderule, json
+    >>> region = sliderule.toregion("tests/data/grandmesa.geojson")
+    >>> print(json.dumps(region["poly"], indent=4))
+    [
+        {
+            "lon": -108.20772968780051,
+            "lat": 38.8232055291981
+        },
+        {
+            "lon": -108.07460164311031,
+            "lat": 38.8475137825863
+        },
+        {
+            "lon": -107.72839858755752,
+            "lat": 39.01510930230633
+        },
+        {
+            "lon": -107.78724142490994,
+            "lat": 39.195630349659986
+        },
+        {
+            "lon": -108.17287000970857,
+            "lat": 39.15920066396116
+        },
+        {
+            "lon": -108.31168256553767,
+            "lat": 39.13757646212944
+        },
+        {
+            "lon": -108.34115668325224,
+            "lat": 39.03758987613325
+        },
+        {
+            "lon": -108.2878686387796,
+            "lat": 38.89051431295789
+        },
+        {
+            "lon": -108.20772968780051,
+            "lat": 38.8232055291981
+        }
+    ]    
     '''
 
     tstart = time.perf_counter()

diff --git a/docs/rtd/source/user_guide/SlideRule.rst b/docs/rtd/source/user_guide/SlideRule.rst
@@ -22,7 +22,7 @@ Using SlideRule means issuing HTTP requests to SlideRule's endpoints to perform
 
 The SlideRule Python Client helps make the above steps a lot easier by providing a user-friendly interface for accomplishing typical workflows.
 
-#. The Python client supports an *area of interest* being defined in multiple ways - as a dictionary of latitude and longitudes, a list of coordinates, a GeoJSON file, a Shapefile, or a GeoDataFrame - and then representing the area of interest in standard formats accepted by SlideRule and other NASA web services.
+#. The Python client supports an *area of interest* being defined in multiple ways - as a dictionary of latitude and longitudes, a list of coordinates, a GeoJSON file, a Shapefile, or a GeoDataFrame - and then converting that representation into the different forms required by SlideRule and other NASA web services.
 #. The Python client queries NASA's Common Metadata Repository (CMR) system automatically for the user and populates the requests to SlideRule with the available science data pertinent to the user's request.
 #. The Python client allows users to define their processing parameters as Python dictionaries, and make requests to SlideRule using Python functions.
 #. The Python client handles the HTTPS connection to the SlideRule servers as well as any necessary authentication requests to the SlideRule Provisioning System when private clusters are being used.
@@ -138,7 +138,7 @@ For example:
                {"lon": -108.3605610678553, "lat": 39.25086131372244},
                {"lon": -108.3435200747503, "lat": 38.89102961045247} ]
 
-In order to facilitate other formats, the ``sliderule.toregion`` function can be used to convert polygons from the GeoJSON and Shapefile formats to the format accepted by `SlideRule`.
+In order to facilitate other formats, the ``sliderule.toregion`` function can be used to convert polygons from the GeoJSON and Shapefile formats into this format accepted by `SlideRule`.
 
 There is no limit to the number of points in the polygon, but note that as the number of points grow, the amount of time it takes to perform the subsetting process also grows. For that reason, it is recommended that if your polygon has more than a few hundred points, it is best to enable the rasterization option described in the GeoJSON section below.