Components

APIformatting

Generate and format information for submitting to API (CMR and NSIDC).

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

Bases: Generic[T]

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

Parameters:

• partype (str) – Type of parameter list. Must be one of [‘CMR’,’required’,’subset’]

• values (dict, default None) – Dictionary of already-formatted parameters, if there are any, to avoid re-creating them.

• reqtype (str, 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

Return type:

None

check_req_values()

Check that all of the required keys have values, if the key was passed in with the values parameter.

Return type:

bool

check_values()

Check that the non-required keys have values, if the key was passed in with the values parameter.

Return type:

bool

fmted_keys

Enable the Parameters class’ fmted_keys property to be typechecked correctly.

See: https://github.com/microsoft/pyright/issues/3071#issuecomment-1043978070

partype: T

property poss_keys: dict[str, list[str]]

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:

params (dictionaries) – Unlimited number of dictionaries to combine

Return type:

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:

params (dict)

Return type:

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:

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

2. Entering credentials interactively

3. 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 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:

auth (earthaccess.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.

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.

Return type:

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:

• verbose (bool, default False) – Print out all feedback available from the order process. Progress information is automatically printed regardless of the value of verbose.

• path (str) – String with complete path to desired download directory and location.

• restart (bool, 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.

Notes

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

See also

query.Query.download_granules

get_avail(CMRparams, cloud=False)

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

Parameters:

• CMRparams (CMRParamsWithBbox | CMRParamsWithPolygon) – Dictionary of properly formatted CMR search parameters.

• cloud (bool, default: False) –

  CMR metadata is always collected for the cloud system.

  Deprecated since version 1.2: This parameter is ignored.

Notes

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

See also

APIformatting.Parameters, query.Query.avail_granules

place_order(CMRparams, 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:

• CMRparams (CMRParamsWithBbox | CMRParamsWithPolygon) – Dictionary of properly formatted CMR search parameters.

• subsetparams (dict) – Dictionary of properly formatted subsetting parameters. An empty dictionary is passed as input here when subsetting is set to False in query methods.

• verbose (bool, default False) – Print out all feedback available from the order process. Progress information is automatically printed regardless of the value of verbose.

• subset (bool, 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_filepath (str, default None) – String of the full filename and path when the spatial input is a file.

Notes

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

See also

query.Query.order_granules

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:

• grans (list of dictionaries) – List of input granule json dictionaries. Must have key “producer_granule_id”

• ids (bool, default True) – Return a list of the available granule IDs for the granule dictionary

• cycles (bool, default False) – Return a list of the available orbital cycles for the granule dictionary

• tracks (bool, default False) – Return a list of the available Reference Ground Tracks (RGTs) for the granule dictionary

• dates (bool, default False) – Return a list of the available dates for the granule dictionary.

• cloud (bool, 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.

harmony

class icepyx.core.harmony.HarmonyApi

Bases: EarthdataAuthMixin

A client for interacting with the NASA Harmony API.

harmony_client

The Harmony API client.

Type:

harmony.Client

job_ids

List of job IDs that have been placed with the Harmony API.

Type:

list[str]

check_order_status(job_id)

Check the status of a submitted Harmony job.

Parameters:

job_id (str)

Return type:

dict[str, Any]

download_granules(download_dir, overwrite=False)

Download all granules associated with current order.

This method retrieves and downloads granules for all job IDs stored in self.job_ids, saving them to the specified directory.

Parameters:

• download_dir (Path) – The directory where granules should be saved.

• overwrite (bool, optional) – Whether to overwrite existing files (default is False).

Returns:

A list of file paths to the downloaded granules.

Return type:

list of Path

get_capabilities(concept_id)

Retrieve the capabilities of a dataset given its concept ID.

Parameters:

concept_id (str) – The concept ID of the dataset.

Returns:

A dictionary containing dataset capabilities.

Return type:

dict

pause_order(job_id)

Pauses an order that is currently processing.

Parameters:

job_id (str) – The ID of the Harmony job to resume.

Returns:

A dictionary containing the order status and related metadata.

Return type:

dict

place_order(concept_id, spatial=None, temporal=None, shape=None, granule_name=[], skip_preview=False)

Submit an order to Harmony and wait for it to complete.

Parameters:

• concept_id (str) – The concept ID of the dataset.

• spatial (harmony.BBox, str, harmony.request.WKT, or None, optional) – The spatial extent for the order.

• temporal (HarmonyTemporal or None, optional) – The temporal range for the order.

• shape (str or None, optional) – A spatial shape file for filtering.

• granule_name (list[str], optional) – Specific granule names to include in the order.

• skip_preview (bool, optional) – Whether to bypass preview mode if the order exceeds 300 granules.

Returns:

The Harmony job ID.

Return type:

str

resume_order(job_id)

Resume processing of an order that is paused.

Parameters:

job_id (str) – The ID of the Harmony job to resume.

Returns:

A dictionary containing the order status and related metadata.

Return type:

dict

skip_preview(job_id)

Resume processing of an order that is in the “PREVIEW” state.

If a subsetting order exceeds 300 granules, Harmony places it in a paused state called “preview,” where only a few granules are processed initially. This method resumes processing by first pausing and then resuming the order.

Parameters:

job_id (str) – The ID of the Harmony job to resume.

Returns:

A dictionary containing the order status and related metadata.

Return type:

dict

class icepyx.core.harmony.HarmonyTemporal

Bases: TypedDict

start: datetime

stop: datetime

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 (str) – 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 (str) – 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')
'007'

orders

class icepyx.core.orders.DataOrder(job_id, type, granules, harmony_client)

Bases: object

A class representing an order for Harmony data processing.

Parameters:

• job_id (str)

• type (str)

• granules (List[Any] | Granules)

• harmony_client (Any)

job_id

The ID of the Harmony job.

Type:

str

Return type:

str

type

The type of order (e.g., “subset”).

Type:

str

granules

A list of granules included in the order.

Type:

list

harmony_client

The Harmony API client used for interacting with the service.

Type:

object

HARMONY_BASE_URL = 'https://harmony.earthdata.nasa.gov/workflow-ui/'

download(path, overwrite=False)

Download the granules for the order, blocking until they are ready if necessary.

Parameters:

• path (str or Path) – The directory where granules should be saved.

• overwrite (bool, optional) – Whether to overwrite existing files (default is False).

Returns:

A list of downloaded granules

Return type:

list or None

download_granules(path, overwrite=False)

Download the granules for the order.

Parameters:

• path (str or Path) – The directory where granules should be saved.

• overwrite (bool, optional) – Whether to overwrite existing files (default is False).

Returns:

A list of downloaded granules

Return type:

list or None

job_id()

Get the job ID of the order.

Returns:

The Harmony job ID.

Return type:

str

pause()

Pause the order.

Returns:

The response from the Harmony API if the order is paused, otherwise None.

Return type:

dict or None

resume()

Resume the order if it has been paused or is on a “preview” state.

Returns:

The response from the Harmony API if the order is resumed, otherwise None.

Return type:

dict or None

skip_preview()

Resume the order if it has been paused due to exceeding granule limits.

Returns:

The response from the Harmony API if the order is resumed, otherwise None.

Return type:

dict or None

status()

Retrieve the status of the order.

Returns:

A dictionary containing the order status and related metadata.

Return type:

dict

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 extent – An array of bounding coordinates.

Return type:

array

property extent_as_gdf

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

Returns:

extent_gdf – A GeoDataframe containing the spatial region of interest.

Return type:

geopandas.GeoDataFrame

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:

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

Return type:

string

fmt_for_EGI()

WARNING: This method is deprecated. Use fmt_for_CMR instead. 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:

Properly formatted json string for submission to CMR

Return type:

string

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

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

Parameters:

• extent_type (str) – One of ‘bounding_box’ or ‘polygon’, indicating what type of input the spatial extent is

• spatial_extent (list) – A list containing the spatial extent as coordinates in decimal degrees of [longitude1, latitude1, longitude2, latitude2, … longitude_n,latitude_n, longitude1,latitude1].

Returns:

indicating whether or not the spatial extent crosses the dateline.

Return type:

boolean

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

Return a geodataframe of the spatial extent

Parameters:

• extent_type (str) – One of ‘bounding_box’ or ‘polygon’, indicating what type of input the spatial extent is

• spatial_extent (str 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-latitude, 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.

• file (bool, default False) – Indication for whether the spatial_extent string is a filename or coordinate list

Returns:

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

Return type:

geopandas.GeoDataFrame

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 (str) –

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

Parameters:

• date_range (list | dict)

• start_time (str | time | None)

• end_time (str | time | None)

property end: datetime

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: datetime

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

Return type:

bool (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 (str) –

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

• ”YYYY-MM-DD”

• ”YYYY-DOY”

Return type:

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[date]) – A date range provided in the form of a list of datetime.dates. List must be of length 2.

• start_time (str | time | None)

• end_time (str | time | None)

Return type:

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 (str | time | None)

• end_time (str | time | None)

Return type:

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]) – A date range provided in the form of a list of datetimes. List must be of length 2.

• NOTE (If start and/or end times are given,)

• objects. (they will be ignored in favor of the time from the start/end datetime.datetime)

• start_time (str | time | None)

• end_time (str | time | None)

Return type:

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, str | 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 (str | time | None)

• end_time (str | time | None)

Return type:

tuple[datetime, datetime]

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 (str, datetime.time, None)

• end_time (string, datetime.time, None)

Return type:

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_obj (icepyx.Query, default None) – icepy Query class object.

• product (str) – ICESat-2 product ID

• spatial_extent (list or str, default None) – as in the icepyx.Query object

• date_range (list of 'YYYY-MM-DD' strings, default None) – as in the icepyx.Query object

• cycle (str, default all available orbital cycles, default None) – as in the icepyx.Query object

• track (str, default all available reference ground tracks (RGTs), default None) – as in the icepyx.Query object

See also

icepyx.Query

generate_OA_parameters()

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

Returns:

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

Return type:

list

grid_bbox(binsize=5)

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

Returns:

bbox_list – A list of bounding boxes with a maximum size of 5*5 degree

Return type:

list

make_request(base_url, payload)

Make HTTP request

Parameters:

base_url (str) – OpenAltimetry URL

See also

request_OA_data

parallel_request_OA()

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_da – A dask array containing the ICESat-2 data.

Return type:

dask.Array

query_icesat2_filelist()

Query list of ICESat-2 files for each bounding box

Returns:

filelist_tuple – A tuple of non-empty lists of bounding boxes and corresponding ICESat-2 file lists

Return type:

tuple

request_OA_data(paras)

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

Parameters:

paras (list) – A single parameter list for an OpenAltimetry API data request.

Returns:

OA_darr – A dask array containing the ICESat-2 elevation data.

Return type:

da.array

viz_elevation()

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

Returns:

map_cycle, map_rgt + lineplot_rgt – Holoviews data visualization elements

Return type:

Holoviews objects

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

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

Parameters:

• files (list) – 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_list – A list of file names from latest n ICESat-2 cycles

Return type:

list

icepyx.core.visualization.gran_paras(filename)

Returns a list of granule information for file name string.

Parameters:

filename (str) – ICESat-2 file name

Returns:

gran_paras_list – A list of parameters including RGT, cycle, and datetime of ICESat-2 data granule

Return type:

list

icepyx.core.visualization.user_check(message)

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

Parameters:

message (str) – Message to indicate users the options