ICESat-2 Module

The ICESat-2 module within SlideRule supports a number of both legacy p-series and s-series endpoints, as well as the newer DataFrame-based x-series endpoints. This document focuses on the x-series endpoints while still referencing the other legacy endpoints when helpful.

Three main kinds of data are returned by the ICESat-2 endpoints: segmented photon data, elevation data (from the ATL06-SR algorithm), and vegetation data (from the PhoREAL algorithm). All data returned by the ICESat-2 endpoints are organized around the concept of an extent. An extent is a variable length, customized ATL03 segment. It takes the ATL03 photons and divides them up based on their along-track distance, filters them, and then packages them together a single new custom segment. Given that the ICESat-2 standard data products have a well defined meaning for segment, SlideRule uses the term extent to indicate this custom-length and custom-filtered segment of photons.

The following processing flags are used for all ICESat-2 endpoints:

• 0x0001: Along track spread too short

• 0x0002: Too few photons

• 0x0004: Maximum iterations reached

• 0x0008: Out of bounds

• 0x0010: Underflow

• 0x0020: Overflow

In addition, most endpoints support the generation of a name filter using the granule parameter:

• rgt: Reference ground track

• cycle: Orbit cycle

• region: ATL03 region {1 to 14}

• version: ATL03 release version (e.g. 007)

1. ATL03 - atl03x¶

The SlideRule atl03x endpoint provides a service for ATL03 custom processing. This endpoint queries ATL03 input granules for photon heights and locations based on a set of photon-input parameters that select geographic and temporal ranges. It then selects a subset of these photons based on a set of photon classification parameters, and divides these selected photons into short along-track extents, each of which is suitable for generating a single height estimate. These extents may be returned to the client, or may be passed to downstream algorithms like the ATL06-SR height-estimation module, or the PhoREAL algorithm.

Using the Python client, this service is called via:

sliderule.run('atl03x', parms)

The default resulting DataFrame from this endpoint contains the following columns:

1.1 Photon-input Parameters¶

The photon-input parameters allow the user to select an area, a time range, or a specific ATL03 granule to use for input to the photon-selection algorithm. If multiple parameters are specified, the result will be those photons that match all of the parameters.

• poly: polygon defining region of interest (see Polygons)

• region_mask: geojson describing region of interest which enables rasterized subsetting on servers (see in geojson)

• track: reference pair track number (1, 2, 3, or 0 to include for all three; defaults to 0); note that this is combined with the beam selection as a union of the two

• beams: list of beam identifiers (gt1l, gt1r, gt2l, gt2r, gt3l, gt3r; defaults to all)

• spots: list of spots (1, 2, 3, 4, 5, 6); this is only supporting by the atl03x endpoint

• rgt: reference ground track (defaults to all if not specified)

• cycle: counter of 91-day repeat cycles completed by the mission (defaults to all if not specified)

• region: geographic region for corresponding standard product (defaults to all if not specified)

• t0: start time for filtering granules (format %Y-%m-%dT%H:%M:%SZ, e.g. 2018-10-13T00:00:00Z)

• t1: stop time for filtering granuels (format %Y-%m-%dT%H:%M:%SZ, e.g. 2018-10-13T00:00:00Z)

1.2 Photon-selection Parameters¶

Once the ATL03 input data are are selected, a set of photon-selection photon parameters are used to select from among the available photons. At this stage, additional photon-classification algorithms (ATL08, YAPC) may be selected beyond what is available in the ATL03 files. The criterial described by these parameters are applied together, so that only photons that fulfill all of the requirements are returned.

1.2.1 Native ATL03 Photon Classification¶

ATL03 contains a set of photon classification values, that are designed to identify signal photons for different surface types with specified confidence:

• srt: surface type: 0-land, 1-ocean, 2-sea ice, 3-land ice, 4-inland water

• cnf: confidence level for photon selection, can be supplied as a single value (which means the confidence must be at least that), or a list (which means the confidence must be in the list); note - the confidence can be supplied as strings {“atl03_tep”, “atl03_not_considered”, “atl03_background”, “atl03_within_10m”, “atl03_low”, “atl03_medium”, “atl03_high”} or as numbers {-2, -1, 0, 1, 2, 3, 4}.

• quality_ph: quality classification based on an ATL03 algorithms that attempt to identify instrumental artifacts, can be supplied as a single value (which means the classification must be exactly that), or a list (which means the classification must be in the list).

• podppd: pointing/geolocation degradation mask; each bit in the mask represents a pointing/geolocation solution quality assessment to be included; the bits are 0: nominal, 1: pod_degrade, 2: ppd_degrade, 3: podppd_degrade, 4: cal_nominal, 5: cal_pod_degrade, 6: cal_ppd_degrade, 7: cal_podppd_degrade.

1.2.2 YAPC Classification¶

The experimental YAPC (Yet Another Photon Classifier) photon-classification scheme assigns each photon a score based on the number of adjacent photons. YAPC parameters are provided as a dictionary, with entries described below:

• yapc: settings for the yapc algorithm; if provided then SlideRule will execute the YAPC classification on all photons

  • score: the minimum yapc classification score of a photon to be used in the processing request; the score is compared against the raw score values, so its scale depends on where the scores come from: 0-65535 for scores read from release 007 granules (weight_ph, where 65535 represents the saturation density), 0-255 for scores read from release 006 granules and for scores calculated on the servers (versions 1-3)

  • knn: the number of nearest neighbors to use, or specify 0 to allow automatic selection of the number of neighbors (version 2 only)

  • min_knn: minimum number of k-nearest neighbors (version 3 only)

  • win_h: the window height used to filter the nearest neighbors (overrides calculated value if non-zero)

  • win_x: the window width used to filter the nearest neighbors

  • version: the version of the YAPC algorithm to use; 0:read from ATL03 granule, 1-3:algorithm version (not supported by atl03x; requests to atl03x with versions 1-3 are rejected with an error)

To run the YAPC algorithm, specify the YAPC settings as a sub-dictionary. Here is an example set of parameters that runs YAPC:

parms = {
    "cnf": 0,
    "yapc": { "score": 0, "version": 3, "knn": 4 },
    "ats": 10.0,
    "cnt": 5,
    "len": 20.0,
    "res": 20.0
}

1.2.3 ATL08 Classification¶

If ATL08 classification parameters are specified, the ATL08 (vegetation height) files corresponding to the ATL03 files are queried for the more advanced classification scheme available in those files. Photons are then selected based on the classification values specified. Note that srt=0 (land) and cnf=0 (no native filtering) should be specified to allow all ATL08 photons to be used.

• atl08_class: list of ATL08 classifications used to select which photons are used in the processing (the available classifications are: “atl08_noise”, “atl08_ground”, “atl08_canopy”, “atl08_top_of_canopy”, “atl08_unclassified”)

1.2.4 ATL24 Classification¶

If ATL24 classification parameters are specified, the ATL24 (bathymetry) files corresponding to the ATL03 files are queried for the more advanced classification scheme available in those files. Photons are then selected based on the classification values specified. Note that srt=-1 (dynamic) and cnf=-1 (no native filtering) should be specified to allow all ATL24 photons to be used.

• atl24

  • class_ph: list of ATL24 classifications used to select which photons are used in the processing (the available classifications are: “bathymetry”, “sea_surface”, “unclassified”)

1.2.5 ATL03 Signal Classification¶

Starting with release 007, ATL03 granules include an experimental per-photon signal classification (signal_class_ph) derived from the weight_ph photon weights; photons with the highest weights (the highest reflectors) are labelled as the primary signal, and the fitted photons are the subset of the primary signal most likely to represent a surface return. The atl03_signal_class parameter defaults to every classification, which selects every photon without reading signal_class_ph; when a subset of classifications is specified, only photons with those classifications are selected and the classification of each selected photon is included in the response.

• atl03_signal_class: list of ATL03 signal classifications used to select which photons are used in the processing; defaults to all of them (the available classifications are: “ignored”, “likely_noise”, “likely_signal”, “signal_below”, “signal_above”, “primary_signal”, “fitted_signal”; the corresponding numeric values -1 through 5 may also be supplied)

This selection is only supported by the atl03x endpoint and requires ATL03 release 007 or later granules; requests against earlier releases are rejected with an error. Because the selection happens before any of the processing algorithms run, it can be combined with fit to produce elevations fit to only the selected photons (for example, a fit to the highest reflecting surface using [“primary_signal”, “fitted_signal”]).

1.3 Photon-extent Parameters¶

Selected photons are divided and aggregated using along-track samples (“extents”) with user-specified length. These extends may or may not align with the original 20-m segments of ATL03 photons. The len parameter specifies the length of each extent, and the _res_parameter specifies the distance between subsequent extent centers. If res is less than len, subsequent segments will contain duplicate photons. The API may also select photons based on their along-track distance, or based on the segment-id parameters in the ATL03 product (see the dist_in_seg parameter).

• len: length of each extent in meters

• res: step distance for successive extents in meters

• dist_in_seg: true|false flag indicating that the units of the len and res are in ATL03 segments (e.g. if true then a len=2 is exactly 2 ATL03 segments which is approximately 40 meters)

Extents are optionally filtered based on the number of photons in each extent and the distribution of those photons. If the pass_invalid parameter is set to False, only those extents fulfilling these criteria will be returned.

• pass_invalid: true|false flag indicating whether or not extents that fail validation checks are still used and returned in the results

• ats: minimum along track spread, which is the distance in meters between the outermost valid photons in the variable length segment

• cnt: minimum photon count in segment

1.4 Ancillary Data¶

The ancillary field parameters allow the user to request additional fields from the source datasets being subsetted. Ancillary data returned from the atl03x (as well as theatl03s and atl03sp) APIs are per-photon values that are read from the ATL03 granules. No processing is performed on the data read out of the ATL03 granule. The fields must come from either a per-photon variable (atl03_ph_fields), a per-segment variable (atl03_geo_fields, atl03_corr_fields), or a rate variable (atl03_bckgrd_fields).

Ancillary fields are used to specify additional fields in the ATL03, ATL08, and ATL09 granules to be returned with the photon extent and dowstream customized products. Each field provided by the user will result in a corresponding column added to the returned GeoDataFrame. Note: if a field is requested that is already present in the default GeoDataFrame, then the name of both fields will be changed to include a _x suffix for the default incusion of the field, and a _y for the ancillary inclusion of the field. In general, they should have the same value, but in some cases the ancillary field goes through different processing steps and may possibly contain a different value.

• atl03_bckgrd_fields: fields in the “bckgrd_atlas” group of the ATL03 granule

• atl03_geo_fields: fields in the “geolocation” group of the ATL03 granule

• atl03_cor_fields: fields in the “geophys_corr” group of the ATL03 granule

• atl03_ph_fields: fields in the “heights” group of the ATL03 granule

• atl08_fields: fields in the “land_segments” group of the ATL08 granule

• atl09_fields: fields in the “bckgrd_atlas”, “high_rate”, and “low_rate” groups of the ATL09 granule (must provide the group name in the request, e.g. “low_rate/bsnow_con”)

For example:

parms = {
    "atl03_geo_fields":     ["solar_elevation"],
    "atl03_ph_fields":      ["pce_mframe_cnt"],
    "atl08_fields":         ["asr"]
}

1.5 ATL06-SR Algorithm¶

The ATL06-SR algorithm fits a line segment to the photons in each extent, using an iterative selection refinement to eliminate noise photons not correctly identified by the photon classification. The results are then checked against three parameters : sigma_r_max, which eliminates segments for which the robust dispersion of the residuals is too large, and the ats and cnt parameters described above, which eliminate segments for which the iterative fitting has eliminated too many photons. The algorithm is run by supplying the fit parameter in the processing request, but can also be run via the legacy atl06 and atl06p endpoints.

This algorithm replaces the columns of the source DataFrame with the following columns:

Using the Python client, this service is called via:

parms = {
  "fit": {}
}
sliderule.run('atl03x', parms)

1.5.1 ATL06-SR Parameters¶

The ATL06-SR parameters are supplied in user requests under the fit key and include:

• fit:

  • maxi: maximum iterations, not including initial least-squares-fit selection

  • H_min_win: minimum height to which the refined photon-selection window is allowed to shrink, in meters

  • sigma_r_max: maximum robust dispersion in meters

1.5.2 ATL06-SR Ancillary Data¶

Ancillary data returned from the fit algorithm (as well as atl06 and atl06p APIs) come from the ancillary fields specified for ATL03, but instead of being returned as-is, they are processed using the ATL06 least-squares-fit algorithm, and only the result is returned. In other words, ancillary data points from ATL03 to be included in an ATL06-SR result are treated just like the h_mean, latitude, and longitude variables, and returned as a fitted double-precision floating point value.

1.6 PhoREAL Algorithm¶

The PhoREAL algorithm is a modified version of the ATL08 canopy metrics algorithm developed at the University of Texas at Austin that calculates canopy metrics on a segment of ATL03 photons. The algorithm is run by supplying the phoreal parameter in the atl03x request, but can also be accessed via the legacy endpoints atl08 and atl08p.

This algorithm replaces the columns of the source DataFrame with the following columns:

Using the Python client, this service is called via:

parms = {
  "phoreal": {}
}
sliderule.run('atl03x', parms)

1.6.1 PhoREAL Parameters¶

The PhoREAL parameters are supplied in user requests under the phoreal key and include:

• phoreal:

  • binsize: size of the vertical photon bin in meters

  • geoloc: algorithm to use to calculate the geolocation (latitude, longitude, along-track distance, and time) of each custom length PhoREAL segment; “mean” - takes the average value across all photons in the segment; “median” - takes the median value across all photons in the segment; “center” - takes the halfway value calculated by the average of the first and last photon in the segment

  • use_abs_h: boolean whether the absolute photon heights are used instead of the normalized heights

  • send_waveform: boolean whether to send to the client the photon height histograms in addition to the vegetation statistics

  • above_classifier: boolean whether to use the ABoVE photon classifier when determining top of canopy photons

1.6.2 ATL08-PhoREAL Ancillary Data¶

Ancillary data returned from the atl08 and atl08p APIs come from the land_segments group of the ATL08 granules. The data goes through a series of processing steps before being returned back to the user as per-extent (i.e. variable-length segment) result values.

• When a user requests an ATL08 ancillary field, the ATL08 classifications are automatically enabled with all unclassified photons filtered out (i.e. noise, ground, canopy, and top of canopy are included; unclassified photons are excluded). If the user is also requesting PhoREAL processing, then noise photons are automatically filtered out as well. Lastly, if the user manually specifies which ATL08 photon classifications to use, then that manual specification takes precedence and is used.

• If a user manually specifies that unclassified photons are to be included, the value used for an ancillary field for that photon has all 1’s in the binary encoding of that value. For example, if it is an 8-bit unsigned integer, the value would be 255. If it is a double-precision floating point, the value would be -nan.

• Since the ATL08 APIs return per-extent values and not per-photon values, the set of per-photon ancillary field values must be reduced in some way to a single per-extent value to be returned back to the user. There are currently two options available for how this reduction occurs.

  1. Nearest Neighbor (Mode): the value that appears most often in the extent is selected. This is the default method. For example, if a user specifies `atl08_fields": [“asr”]`` in their parameters, and the PhoREAL extent consists of mostly two-thirds of one ATL08 segment, and a third of the next ATL08 segment (and if the photons rate is consistent across those two ATL08 segments), then the value returned by the nearest neighbor processing will be the ATL08 land_segment value from the first ATL08 segment.

  2. Interpolation (Average): the value that is the average of all the per-photon values provided. This is only performed when the user appends a “%” to the end of the field’s name in the field list parameter. For example, if a user specifies `atl08_fields": [“asr%”]`` in their parameters, then the returned result is the average of all of the “asr” values in the PhoREAL extent. Note that the GeoDataFrame returned to the user will include the “%” in the column name for this particular field - that is so a user can request both nearest neighbor and interpolated values for the same field in a single request.

2. ATL06 - atl06x¶

The SlideRule atl06x endpoint provides a service for ATL06 subsetting and custom processing. This endpoint queries ATL06 input granules for segment heights and locations based on geographic and temporal ranges. The resulting extents are typically directly returned to the client, but may be passed to downstream algorithms and custom processing steps like raster sampling.

Using the Python client, this service is called via:

sliderule.run('atl06x', parms)

The default resulting DataFrame from this endpoint contains the following columns:

2.1 Ancillary Data¶

Ancillary data returned from the atl06x endpoint (as well as atl06 and atl06p endpoints) come from the land_ice_segments group of the ATL06 granules. The data is mostly returned as-is, with one exception. Double-precision and single-precision floating point variables are checked to see if they contain the maximum value of their respective encodings, and if so, a floating point NaN (not-a-number) is returned instead. This check is not performed for integer variables because the maximum value of an encoded integer can sometimes be a valid value (e.g. bit masks).

• atl06_fields: fields in the “land_ice_segments” group of the ATL06 granule, provided as a list of strings

For example,

parms = {
    "atl06_fields": ["ground_track/ref_azimuth"],
}
gdf = sliderule.run("atl06x", parms)

3. ATL08 - atl08x¶

The SlideRule atl08x endpoint provides a service for ATL08 subsetting and custom processing. This endpoint queries ATL08 input granules for segment vegetation statistics and locations based on geographic and temporal ranges. These statistics are typically directly returned to the client, but may be passed to downstream algorithms and custom processing steps like raster sampling.

Using the Python client, this service is called via:

sliderule.run('atl08x', parms)

The default resulting DataFrame from this endpoint contains the following columns:

3.1 Quality Filter Parameters¶

The ATL08 data can be filtered based on different quality filters.

• te_quality_score: terrain quality score threshold

• can_quality_score: canopy quality score threshold

3.2 Ancillary Data¶

Ancillary data returned from the atl08x endpoint (as well as atl08 and atl08p endpoints) come from the {beam} group of the ATL08 granules.

• atl08_fields: fields in the beam group of the ATL08 granule, provided as a list of strings

For example,

parms = {
    "atl08_fields": ["asr"],
}
gdf = sliderule.run("atl08x", parms)

4. ATL13 - atl13x¶

The SlideRule atl13x endpoint provides a service for ATL13 subsetting and custom processing. This endpoint queries ATL13 input granules for segment inland lake statistics based on geographic and temporal ranges. These statistics are typically directly returned to the client, but may be passed to downstream algorithms and custom processing steps like raster sampling.

This endpoint is called via:

sliderule.run('atl13x', parms)

The default resulting DataFrame from this API contains the following columns:

4.1 Inland Lake Parameters¶

Inland lake data can be queried using the following parameters under the atl13 key:

• atl13:

  • refid: ATL13 reference id

  • name: lake (or body of water) name

  • coord: latitude and longitude coordinates contained within the desired body of water|object {“lat”: $lat, "lon":$lon}

4.2 Ancillary Data¶

Ancillary data returned from the atl13x endpoint comes from the {beam} group of the ATL13 granules.

• atl13_fields: fields in the beam group of the ATL13 granule, provided as a list of strings

For example,

parms = {
    "atl08_fields": ["ice_flag"],
}
gdf = sliderule.run("atl13x", parms)

5. ATL24 - atl24x¶

The SlideRule atl24x endpoint provides a service for ATL24 subsetting and custom processing. This endpoint queries ATL24 input granules for bathymetry data for ATL03 photons based on geographic and temporal ranges. ATL24 provides bathymetry labels and metrics which are typically directly returned to the client, but may be passed to downstream algorithms and custom processing steps like raster sampling.

This endpoint is called via:

sliderule.run('atl24x', parms)

The default resulting DataFrame from this API contains the following columns:

5.1 Query Parameters¶

The following parameters are supported under the atl24 key for customizing the request to ATL24 and filtering which data is returned.

• atl24:

  • compact: reduces number of fields to minimal viable set (boolean)

  • class_ph: ATL24 classification filter (list; 0:unclassified, 40:bathymetry, 41:sea surface)

  • confidence_threshold|minimal bathymetry confidence score|double; 0 to 1.0|0|

  • invalid_kd: invalid kd flag values to allow (“on”: includes only photons with invalid kd; “off”: includes only photons without invalid kd; defaults to both when not specified)

  • invalid_wind_speed: invalid wind speed flag values to allow (“on”: includes only photons with invalid wind speed; “off”: includes only photons without invalid wind speed; defaults to both when not specified)

  • low_confidence: low confidence flag values to allow (“on”: includes only low confidence photons; “off”: includes only high confidence photons; defaults to both when not specified)

  • night: night flag values to allow (“on”: includes only photons collected at night; “off”: includes only photons collected during the day; defaults to both when not specified)

  • sensor_depth_exceeded: sensor depth exceeded flag values to allow (“on”: includes only photons at a depth greater than the sensor depth; “off”: includes only photons at a depth less then the sensor depth; defaults to both when not specified)

5.2 Ancillary Data¶

Ancillary data returned from the atl24x endpoint comes from the {beam} group of the ATL24 granules.

• anc_fields: fields in the beam group of the ATL24 granule, provided as a list of strings

For example,

parms = {
    "anc_fields": ["index_ph"],
}
gdf = sliderule.run("atl24x", parms)

Appendix A: Legacy Endpoints¶

For legacy endpoints, each extent is uniquely identified by an extent ID. The extent ID is analogous to the ATL03 segment ID, and is consistently generated for any extent given the same input parameters. This means subsequent runs of SlideRule with the same request parameters will return the same extent IDs.

While all data returned from SlideRule for ATL03/06/08 endpoints include the extent ID (as extent_id), by default the Python client strips it out when it creates the final GeoDataFrame. There is an option to keep the extend ID by setting the “keep_id” argument in the atl03/06/08 group of Python functions to True. This is useful when performing merges on GeoDataFrames from multiple APIs (for example, you can combine results from atl06 and atl08 endpoints and created a single GeoDataFrame with both elevation and vegatation data in it).

Result times returned by SlideRule for legacy endpoints are in standard Unix nanoseconds, while times provided in the ICESat-2 standard data products are in seconds from the ATLAS Epoch. The server-side code performs this conversion for you. But if you are using ICESat-2 products direction in addition to SlideRule results, and need to convert between them, you must first convert the unix time to standard GPS time, and then you need to subtract the number of seconds between the GPS epoch which is January 6, 2018 at midnight (1980-01-06T00:00:00.000000Z) and the ATLAS SDP epoch of January 1, 2018 at midnight (2018-01-01T00:00:00.000000Z). That number is 1198800018 seconds.

A.1 Segmented Photon Data - atl03sp¶

The photon data is stored as along-track segments inside the ATL03 granules, which is then broken apart by SlideRule and re-segmented according to processing parameters supplied at the time of the request. The new segments are called extents. When the length of an extent is 40 meters, and the step size is 20 meters, the extent matches the ATL06 segments.

Most of the time, the photon extents are kept internal to SlideRule and not returned to the user. But there are some APIs that do return raw photon extents for the user to process on their own.

Even though this offloads processing on the server, the API calls can take longer since more data needs to be returned to the user, which can bottleneck over the network.

Photon extents are returned as GeoDataFrames where each row is a photon. Each extent represents the data that the ATL06 algorithm uses to generate a single ATL06 elevation. When the step size is shorter than the length of the extent, the extents returned overlap each other which means that each photon is being returned multiple times and will be duplicated in the resulting GeoDataFrame.

The GeoDataFrame for each photon extent has the following columns:

• track: reference pair track number (1, 2, 3)

• sc_orient: spacecraft orientation (0: backwards, 1: forwards)

• rgt: reference ground track

• cycle: cycle

• segment_id: segment ID of first ATL03 segment in result

• segment_dist: along track distance from the equator to the center of the extent (in meters)

• count: the number of photons in the segment

• time: nanoseconds from Unix epoch (January 1, 1970) without leap seconds

• latitude: latitude (-90.0 to 90.0)

• longitude: longitude (-180.0 to 180.0)

• x_atc: along track distance of the photon in meters (with respect to the center of the segment)

• y_atc: across track distance of the photon in meters

• across: across track distance of the photon in meters

• height: height of the photon in meters

• solar_elevation: solar elevation from ATL03 at time of measurement, in degrees

• background_rate: background photon counts per second

• atl08_class: the photon’s ATL08 classification (0: noise, 1: ground, 2: canopy, 3: top of canopy, 4: unclassified)

• atl03_cnf: the photon’s ATL03 confidence level (-2: TEP, -1: not considered, 0: background, 1: within 10m, 2: low, 3: medium, 4: high)

• quality_ph: the photon’s quality classification (0: nominal, 1: possible after pulse, 2: possible impulse responpse effect, 3: possible tep)

• yapc_score: the photon’s YAPC photon weight (a photon-density score - higher is denser; when version: 0 this is the raw weight_ph value read from the granule; 0 - 65535 for scores read from release 007 granules, 0 - 255 otherwise)

Note: when PhoREAL is enabled, the ATL03 extent records (atl03rec) are enhanced to include the following populated fields:

• relief: ATL08 normalized photon heights

• landcover: ATL08 landcover flags

• snowcover: ATL08 snowcover flags

A.2 Elevations - atl06p¶

The primary result returned by SlideRule for ICESat-2 ATL06-SR processing requests is a set of geolocated elevations corresponding to a geolocated ATL03 along-track segment. The elevations are contained in a GeoDataFrame where each row represents a calculated elevation.

The elevation GeoDataFrame has the following columns:

• extent_id: unique ID associated with custom ATL03 segment (removed from final GeoDataFrame by default)

• segment_id: segment ID of first ATL03 segment in result

• n_fit_photons: number of photons used in final calculation

• pflags: processing flags (0x1 - spread too short; 0x2 - too few photons; 0x4 - max iterations reached)

• rgt: reference ground track

• cycle: cycle

• region: region of source granule

• spot: laser spot 1 to 6

• gt: ground track (10: GT1L, 20: GT1R, 30: GT2L, 40: GT2R, 50: GT3L, 60: GT3R)

• x_atc: along track distance from the equator in meters

• time: nanoseconds from Unix epoch (January 1, 1970) without leap seconds

• lat: latitude (-90.0 to 90.0)

• lon: longitude (-180.0 to 180.0)

• h_mean: elevation in meters from ellipsoid

• dh_fit_dx: along-track slope

• y_atc: across-track distance

• w_surface_window_final: width of the window used to select the final set of photons used in the calculation

• rms_misfit: measured error in the linear fit of the surface

• h_sigma: error estimate for the least squares fit model

A.3 Vegetation Metrics (PhoREAL) - atl08p¶

The primary result returned by SlideRule for ICESat-2 PhoREAL processing requests is a set of geolocated vegetation metrics corresponding to a geolocated ATL03 along-track segment. The metrics are contained in a GeoDataFrame where each row represents a segment.

The vegetation GeoDataFrame has the following columns:

• extent_id: unique ID associated with custom ATL03 segment (removed from final GeoDataFrame by default)

• segment_id: segment ID of first ATL03 segment in result

• rgt: reference ground track

• cycle: cycle

• region: region of source granule

• spot: laser spot 1 to 6

• gt: ground track (10: GT1L, 20: GT1R, 30: GT2L, 40: GT2R, 50: GT3L, 60: GT3R)

• ph_count: total number of photons used by PhoREAL algorithm for this extent

• gnd_count: number of ground photons used by PhoREAL algorithm for this extent

• veg_count: number of vegetation (canopy and top of canopy) photons used by PhoREAL algorithm for this extent

• landcover: flag indicating if segment includes land surfaces

• snowcover: flag indicating if snow is present in the segment

• time: nanoseconds from Unix epoch (January 1, 1970) without leap seconds

• lat: latitude (-90.0 to 90.0)

• lon: longitude (-180.0 to 180.0)

• x_atc: along track distance from the equator in meters

• solar_elevation: solar elevation from ATL03 at time of measurement, in degrees

• h_te_median: median terrain elevation in meters (absolute heights)

• h_max_canopy: maximum relief height for canopy photons

• h_min_canopy: minimum relief height for canopy photons

• h_mean_canopy: average relief height for canopy photons

• h_canopy: 98th percentile relief height for canopy photons

• canopy_openness: standard deviation of relief height for canopy photons

• canopy_h_metrics: relief height at given percentile for canopy photons

A.4 Callbacks¶

For large processing requests, it is possible that the data returned from the API is too large or impractical to fit in the local memory of the Python interpreter making the request. In these cases, certain APIs in the SlideRule Python client allow the calling application to provide a callback function that is called for every result that is returned by the servers.

If a callback is supplied, the API will not return back to the calling application anything associated with the supplied record types, but assumes the callback fully handles processing the data.

The callback function takes the following form callback(record, session) and handles processing streamed records for a request. The record parameter is the passback variable that contains the streamed record. The session parameter is the passback variable holding the current SlideRule client session.

Here is an example of a callback being used for the atl03sp function:

rec_cnt = 0
ph_cnt = 1

def atl03rec_cb(rec, session):
    global rec_cnt, ph_cnt
    rec_cnt += 1
    ph_cnt += rec["count"][0] + rec["count"][1]
    print("{} {}".format(rec_cnt, ph_cnt), end='\r')

gdf = icesat2.atl03sp({}, callbacks = {"atl03rec": atl03rec_cb})