icepyx.Query¶

class icepyx.Query(dataset=None, spatial_extent=None, date_range=None, start_time=None, end_time=None, version=None, cycles=None, tracks=None, orbit_number=None, files=None)¶

ICESat-2 Data object to query, obtain, and perform basic operations on available ICESat-2 datasets using temporal and spatial input parameters. Allows the easy input and formatting of search parameters to match the NASA NSIDC DAAC and (development goal-not yet implemented) conversion to multiple data types.

Parameters

datasetstring: ICESat-2 dataset ID, also known as “short name” (e.g. ATL03). Available datasets can be found at: https://nsidc.org/data/icesat-2/data-sets
spatial_extentlist or string: Spatial extent of interest, provided as a bounding box, list of polygon coordinates, or geospatial polygon file. Bounding box coordinates should be provided in decimal degrees as [lower-left-longitude, lower-left-latitute, upper-right-longitude, upper-right-latitude]. Polygon coordinates should be provided as coordinate pairs in decimal degrees as [(longitude1, latitude1), (longitude2, latitude2), … (longitude_n,latitude_n), (longitude1,latitude1)] or [longitude1, latitude1, longitude2, latitude2, … longitude_n,latitude_n, longitude1,latitude1]. Your list must contain at least four points, where the first and last are identical. DevGoal: adapt code so the polygon is automatically closed if need be Geospatial polygon files are entered as strings with the full file path and must contain only one polygon with the area of interest. Currently supported formats are: kml, shp, and gpkg
date_rangelist of ‘YYYY-MM-DD’ strings: Date range of interest, provided as start and end dates, inclusive. The required date format is ‘YYYY-MM-DD’ strings, where YYYY = 4 digit year, MM = 2 digit month, DD = 2 digit day. Currently, a list of specific dates (rather than a range) is not accepted. DevGoal: accept date-time objects, dicts (with ‘start_date’ and ‘end_date’ keys, and DOY inputs). DevGoal: allow searches with a list of dates, rather than a range.
start_timeHH:mm:ss, default 00:00:00: Start time in UTC/Zulu (24 hour clock). If None, use default. DevGoal: check for time in date-range date-time object, if that’s used for input.
end_timeHH:mm:ss, default 23:59:59: End time in UTC/Zulu (24 hour clock). If None, use default. DevGoal: check for time in date-range date-time object, if that’s used for input.
versionstring, default most recent version: Dataset version, given as a 3 digit string. If no version is given, the current version is used.
cyclestring, default all available orbital cycles: Dataset cycle, given as a 2 digit string. If no cycle is given, all available cycles are used.
trackstring, default all available reference ground tracks (RGTs): Dataset track, given as a 4 digit string. If no track is given, all available reference ground tracks are used.

Returns

query object

Examples

Initializing Query with a bounding box.

>>> reg_a_bbox = [-55, 68, -48, 71]
>>> reg_a_dates = ['2019-02-20','2019-02-28']
>>> reg_a = icepyx.query.Query('ATL06', reg_a_bbox, reg_a_dates)
>>> reg_a
<icepyx.core.query.Query at [location]>

Initializing Query with a list of polygon vertex coordinate pairs.

>>> reg_a_poly = [(-55, 68), (-55, 71), (-48, 71), (-48, 68), (-55, 68)]
>>> reg_a_dates = ['2019-02-20','2019-02-28']
>>> reg_a = icepyx.query.Query('ATL06', reg_a_poly, reg_a_dates)
>>> reg_a
<icepyx.core.query.Query at [location]>

Initializing Query with a geospatial polygon file.

>>> aoi = '/User/name/location/aoi.shp'
>>> reg_a_dates = ['2019-02-22','2019-02-28']
>>> reg_a = icepyx.query.Query('ATL06', aoi, reg_a_dates)
>>> reg_a
<icepyx.core.query.Query at [location]>

__init__(dataset=None, spatial_extent=None, date_range=None, start_time=None, end_time=None, version=None, cycles=None, tracks=None, orbit_number=None, files=None)¶: Initialize self. See help(type(self)) for accurate signature.

Methods

`__init__`([dataset, spatial_extent, …])	Initialize self.
`avail_granules`([ids, cycles, tracks])	Obtain information about the available granules for the query object’s parameters.
`dataset_all_info`()	Display all metadata about the dataset of interest (the collection).
`dataset_summary_info`()	Display a summary of selected metadata for the specified version of the dataset of interest (the collection).
`download_granules`(path[, verbose, subset, …])	Downloads the data ordered using order_granules.
`earthdata_login`(uid, email)	Log in to NSIDC EarthData to access data.
`latest_version`()	Determine the most recent version available for the given dataset.
`order_granules`([verbose, subset, email])	Place an order for the available granules for the query object.
`show_custom_options`([dictview])	Display customization/subsetting options available for this dataset.
`subsetparams`(**kwargs)	Display the subsetting key:value pairs that will be submitted.
`visualize_spatial_extent`()	Creates a map displaying the input spatial extent

Attributes

`CMRparams`	Display the CMR key:value pairs that will be submitted.
`cycles`	Return the unique ICESat-2 orbital cycle.
`dataset`	Return the short name dataset ID string associated with the query object.
`dataset_version`	Return the dataset version of the data object.
`dates`	Return an array showing the date range of the query object.
`end_time`	Return the end time specified for the end date.
`file_vars`	Return the file variables object.
`granules`	Return the granules object, which provides the underlying funtionality for searching, ordering, and downloading granules for the specified dataset.
`orbit_number`	Return the ICESat-2 CMR orbit number
`order_vars`	Return the order variables object.
`reqparams`	Display the required key:value pairs that will be submitted.
`spatial_extent`	Return an array showing the spatial extent of the query object.
`start_time`	Return the start time specified for the start date.
`tracks`	Return the unique ICESat-2 Reference Ground Tracks