icesat2

The ICESat-2 Python API icesat2.py is used to access the services provided by the icesat2 plugin for SlideRule. From Python, the module can be imported via:

from sliderule import icesat2

init

sliderule.icesat2.init(url='slideruleearth.io', verbose=False, max_resources=300, loglevel=50, organization='sliderule', desired_nodes=None, time_to_live=60, bypass_dns=False, rethrow=False)[source]

Initializes the Python client for use with SlideRule and should be called before other ICESat-2 API calls. This function is a wrapper for the sliderule.init(…) function.

Parameters:: max_resources (int) – maximum number of H5 granules to process in the request

Examples

>>> from sliderule import icesat2
>>> icesat2.init()

atl03s

sliderule.icesat2.atl03s(parm, resource)[source]

Subsets ATL03 data given the polygon and time range provided and returns segments of photons

Parameters:

parms (dict) – parameters used to configure ATL03 subsetting (see Parameters)
resource (str) – ATL03 HDF5 filename

Returns:

ATL03 extents (see Photon Segments)

Return type:

GeoDataFrame

atl03sp

sliderule.icesat2.atl03sp(parm, callbacks={}, resources=None, keep_id=False, height_key=None)[source]

Performs ATL03 subsetting in parallel on ATL03 data and returns photon segment data. Unlike the atl03s function, this function does not take a resource as a parameter; instead it is expected that the parm argument includes a polygon which is used to fetch all available resources from the CMR system automatically.

Warning

Note, it is often the case that the list of resources (i.e. granules) returned by the CMR system includes granules that come close, but do not actually intersect the region of interest. This is due to geolocation margin added to all CMR ICESat-2 resources in order to account for the spacecraft off-pointing. The consequence is that SlideRule will return no data for some of the resources and issue a warning statement to that effect; this can be ignored and indicates no issue with the data processing.

Parameters:

parms (dict) –
parameters used to configure ATL03 subsetting (see Parameters)
callbacks (dictionary) – a callback function that is called for each result record
resources (list) – a list of granules to process (e.g. [“ATL03_20181019065445_03150111_005_01.h5”, …])
keep_id (bool) – whether to retain the “extent_id” column in the GeoDataFrame for future merges
height_key (str) – identifies the name of the column provided for the 3D CRS transformation

Returns:

ATL03 segments (see Photon Segments)

Return type:

GeoDataFrame

atl03v

sliderule.icesat2.atl03v(parm, resource)[source]

Subsets ATL03 data given the polygon and time range provided and returns counts of photons in segments

Parameters:

parms (dict) –
parameters used to configure ATL03 subsetting (see Parameters)
resource (str) – ATL03 HDF5 filename

Returns:

ATL03 extents (see Photon Segments)

Return type:

GeoDataFrame

atl03vp

sliderule.icesat2.atl03vp(parm, callbacks={}, resources=None, keep_id=False)[source]

Performs ATL03 subsetting in parallel on ATL03 data and returns counts of photons in segments. Unlike the atl03v function, this function does not take a resource as a parameter; instead it is expected that the parm argument includes a polygon which is used to fetch all available resources from the CMR system automatically.

Warning

Note, it is often the case that the list of resources (i.e. granules) returned by the CMR system includes granules that come close, but do not actually intersect the region of interest. This is due to geolocation margin added to all CMR ICESat-2 resources in order to account for the spacecraft off-pointing. The consequence is that SlideRule will return no data for some of the resources and issue a warning statement to that effect; this can be ignored and indicates no issue with the data processing.

Parameters:

parms (dict) –
parameters used to configure ATL03 subsetting (see Parameters)
callbacks (dictionary) – a callback function that is called for each result record
resources (list) – a list of granules to process (e.g. [“ATL03_20181019065445_03150111_005_01.h5”, …])
keep_id (bool) – whether to retain the “extent_id” column in the GeoDataFrame for future merges

Returns:

ATL03 segments (see Photon Segments)

Return type:

GeoDataFrame

atl06

sliderule.icesat2.atl06(parm, resource)[source]

Performs ATL06-SR processing on ATL03 data and returns geolocated elevations

Parameters:

parms (dict) –
parameters used to configure ATL06-SR algorithm processing (see Parameters)
resource (str) – ATL03 HDF5 filename

Returns:

geolocated elevations (see Elevations)

Return type:

GeoDataFrame

atl06p

sliderule.icesat2.atl06p(parm, callbacks={}, resources=None, keep_id=False, as_numpy_array=False, height_key=None)[source]

Performs ATL06-SR processing in parallel on ATL03 data and returns geolocated elevations. This function expects that the parm argument includes a polygon which is used to fetch all available resources from the CMR system automatically. If resources is specified then any polygon or resource filtering options supplied in parm are ignored.

Warning

It is often the case that the list of resources (i.e. granules) returned by the CMR system includes granules that come close, but do not actually intersect the region of interest. This is due to geolocation margin added to all CMR ICESat-2 resources in order to account for the spacecraft off-pointing. The consequence is that SlideRule will return no data for some of the resources and issue a warning statement to that effect; this can be ignored and indicates no issue with the data processing.

Parameters:

parms (dict) –
parameters used to configure ATL06-SR algorithm processing (see Parameters)
callbacks (dictionary) – a callback function that is called for each result record
resources (list) – a list of granules to process (e.g. [“ATL03_20181019065445_03150111_005_01.h5”, …])
keep_id (bool) – whether to retain the “extent_id” column in the GeoDataFrame for future merges
as_numpy_array (bool) – whether to provide all sampled values as numpy arrays even if there is only a single value
height_key (str) – identifies the name of the column provided for the 3D CRS transformation

Returns:

geolocated elevations (see Elevations)

Return type:

GeoDataFrame

Examples

>>> from sliderule import icesat2
>>> icesat2.init("slideruleearth.io", True)
>>> parms = { "cnf": 4, "ats": 20.0, "cnt": 10, "len": 40.0, "res": 20.0 }
>>> resources = ["ATL03_20181019065445_03150111_003_01.h5"]
>>> atl03_asset = "atlas-local"
>>> rsps = icesat2.atl06p(parms, asset=atl03_asset, resources=resources)
>>> rsps
        dh_fit_dx  w_surface_window_final  ...                       time                     geometry
0        0.000042               61.157661  ... 2018-10-19 06:54:46.104937  POINT (-63.82088 -79.00266)
1        0.002019               61.157683  ... 2018-10-19 06:54:46.467038  POINT (-63.82591 -79.00247)
2        0.001783               61.157678  ... 2018-10-19 06:54:46.107756  POINT (-63.82106 -79.00283)
3        0.000969               61.157666  ... 2018-10-19 06:54:46.469867  POINT (-63.82610 -79.00264)
4       -0.000801               61.157665  ... 2018-10-19 06:54:46.110574  POINT (-63.82124 -79.00301)
...           ...                     ...  ...                        ...                          ...
622407  -0.000970               61.157666  ... 2018-10-19 07:00:29.606632  POINT (135.57522 -78.98983)
622408   0.004620               61.157775  ... 2018-10-19 07:00:29.250312  POINT (135.57052 -78.98983)
622409  -0.001366               61.157671  ... 2018-10-19 07:00:29.609435  POINT (135.57504 -78.98966)
622410  -0.004041               61.157748  ... 2018-10-19 07:00:29.253123  POINT (135.57034 -78.98966)
622411  -0.000482               61.157663  ... 2018-10-19 07:00:29.612238  POINT (135.57485 -78.98948)

[622412 rows x 16 columns]

atl06s

sliderule.icesat2.atl06s(parm, resource)[source]

Subsets ATL06 data given the polygon and time range provided and returns elevations

Parameters:

parms (dict) –
parameters used to configure ATL03 subsetting (see Parameters)
resource (str) – ATL06 HDF5 filename

Returns:

ATL06 elevations

Return type:

GeoDataFrame

atl06sp

sliderule.icesat2.atl06sp(parm, callbacks={}, resources=None, keep_id=False, as_numpy_array=False, height_key=None)[source]

Performs ATL06 subsetting in parallel on ATL06 data and returns elevation data. Unlike the atl06s function, this function does not take a resource as a parameter; instead it is expected that the parm argument includes a polygon which is used to fetch all available resources from the CMR system automatically.

Warning

Note, it is often the case that the list of resources (i.e. granules) returned by the CMR system includes granules that come close, but do not actually intersect the region of interest. This is due to geolocation margin added to all CMR ICESat-2 resources in order to account for the spacecraft off-pointing. The consequence is that SlideRule will return no data for some of the resources and issue a warning statement to that effect; this can be ignored and indicates no issue with the data processing.

Parameters:

parms (dict) –
parameters used to configure ATL03 subsetting (see Parameters)
callbacks (dictionary) – a callback function that is called for each result record
resources (list) – a list of granules to process (e.g. [“ATL03_20181019065445_03150111_005_01.h5”, …])
keep_id (bool) – whether to retain the “extent_id” column in the GeoDataFrame for future merges
as_numpy_array (bool) – whether to provide all sampled values as numpy arrays even if there is only a single value
height_key (str) – identifies the name of the column provided for the 3D CRS transformation

Returns:

ATL06 elevations

Return type:

GeoDataFrame

atl08

sliderule.icesat2.atl08(parm, resource)[source]

Performs ATL08-PhoREAL processing on ATL03 and ATL08 data and returns geolocated elevations

Parameters:

parms (dict) –
parameters used to configure ATL06-SR algorithm processing (see Parameters)
resource (str) – ATL03 HDF5 filename

Returns:

geolocated vegatation statistics

Return type:

GeoDataFrame

atl08p

sliderule.icesat2.atl08p(parm, callbacks={}, resources=None, keep_id=False, as_numpy_array=False, height_key=None)[source]

Performs ATL08-PhoREAL processing in parallel on ATL03 and ATL08 data and returns geolocated vegatation statistics. This function expects that the parm argument includes a polygon which is used to fetch all available resources from the CMR system automatically. If resources is specified then any polygon or resource filtering options supplied in parm are ignored.

Warning

It is often the case that the list of resources (i.e. granules) returned by the CMR system includes granules that come close, but do not actually intersect the region of interest. This is due to geolocation margin added to all CMR ICESat-2 resources in order to account for the spacecraft off-pointing. The consequence is that SlideRule will return no data for some of the resources and issue a warning statement to that effect; this can be ignored and indicates no issue with the data processing.

Parameters:

parms (dict) –
parameters used to configure ATL06-SR algorithm processing (see Parameters)
callbacks (dictionary) – a callback function that is called for each result record
resources (list) – a list of granules to process (e.g. [“ATL03_20181019065445_03150111_005_01.h5”, …])
keep_id (bool) – whether to retain the “extent_id” column in the GeoDataFrame for future merges
as_numpy_array (bool) – whether to provide all sampled values as numpy arrays even if there is only a single value
height_key (str) – identifies the name of the column provided for the 3D CRS transformation

Returns:

geolocated vegetation statistics

Return type:

GeoDataFrame

atl13s

sliderule.icesat2.atl13s(parm, resource)[source]

Subsets ATL13 data given the polygon and time range provided and returns measurements

Parameters:

parms (dict) –
parameters used to configure ATL13 subsetting (see Parameters)
resource (str) – ATL13 HDF5 filename

Returns:

ATL13 water measurements

Return type:

GeoDataFrame

atl13sp

sliderule.icesat2.atl13sp(parm, callbacks={}, resources=None, keep_id=False, as_numpy_array=False, height_key=None)[source]

Performs ATL13 subsetting in parallel on ATL13 data and returns measurement data. Unlike the atl13s function, this function does not take a resource as a parameter; instead it is expected that the parm argument includes a polygon which is used to fetch all available resources from the CMR system automatically.

Parameters:

parms (dict) –
parameters used to configure ATL13 subsetting (see Parameters)
callbacks (dictionary) – a callback function that is called for each result record
resources (list) – a list of granules to process (e.g. [“ATL13_20181019065445_03150111_005_01.h5”, …])
keep_id (bool) – whether to retain the “extent_id” column in the GeoDataFrame for future merges
as_numpy_array (bool) – whether to provide all sampled values as numpy arrays even if there is only a single value
height_key (str) – identifies the name of the column provided for the 3D CRS transformation

Returns:

ATL13 water measurements

Return type:

GeoDataFrame

atl24v

sliderule.icesat2.atl24v(parm, resource)[source]: Provides statistics for the number of photons within a granule