Getting Started

This documentation is intended to explain how to use SlideRule, an on-demand science data processing service, and its accompanying Python client. SlideRule is hosted at icesat2sliderule.org and responds to REST API calls to process and return science results. The software was originally developed to support science applications for NASA’s Ice Cloud and land Elevation Satellite-2 (ICESat-2), but has the goal of demonstrating a new paradigm for providing science data products to researchers. Future enhancements to SlideRule include adding datasets from new missions and including algorithms for different types of science applications.

While SlideRule can be accessed by any http client (e.g. curl) by making GET and POST requests to the SlideRule service, the python packages in this repository provide higher level access to SlideRule by hiding the GET and POST requests inside python function calls that accept and return basic python variable types (e.g. dictionaries, lists, numbers), and GeoDataFrames.

Basic Usage

The SlideRule service provides a number of services which allow a user to process ICESat-2 and HDF5 data. For example, the icesat2.atl06p python function makes a request to the atl06 service and returns calculated segment elevations from ATL03 data within a geospatial region.

# import (1)
from sliderule import icesat2

# region of interest (2)
grand_mesa = [ {"lon": -108.3435200747503, "lat": 38.89102961045247},
               {"lon": -107.7677425431139, "lat": 38.90611184543033},
               {"lon": -107.7818591266989, "lat": 39.26613714985466},
               {"lon": -108.3605610678553, "lat": 39.25086131372244},
               {"lon": -108.3435200747503, "lat": 38.89102961045247} ]

# initialize (3)
icesat2.init("icesat2sliderule.org")

# processing parameters (4)
parms = {
    "poly": grand_mesa["poly"],
    "srt": icesat2.SRT_LAND,
    "cnf": icesat2.CNF_SURFACE_HIGH,
    "len": 40.0,
    "res": 20.0,
    "maxi": 1
}

# make request (5)
gdf = icesat2.atl06p(parms)

This code snippet performs the following functions with respect to SlideRule:

  1. Imports the icesat2 module from the SlideRule Python packages

  2. Defines a polygon that captures the Grand Mesa region

  3. Initializes the icesat2 module with the address of the SlideRule server and other configuration parameters

  4. Builds an atl06 API request structure that specifies the region of interest and processing parameters

  5. Issues the request to the SlideRule service and returns the results in a pandas GeoDataFrame for further analysis

Common API Calls

Out of all the API calls available in SlideRule, there are a few common ones that handle most use cases. The functions associated with these APIs are listed below for convenience. For a complete reference, please see the API Reference.

function

description

init

Initialize the icesat2 package with the URL to the SlideRule service

atl06p

Perform ATL06-SR processing in parallel on ATL03 data and return gridded elevations

atl03sp

Subset ATL03 granuels in parallel and return the photon data

h5p

Read a list of datasets in parallel from an HDF5 file and return the values of the datasets

toregion

Convert a GeoJSON formatted polygon or shapefile into the format accepted by SlideRule

get_version

Get version information for the running servers and client

icepyx.atl06p

Uses icepyx region to perform ATL06-SR processing in parallel on ATL03 data and return gridded elevations

icepyx.atl03sp

Uses icepyx region to subset ATL03 granuels in parallel and return the photon data

source

Perform a direct API call to a SlideRule service