Components

APIformatting

class icepyx.core.APIformatting.Parameters(partype, values=None, reqtype=None)

Bases: object

Build and update the parameter lists needed to submit a data order

Parameters:

partypestring: Type of parameter list. Must be one of [‘CMR’,’required’,’subset’]
valuesdictionary, default None: Dictionary of already-formatted parameters, if there are any, to avoid re-creating them.
reqtypestring, default None: For partype==’required’, indicates which parameters are required based on the type of query. Must be one of [‘search’,’download’]

build_params(**kwargs)

Build the parameter dictionary of formatted key:value pairs for submission to NSIDC in the data request.

Parameters:

**kwargs

Keyword inputs containing the needed information to build the parameter list, depending on parameter type, if the already formatted key:value is not submitted as a kwarg. May include optional keyword arguments to be passed to the subsetter. Valid keywords are time, bbox OR Boundingshape, format, projection, projection_parameters, and Coverage.

Keyword argument inputs for ‘CMR’ may include: start, end, extent_type, spatial_extent Keyword argument inputs for ‘required’ may include: product or short_name, version, page_size, page_num, request_mode, include_meta, client_string Keyword argument inputs for ‘subset’ may include: geom_filepath, start, end, extent_type, spatial_extent

check_req_values(): Check that all of the required keys have values, if the key was passed in with the values parameter.

check_values(): Check that the non-required keys have values, if the key was passed in with the values parameter.

property fmted_keys: Returns the dictionary of formatted keys associated with the parameter object.

property poss_keys: Returns a list of possible input keys for the given parameter object. Possible input keys depend on the parameter type (partype).

icepyx.core.APIformatting.combine_params(*param_dicts)

Combine multiple dictionaries into one.

Merging is performed in sequence using dict.update(); dictionaries later in the list overwrite those earlier.

Parameters:

paramsdictionaries: Unlimited number of dictionaries to combine

Returns:

A single dictionary of all input dictionaries combined

Examples

>>> CMRparams = {'temporal': '2019-02-20T00:00:00Z,2019-02-28T23:59:59Z', 'bounding_box': '-55,68,-48,71'}
>>> reqparams = {'short_name': 'ATL06', 'version': '002', 'page_size': 2000, 'page_num': 1}
>>> ipx.core.APIformatting.combine_params(CMRparams, reqparams)
{'temporal': '2019-02-20T00:00:00Z,2019-02-28T23:59:59Z',
'bounding_box': '-55,68,-48,71',
'short_name': 'ATL06',
'version': '002',
'page_size': 2000,
'page_num': 1}

icepyx.core.APIformatting.to_string(params)

Combine a parameter dictionary into a single url string

Parameters:

paramsdictionary

Returns:

url string of input dictionary (not encoded)

Examples

>>> CMRparams = {'temporal': '2019-02-20T00:00:00Z,2019-02-28T23:59:59Z',
...             'bounding_box': '-55,68,-48,71'}
>>> reqparams = {'short_name': 'ATL06', 'version': '002', 'page_size': 2000, 'page_num': 1}
>>> params = ipx.core.APIformatting.combine_params(CMRparams, reqparams)
>>> ipx.core.APIformatting.to_string(params)
'temporal=2019-02-20T00:00:00Z,2019-02-28T23:59:59Z&bounding_box=-55,68,-48,71&short_name=ATL06&version=002&page_size=2000&page_num=1'

EarthdataAuthMixin

exception icepyx.core.auth.AuthenticationError

Bases: Exception

Raised when an error is encountered while authenticating Earthdata credentials

class icepyx.core.auth.EarthdataAuthMixin(auth=None)

Bases: object

This mixin class generates the needed authentication sessions and tokens, including for NASA Earthdata cloud access. Authentication is completed using the [earthaccess library](https://nsidc.github.io/earthaccess/). Methods for authenticating are:

Storing credentials as environment variables ($EARTHDATA_LOGIN and $EARTHDATA_PASSWORD)

Entering credentials interactively

Storing credentials in a .netrc file (not recommended for security reasons)

More details on using these methods is available in the [earthaccess documentation](https://nsidc.github.io/earthaccess/tutorials/restricted-datasets/#auth).

This class can be inherited by any other class that requires authentication. For example, the Query class inherits this one, and so a Query object has the .session property. The method earthdata_login() is included for backwards compatibility.

The class can be created without any initialization parameters, and the properties will be populated when they are called. It can alternately be initialized with an earthaccess.auth.Auth object, which will then be used to create a session or s3login_credentials as they are called.

Parameters:

authearthaccess.auth.Auth, default None: Optional parameter to initialize an object with existing credentials.

Examples

>>> a = EarthdataAuthMixin()
>>> a.session 
>>> a.s3login_credentials 

property auth: Authentication object returned from earthaccess.login() which stores user authentication.

earthdata_login(uid=None, email=None, s3token=None, **kwargs) → None

Authenticate with NASA Earthdata to enable data ordering and download. Credential storage details are described in the EathdataAuthMixin class section.

Note: This method is deprecated and will be removed in a future release. It is no longer required to explicitly run .earthdata_login(). Authentication will be performed by the module as needed.

Parameters:

uidstring, default None: Deprecated keyword for Earthdata login user ID.
emailstring, default None: Deprecated keyword for backwards compatibility.
s3tokenboolean, default None: Deprecated keyword to generate AWS s3 ICESat-2 data access credentials
kwargskey:value pairs: Keyword arguments to be passed into earthaccess.login().

Examples

>>> reg_a = ipx.Query('ATL06',[-55, 68, -48, 71],['2019-02-20','2019-02-28']) 
>>> reg_a.earthdata_login() 
Enter your Earthdata Login username: ___________________

EARTHDATA_USERNAME and EARTHDATA_PASSWORD are not set in the current environment, try setting them or use a different strategy (netrc, interactive) No .netrc found in /Users/username

property s3login_credentials

A dictionary which stores login credentials for AWS s3 access. This property is accessed if using AWS cloud data.

Because s3 tokens are only good for one hour, this function will automatically check if an hour has elapsed since the last token use and generate a new token if necessary.

property session: Earthaccess session object for connecting to Earthdata resources.

granules

class icepyx.core.granules.Granules

Bases: EarthdataAuthMixin

Interact with ICESat-2 data granules. This includes finding, ordering, and downloading them as well as (not yet implemented) getting already downloaded granules into the query object.

Returns:

Granules object

download(verbose, path, restart=False)

Downloads the data for the object’s orderIDs, which are generated by ordering data from the NSIDC.

Parameters:

verboseboolean, default False: Print out all feedback available from the order process. Progress information is automatically printed regardless of the value of verbose.
pathstring: String with complete path to desired download directory and location.
restartboolean, default False: Restart your download if it has been interrupted. If the kernel has been restarted, but you successfully completed your order, you will need to re-initialize your query class object and can then skip immediately to the download_granules method with restart=True.

See also

query.Query.download_granules

Notes

This function is used by query.Query.download_granules(), which automatically feeds in the required parameters.

get_avail(CMRparams, reqparams, cloud=False)

Get a list of available granules for the query object’s parameters. Generates the avail attribute of the granules object.

Parameters:

CMRparamsdictionary: Dictionary of properly formatted CMR search parameters.
reqparamsdictionary: Dictionary of properly formatted parameters required for searching, ordering, or downloading from NSIDC.
clouddeprecated, boolean, default False: CMR metadata is always collected for the cloud system.

See also

APIformatting.Parameters
query.Query.avail_granules

Notes

This function is used by query.Query.avail_granules(), which automatically feeds in the required parameters.

place_order(CMRparams, reqparams, subsetparams, verbose, subset=True, geom_filepath=None)

Place an order for the available granules for the query object. Adds the list of zipped files (orders) to the granules data object (which is stored as the granules attribute of the query object). You must be logged in to Earthdata to use this function.

Parameters:

CMRparamsdictionary: Dictionary of properly formatted CMR search parameters.
reqparamsdictionary: Dictionary of properly formatted parameters required for searching, ordering, or downloading from NSIDC.
subsetparamsdictionary: Dictionary of properly formatted subsetting parameters. An empty dictionary is passed as input here when subsetting is set to False in query methods.
verboseboolean, default False: Print out all feedback available from the order process. Progress information is automatically printed regardless of the value of verbose.
subsetboolean, default True: Apply subsetting to the data order from the NSIDC, returning only data that meets the subset parameters. Spatial and temporal subsetting based on the input parameters happens by default when subset=True, but additional subsetting options are available. Spatial subsetting returns all data that are within the area of interest (but not complete granules. This eliminates false-positive granules returned by the metadata-level search)
geom_filepathstring, default None: String of the full filename and path when the spatial input is a file.

See also

query.Query.order_granules

Notes

This function is used by query.Query.order_granules(), which automatically feeds in the required parameters.

icepyx.core.granules.gran_IDs(grans, ids=False, cycles=False, tracks=False, dates=False, cloud=False)

Returns a list of granule information for each granule dictionary in the input list of granule dictionaries. Granule info may be from a list of those available from NSIDC (for ordering/download) or a list of granules present on the file system.

Parameters:

granslist of dictionaries: List of input granule json dictionaries. Must have key “producer_granule_id”
ids: boolean, default True: Return a list of the available granule IDs for the granule dictionary
cyclesboolean, default False: Return a list of the available orbital cycles for the granule dictionary
tracksboolean, default False: Return a list of the available Reference Ground Tracks (RGTs) for the granule dictionary
datesboolean, default False: Return a list of the available dates for the granule dictionary.
cloudboolean, default False: Return a a list of AWS s3 urls for the available granules in the granule dictionary.

icepyx.core.granules.info(grans): Return some basic summary information about a set of granules for an query object. Granule info may be from a list of those available from NSIDC (for ordering/download) or a list of granules present on the file system.

is2ref

icepyx.core.is2ref.about_product(prod)

Ping Earthdata to get metadata about the product of interest (the collection).

See also

query.Query.product_all_info

icepyx.core.is2ref.extract_product(filepath, auth=None)

Read the product type from the metadata of the file. Valid for local or s3 files, but must provide an auth object if reading from s3. Return the product as a string.

Parameters:

filepath: string: local or remote location of a file. Could be a local string or an s3 filepath
auth: earthaccess.auth.Auth, default None: An earthaccess authentication object. Optional, but necessary if accessing data in an s3 bucket.

icepyx.core.is2ref.extract_version(filepath, auth=None)

Read the version from the metadata of the file. Valid for local or s3 files, but must provide an auth object if reading from s3. Return the version as a string.

Parameters:

filepath: string: local or remote location of a file. Could be a local string or an s3 filepath
auth: earthaccess.auth.Auth, default None: An earthaccess authentication object. Optional, but necessary if accessing data in an s3 bucket.

icepyx.core.is2ref.gt2spot(gt, sc_orient)

icepyx.core.is2ref.latest_version(product)

Determine the most recent version available for the given product.

Examples

>>> latest_version('ATL03')
'006'

spatial

class icepyx.core.spatial.Spatial(spatial_extent, **kwarg)

Bases: object

property extent

Return the coordinates of the spatial extent of the Spatial object.

The result will be returned as an array. For input geometry files with multiple features, the boundary of the the unary union of all features is returned.

Returns:

spatial extentarray: An array of bounding coordinates.

property extent_as_gdf

Return the spatial extent of the query object as a GeoPandas GeoDataframe.

Returns:

extent_gdfGeoDataframe: A GeoDataframe containing the spatial region of interest.

property extent_file

Return the path to the geospatial polygon file containing the Spatial object’s spatial extent. If the spatial extent did not come from a file (i.e. user entered list of coordinates), this will return None.

Examples

>>> reg_a = Spatial([-55, 68, -48, 71])
>>> reg_a.extent_file

>>> from pathlib import Path
>>> reg_a = Spatial(str(Path('./doc/source/example_notebooks/supporting_files/simple_test_poly.gpkg').resolve()))
>>> reg_a.extent_file 
./doc/source/example_notebooks/supporting_files/simple_test_poly.gpkg

property extent_type

Return the extent type of the Spatial object as a string.

Examples

>>> reg_a = Spatial([-55, 68, -48, 71])
>>> reg_a.extent_type
'bounding_box'

>>> reg_a = Spatial([(-55, 68), (-55, 71), (-48, 71), (-48, 68), (-55, 68)])
>>> reg_a.extent_type
'polygon'

fmt_for_CMR()

Format the spatial extent for NASA’s Common Metadata Repository (CMR) API.

CMR spatial inputs must be formatted a specific way. This method formats the given spatial extent to be a valid submission. For large/complex polygons, this includes simplifying the polygon (NOTE: currently not all polygons are simplified enough). Coordinates will be properly ordered, and the required string formatting applied. For small regions, a buffer may be added.

Returns:

string: Properly formatted string of spatial data for submission to CMR API.

fmt_for_EGI()

Format the spatial extent input into a subsetting key value for submission to EGI (the NSIDC DAAC API).

EGI spatial inputs must be formatted a specific way. This method formats the given spatial extent to be a valid submission. DevGoal: For large/complex polygons, this includes simplifying the polygon. Coordinates will be properly ordered, and the required string formatting applied.

Returns:

string: Properly formatted json string for submission to EGI (NSIDC API).

icepyx.core.spatial.check_dateline(extent_type, spatial_extent)

Check if a bounding box or polygon input cross the dateline.

Parameters:

extent_typestring: One of ‘bounding_box’ or ‘polygon’, indicating what type of input the spatial extent is
spatial_extentlist: A list containing the spatial extent as coordinates in decimal degrees of [longitude1, latitude1, longitude2, latitude2, … longitude_n,latitude_n, longitude1,latitude1].

Returns:

boolean: indicating whether or not the spatial extent crosses the dateline.

icepyx.core.spatial.geodataframe(extent_type, spatial_extent, file=False, xdateline=None)

Return a geodataframe of the spatial extent

Parameters:

extent_typestring

One of ‘bounding_box’ or ‘polygon’, indicating what type of input the spatial extent is

spatial_extentstring or list

A list containing the spatial extent OR a string containing a filename. If file is False, spatial_extent should be a list of coordinates in decimal degrees of [lower-left-longitude, lower-left-latitute, upper-right-longitude, upper-right-latitude] or [longitude1, latitude1, longitude2, latitude2, … longitude_n,latitude_n, longitude1,latitude1].

If file is True, spatial_extent is a string containing the full file path and filename to the file containing the desired spatial extent.

fileboolean, default False

Indication for whether the spatial_extent string is a filename or coordinate list

Returns:

gdfGeoDataFrame: Returns a GeoPandas GeoDataFrame containing the spatial extent. The GeoDataFrame will have only one entry unless a geospatial file was submitted.

See also

icepyx.Query

Examples

>>> reg_a = ipx.Query('ATL06',[-55, 68, -48, 71],['2019-02-20','2019-02-28'])
>>> gdf = geodataframe(reg_a.spatial.extent_type, reg_a.spatial.extent)
>>> gdf.geometry
0    POLYGON ((-48 68, -48 71, -55 71, -55 68, -48 ...
Name: geometry, dtype: geometry

icepyx.core.spatial.validate_bounding_box(spatial_extent)

Validates the spatial_extent parameter as a bounding box.

If the spatial_extent is a valid bounding box, returns a tuple containing the Spatial object parameters for the bounding box; otherwise, throw an error containing the reason the bounding box is invalid.

Parameters:

spatial_extent: list or np.ndarray

A list or np.ndarray of strings, numerics, or tuples representing bounding box coordinates in decimal degrees.

Must be provided in the order: [lower-left-longitude, lower-left-latitude, upper-right-longitude, upper-right-latitude])

icepyx.core.spatial.validate_polygon_file(spatial_extent)

Validates the spatial_extent parameter as a polygon from a file.

If the spatial_extent parameter contains a valid polygon, returns a tuple containing the Spatial object parameters for the polygon;

otherwise, throw an error containing the reason the polygon/polygon file is invalid.

Parameters:

spatial_extent: string

A string representing a geospatial polygon file (kml, shp, gpkg) * must provide full file path * recommended for file to only contain 1 polygon.

if multiple polygons, only the first polygon is selected at this time.

icepyx.core.spatial.validate_polygon_list(spatial_extent)

Validates the spatial_extent parameter as a polygon from a list of coordinates.

If the spatial_extent is a valid polygon, returns a tuple containing the Spatial object parameters for the polygon;

otherwise, throw an error containing the reason the polygon is invalid.

Parameters:

spatial_extent: list or np.ndarray

A list or np.ndarray of strings, numerics, or tuples representing polygon coordinates, provided as coordinate pairs in decimal degrees in the order: [longitude1, latitude1, longitude2, latitude2, … … longitude_n,latitude_n, longitude1,latitude1]

If the first and last coordinate pairs are NOT equal, the polygon will be closed automatically (last point will be connected to the first point).

icepyx.core.spatial.validate_polygon_pairs(spatial_extent)

Validates the spatial_extent parameter as a polygon from coordinate pairs.

If the spatial_extent is a valid polygon, returns a tuple containing the Spatial object parameters for the polygon;

otherwise, throw an error containing the reason the polygon is invalid.

Parameters:

spatial_extent: list or np.ndarray

A list or np.ndarray of tuples representing polygon coordinate pairs in decimal degrees in the order: [(longitude1, latitude1), (longitude2, latitude2), … … (longitude_n,latitude_n), (longitude1,latitude1)]

If the first and last coordinate pairs are NOT equal, the polygon will be closed automatically (last point will be connected to the first point).

temporal

class icepyx.core.temporal.Temporal(date_range, start_time=None, end_time=None)

Bases: object

property end

Return the end date and time of the Temporal object as a datetime.datetime object.

Examples

>>> tmp_a = Temporal(["2016-01-01", "2020-01-01"])
>>> tmp_a.end
datetime.datetime(2020, 1, 1, 23, 59, 59)

property start

Return the start date and time of the Temporal object as a datetime.datetime object.

Examples

>>> tmp_a = Temporal(["2016-01-01", "2020-01-01"])
>>> tmp_a.start
datetime.datetime(2016, 1, 1, 0, 0)

icepyx.core.temporal.check_valid_date_range(start, end)

Helper function for checking if a date range is valid.

AssertionError is raised if the start date is later than the end date.

Parameters:

start: datetime.datetime, datetime.date: Starting date of date range to check.
end: datetime.datetime, datetime.date: Ending date of date range to check

Returns:

boolean (true if date range is valid, false otherwise)

Examples

>>> start = dt.datetime.strptime("2016-01-01", "%Y-%m-%d")
>>> end = dt.datetime.strptime("2020-01-01", "%Y-%m-%d")
>>> drange = check_valid_date_range(start, end)
>>> drange

>>> drange = check_valid_date_range(end, start) 
AssertionError: Your date range is invalid; end date MUST be on or after the start date.

icepyx.core.temporal.convert_string_to_date(date)

Converts a string to a datetime object. Throws an error if an invalid format is passed in.

Parameters:

date: string

A string representation for the date value. Current supported date formats are:

“YYYY-MM-DD”
“YYYY-DOY”

Returns:

datetime.date object, representing the date from the string parameter.

Examples

>>> mmdd = "2016-01-01"
>>> converted = convert_string_to_date(mmdd)
>>> converted
datetime.date(2016, 1, 1)

>>> doy = "2020-40"
>>> converted = convert_string_to_date(doy)
>>> converted
datetime.date(2020, 2, 9)

icepyx.core.temporal.validate_date_range_date(date_range, start_time=None, end_time=None)

Validates a date range provided in the form of a list of datetime.date objects.

Combines the start and end dates with their respective start and end times to create complete start and end datetime.datetime objects.

Parameters:

date_range: list(str): A date range provided in the form of a list of datetime.dates. List must be of length 2.
start_time: string or datetime.time
end_time: string or datetime.time

Returns:

Start and end datetimes as datetime.datetime objects

Examples

>>> drange = [dt.date(2016, 1, 1), dt.date(2020, 1, 1)]
>>> valid_drange = validate_date_range_date(drange, "00:10:00", "21:00:59")
>>> valid_drange
(datetime.datetime(2016, 1, 1, 0, 10), datetime.datetime(2020, 1, 1, 21, 0, 59))

icepyx.core.temporal.validate_date_range_datestr(date_range, start_time=None, end_time=None)

Validates a date range provided in the form of a list of strings.

Combines the start and end dates with their respective start and end times to create complete start and end datetime.datetime objects.

Parameters:

date_range: list(str)

A date range provided in the form of a list of strings: Strings must be of formats accepted by validate_inputs_temporal.convert_string_to_date(). List must be of length 2.

start_time: string, datetime.time, None

end_time: string, datetime.time, None

Returns:

Start and end dates and times as datetime.datetime objects

Examples

>>> daterange = validate_date_range_datestr(["2016-01-01", "2020-01-01"])
>>> daterange
(datetime.datetime(2016, 1, 1, 0, 0), datetime.datetime(2020, 1, 1, 23, 59, 59))

icepyx.core.temporal.validate_date_range_datetime(date_range, start_time=None, end_time=None)

Validates a date range provided in the form of a list of datetimes.

Parameters:

date_range: list(datetime.datetime): A date range provided in the form of a list of datetimes. List must be of length 2.
start_time: None, string, datetime.time
end_time: None, string, datetime.time
NOTE: If start and/or end times are given,
they will be **ignored in favor of the time from the start/end datetime.datetime objects.**

Returns:

Start and end dates and times as datetime.datetime objects

Examples

>>> drange = [dt.datetime(2016, 1, 14, 1, 0, 0), dt.datetime(2020, 2, 9, 13, 10, 1)]
>>> valid_drange = validate_date_range_datetime(drange)
>>> valid_drange
(datetime.datetime(2016, 1, 14, 1, 0), datetime.datetime(2020, 2, 9, 13, 10, 1))

icepyx.core.temporal.validate_date_range_dict(date_range, start_time=None, end_time=None)

Validates a date range provided in the form of a dict with the following keys:

Parameters:

date_range: dict(str, datetime.datetime, datetime.date)

A date range provided in the form of a dict. date_range must contain only the following keys:

start_date: start date, type can be of dt.datetime, dt.date, or string

end_date: end date, type can be of dt.datetime, dt.date, or string

Keys MUST have the exact names/formatting above or a ValueError will be thrown by this function.

If the values are of type dt.datetime and were created without times, the datetime package defaults of all 0s are used and the start_time/end_time parameters will be ignored!

start_time: string or datetime.time

end_time: string or datetime.time

Returns:

Start and end datetimes as datetime.datetime objects
(by combining the start/end dates with their respective start/end times, if the dict type is not datetime)

Examples

>>> drange = {"start_date": "2016-01-01", "end_date": "2020-01-01"}
>>> valid_drange = validate_date_range_dict(drange, "00:00:00", "23:59:59")
>>> valid_drange
(datetime.datetime(2016, 1, 1, 0, 0), datetime.datetime(2020, 1, 1, 23, 59, 59))

icepyx.core.temporal.validate_times(start_time, end_time)

Validates the start and end times passed into __init__ and returns them as datetime.time objects.

NOTE: If start and/or end times are not provided (are of type None), the defaults are 00:00:00 and 23:59:59, respectively.

Parameters:

start_time: string, datetime.time, None
end_time: string, datetime.time, None

Returns:

start_time, end_time as datetime.time objects

Examples

>>> val_time = validate_times("00:00:00", "23:59:59")
>>> val_time
(datetime.time(0, 0), datetime.time(23, 59, 59))

validate_inputs

icepyx.core.validate_inputs.check_s3bucket(path): Check if the given path is an s3 path. Raise a warning if the data being referenced is not in the NSIDC bucket

icepyx.core.validate_inputs.cycles(cycle): Check if the submitted cycle is valid, and warn the user if not available.

icepyx.core.validate_inputs.prod_version(latest_vers, version): Check if the submitted product version is valid, and warn the user if a newer version is available.

icepyx.core.validate_inputs.tracks(track): Check if the submitted RGT is valid, and warn the user if not available.

visualize

Interactive visualization of spatial extent and ICESat-2 elevations

class icepyx.core.visualization.Visualize(query_obj=None, product=None, spatial_extent=None, date_range=None, cycles=None, tracks=None)

Bases: object

Object class to quickly visualize elevation data for select ICESat-2 products (ATL06, ATL07, ATL08, ATL10, ATL12, ATL13) based on the query parameters defined by the icepyx Query object. Provides interactive maps that show product elevation on a satellite basemap.

Parameters:

query_objipx.Query object, default None: icepy Query class object.
productstring: ICESat-2 product ID
spatial_extent: list or string, default None: as in the ipx.Query object
date_rangelist of ‘YYYY-MM-DD’ strings, default None: as in the ipx.Query object
cyclestring, default all available orbital cycles, default None: as in the ipx.Query object
trackstring, default all available reference ground tracks (RGTs), default None: as in the ipx.Query object

See also

ipx.Query

generate_OA_parameters() → list

Get metadata from file lists in each 5*5 bounding box.

Returns:

paras_listlist: A list of parameters for OpenAltimetry API query, including the reference ground track (RGT), cycle number, datetime, bounding box, and product name.

grid_bbox(binsize=5) → list

Split bounding box into 5 x 5 grids when latitude/longitude range exceeds the default OpenAltimetry 5*5 degree spatial limits

Returns:

bbox_listlist: A list of bounding boxes with a maximum size of 5*5 degree

make_request(base_url, payload)

Make HTTP request

Parameters:

base_urlstring: OpenAltimetry URL

See also

request_OA_data

parallel_request_OA() → array

Requests elevation data from OpenAltimetry API in parallel. Currently supports OA_Products [‘ATL06’,’ATL07’,’ATL08’,’ATL10’,’ATL12’,’ATL13’]

For ATL03 Photon Data, OA only supports single date request according to: https://openaltimetry.org/data/swagger-ui/#/Public/getATL08DataByDate, with geospatial limitation of 1 degree lat/lon. Visualization of ATL03 data is not implemented within this module at this time.

Returns:

OA_data_dadask.Array: A dask array containing the ICESat-2 data.

query_icesat2_filelist() → tuple

Query list of ICESat-2 files for each bounding box

Returns:

filelist_tupletuple: A tuple of non-empty lists of bounding boxes and corresponding ICESat-2 file lists

request_OA_data(paras) → array

Request data from OpenAltimetry based on API: https://openaltimetry.org/data/swagger-ui/#/

Parameters:

paraslist: A single parameter list for an OpenAltimetry API data request.

Returns:

OA_darrda.array: A dask array containing the ICESat-2 elevation data.

viz_elevation() -> (<class 'holoviews.core.spaces.DynamicMap'>, <class 'holoviews.core.layout.Layout'>)

Visualize elevation requested from OpenAltimetry API using datashader based on cycles https://holoviz.org/tutorial/Large_Data.html

Returns:

map_cycle, map_rgt + lineplot_rgtHoloviews objects: Holoviews data visualization elements

icepyx.core.visualization.files_in_latest_n_cycles(files, cycles, n=1) → list

Get list of file names from latest n ICESat-2 cycles

Parameters:

fileslist: A list of file names.
cycles: list: A list of available ICESat-2 cycles
n: int, default 1: Number of latest ICESat-2 cycles to pick

Returns:

viz_file_listlist: A list of file names from latest n ICESat-2 cycles

icepyx.core.visualization.gran_paras(filename) → list

Returns a list of granule information for file name string.

Parameters:

filename: String: ICESat-2 file name

Returns:

gran_paras_listlist: A list of parameters including RGT, cycle, and datetime of ICESat-2 data granule

icepyx.core.visualization.user_check(message)

Check if user wants to proceed visualization when the API request number exceeds 200

Parameters:

messagestring: Message to indicate users the options