sliderule

The SlideRule Python API sliderule.py is used to access the services provided by the base SlideRule server. From Python, the module can be imported via:

import sliderule

Functions¶

init¶

sliderule.init(url='slideruleearth.io', verbose=False, loglevel=20, organization='sliderule', desired_nodes=None, time_to_live=60, plugins=None, log_handler=None, github_token=None, rethrow=False, user_service=False)

Initializes the Python client for use with SlideRule, and should be called before other ICESat-2 API calls. This function is a wrapper for a handful of sliderule functions that would otherwise all have to be called in order to initialize the client.

Parameters

• url (str) the IP address or hostname of the SlideRule service (slideruleearth.io by default)

• verbose (bool) sets up console logger as a convenience to user so all logs are printed to screen

• loglevel (int) minimum severity of log message to output

• organization (str) Cluster name that the client should connect to

• desired_nodes (int) requested number of processing nodes in the cluster

• time_to_live (int) minimum number of minutes the desired number of nodes should be present in the cluster

• plugins (list) names of the plugins that need to be available on the server

• log_handler (logger) user provided logging handler

• github_token (str) personal access token for GitHub authentication

• rethrow (bool) client rethrows exceptions to be handled by calling code

• user_service (bool) requests use user associated asg connected to cluster

Returns

bool

Status of version check

Examples

>>> import sliderule
>>> sliderule.init()

source¶

sliderule.source(api, parm=None, stream=False, callbacks=None, path='/source', session=None, rethrow=False, sign=False)

Perform API call to SlideRule service

Parameters

• api (str) name of the SlideRule endpoint

• parm (dict) dictionary of request parameters

• stream (bool) whether the request is a normal service or a stream service (see De-serialization </user_guide/SlideRule.html#de-serialization>_ for more details)

• callbacks (dict) record type callbacks (advanced use)

• path (str) path to api being requested

• rethrow (bool) client rethrows exceptions to be handled by calling code

• sign (bool) sign the request using a public/private key pair

Returns

dictionary

response data

Examples

>>> import sliderule
>>> sliderule.set_url("slideruleearth.io")
>>> rqst = {
...     "time": "NOW",
...     "input": "NOW",
...     "output": "GPS"
... }
>>> rsps = sliderule.source("datetime", rqst)
>>> print(rsps)
{'time': 1300556199523.0, 'format': 'GPS'}

set_url¶

sliderule.set_url(domain, session=None)

Configure sliderule package with URL of service

Parameters

• urls (str) IP address or hostname of SlideRule service (note, there is a special case where the url is provided as a list of strings instead of just a string; when a list is provided, the client hardcodes the set of servers that are used to process requests to the exact set provided; this is used for testing and for local installations and can be ignored by most users)

Examples

>>> import sliderule
>>> sliderule.set_url("service.my-sliderule-server.org")

set_verbose¶

sliderule.set_verbose(enable, loglevel=20, session=None)

Sets up a console logger to print log messages to screen

Parameters

• enable (bool) True: creates console logger if it doesn’t exist, False: destroys console logger if it does exist

• loglevel (int) minimum severity of log message to output

Examples

>>> import sliderule
>>> sliderule.set_verbose(True, loglevel=logging.INFO)

set_rqst_timeout¶

sliderule.set_rqst_timeout(timeout, session=None)

Sets the TCP/IP connection and reading timeouts for future requests made to sliderule servers. Setting it lower means the client will failover more quickly, but may generate false positives if a processing request stalls or takes a long time returning data. Setting it higher means the client will wait longer before designating it a failed request which in the presence of a persistent failure means it will take longer for the client to remove the node from its available servers list.

Parameters

• timeout (tuple) (, )

Examples

>>> import sliderule
>>> sliderule.set_rqst_timeout((10, 60))

update_available_servers¶

sliderule.update_available_servers(desired_nodes=None, time_to_live=None, session=None)

Manages the number of servers in the cluster. If the desired_nodes parameter is set, then a request is made to change the number of servers in the cluster to the number specified. In all cases, the number of nodes currently running in the cluster are returned - even if desired_nodes is set; subsequent calls to this function is needed to check when the current number of nodes matches the desired_nodes.

Parameters

• desired_nodes (int) the desired number of nodes in the cluster

• time_to_live (int) number of minutes for the desired nodes to run

Returns

int

number of nodes currently in the cluster

int number of nodes available for work in the cluster

Examples

>>> import sliderule
>>> num_servers, max_workers = sliderule.update_available_servers(10)

scaleout¶

sliderule.scaleout(desired_nodes, time_to_live, session=None)

Scale the cluster and wait for cluster to reach desired state

Parameters

• desired_nodes (int) the desired number of nodes in the cluster

• time_to_live (int) number of minutes for the desired nodes to run

Examples

>>> import sliderule
>>> sliderule.scaleout(4, 300)

gps2utc¶

sliderule.gps2utc(gps_time, as_str=True, session=None)

Convert a GPS based time returned from SlideRule into a UTC time.

Parameters

• gps_time (float) number of seconds since GPS epoch (January 6, 1980)

• as_str (bool) if True, returns the time as a string; if False, returns the time as datatime object

Returns

datetime

UTC time (i.e. GMT, or Zulu time)

Examples

>>> import sliderule
>>> sliderule.gps2utc(1235331234)
'2019-02-27 19:34:03'

get_version¶

sliderule.get_version(session=None)

Get the version information for the running servers and Python client

Returns

dict

dictionary of version information

check_version¶

sliderule.check_version(plugins=None, session=None)

Check that the version of the client matches the version of the server and any additionally requested plugins

Parameters

• plugins (list) list of package names (as strings) to check the version on

Returns

bool

True (always; kept for backward compatibility)

toregion¶

sliderule.toregion(source, tolerance=0.0, cellsize=0.01, n_clusters=1, tif_parms=None)

Convert a GeoJSON/Shapefile/GeoDataFrame/list representation of a set of geospatial regions into a list of lat,lon coordinates and raster image recognized by SlideRule

Parameters

• source (str) file name of GeoJSON formatted regions of interest, file must have name with the .geojson suffix file name of ESRI Shapefile formatted regions of interest, file must have name with the .shp suffix GeoDataFrame of region of interest list of longitude,latitude pairs forming a polygon (e.g. [lat1, lon1, lat2, lon2, lat3, lon3, lat1, lon1]) list of longitude,latitude pairs forming a bounding box (e.g. [lat1, lon1, lat2, lon2])

• tolerance (float) tolerance used to simplify complex shapes so that the number of points is less than the limit (a tolerance of 0.001 typically works for most complex shapes)

• cellsize (float) size of pixel in degrees used to create the raster image of the polygon

• n_clusters (int) number of clusters of polygons to create when breaking up the request to CMR

• tif_parms (dict) dictionary of parameters used to read tif file “off” is the value used for off “res” is the pixel size “flipup”: reverse the vertical orientation “fliplr”: reverse the horizontal orientation “bbox” is [lonmin, latmin, lonmax, latmax]

Returns

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 = {

"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

>>> 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}    ]

run¶

sliderule.run(api, parms, aoi=None, resources=None, session=None)

Execute the requested endpoint and return the results as a GeoDataFrame

Parameters

• api (str) endpoint to run

• parms (dict) parameter dictionary

• aoi (dict) area of interest, passed to sliderule.toregion() function and polygon supplied in request

• resources (list) list of resource names as strings

Returns

GeoDataFrame

result of executing the request endpoint