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 icesat2Functions¶
init¶
sliderule.icesat2.init(url='slideruleearth.io', verbose=False, max_resources=None, loglevel=50, organization='sliderule', desired_nodes=None, time_to_live=60, rethrow=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 the sliderule.init(...) function </api_reference/sliderule.html#init>_.
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)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 </user_guide/icesat2.html#parameters>_)resource (str) ATL03 HDF5 filename
Returns
GeoDataFrame
ATL03 extents (see Photon Segments </user_guide/icesat2.html#segmented-photon-data>_)
atl03sp¶
sliderule.icesat2.atl03sp(parm, callbacks={}, resources=None, keep_id=False, height_key=None)Performs ATL03 subsetting in parallel on ATL03 data and returns photon segment data. Unlike the atl03s <#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.
Warnings
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 </user_guide/icesat2.html#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_007_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
GeoDataFrame
ATL03 segments (see Photon Segments </user_guide/icesat2.html#photon-segments>_)
atl03v¶
sliderule.icesat2.atl03v(parm, resource)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 </user_guide/icesat2.html#parameters>_)resource (str) ATL03 HDF5 filename
Returns
GeoDataFrame
ATL03 extents (see Photon Segments </user_guide/icesat2.html#segmented-photon-data>_)
atl03vp¶
sliderule.icesat2.atl03vp(parm, callbacks={}, resources=None, keep_id=False)Performs ATL03 subsetting in parallel on ATL03 data and returns counts of photons in segments. Unlike the atl03v <#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.
Warnings
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 </user_guide/icesat2.html#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_007_01.h5”, ...])
keep_id (bool) whether to retain the “extent_id” column in the GeoDataFrame for future merges
Returns
GeoDataFrame
ATL03 segments (see Photon Segments </user_guide/icesat2.html#photon-segments>_)
atl06¶
sliderule.icesat2.atl06(parm, resource)Performs ATL06-SR processing on ATL03 data and returns geolocated elevations
Parameters
parms (dict) parameters used to configure ATL06-SR algorithm processing (see
Parameters </user_guide/icesat2.html#parameters>_)resource (str) ATL03 HDF5 filename
Returns
GeoDataFrame
geolocated elevations (see Elevations </user_guide/icesat2.html#elevations>_)
atl06p¶
sliderule.icesat2.atl06p(parm, callbacks={}, resources=None, keep_id=False, as_numpy_array=False, height_key=None)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.
Warnings
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 </user_guide/icesat2.html#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_007_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
GeoDataFrame
geolocated elevations (see Elevations </user_guide/icesat2.html#elevations>_)
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)Subsets ATL06 data given the polygon and time range provided and returns elevations
Parameters
parms (dict) parameters used to configure ATL03 subsetting (see
Parameters </user_guide/icesat2.html#parameters>_)resource (str) ATL06 HDF5 filename
Returns
GeoDataFrame
ATL06 elevations
atl06sp¶
sliderule.icesat2.atl06sp(parm, callbacks={}, resources=None, keep_id=False, as_numpy_array=False, height_key=None)Performs ATL06 subsetting in parallel on ATL06 data and returns elevation data. Unlike the atl06s <#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.
Warnings
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 </user_guide/icesat2.html#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_007_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
GeoDataFrame
ATL06 elevations
atl08¶
sliderule.icesat2.atl08(parm, resource)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 </user_guide/icesat2.html#parameters>_)resource (str) ATL03 HDF5 filename
Returns
GeoDataFrame
geolocated vegatation statistics
atl08p¶
sliderule.icesat2.atl08p(parm, callbacks={}, resources=None, keep_id=False, as_numpy_array=False, height_key=None)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.
Warnings
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 </user_guide/icesat2.html#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_007_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
GeoDataFrame
geolocated vegetation statistics
atl13s¶
sliderule.icesat2.atl13s(parm, resource)Subsets ATL13 data given the polygon and time range provided and returns measurements
Parameters
parms (dict) parameters used to configure ATL13 subsetting (see
Parameters </user_guide/icesat2.html#parameters>_)resource (str) ATL13 HDF5 filename
Returns
GeoDataFrame
ATL13 water measurements
atl13sp¶
sliderule.icesat2.atl13sp(parm, callbacks={}, resources=None, keep_id=False, as_numpy_array=False, height_key=None)Performs ATL13 subsetting in parallel on ATL13 data and returns measurement data. Unlike the atl13s <#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 </user_guide/icesat2.html#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_007_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
GeoDataFrame
ATL13 water measurements
atl24v¶
sliderule.icesat2.atl24v(parm, resource)Provides statistics for the number of photons within a granule