Query 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: dataset, version, start, end, extent_type, spatial_extent Keyword argument inputs for ‘required’ may include: page_size, page_num, request_mode, include_meta 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 formated 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.

Parameters

paramsdictionaries: Unlimited number of dictionaries to combine

Returns

single dictionary of all input dictionaries combined

Examples

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

Earthdata¶

class icepyx.core.Earthdata.Earthdata(uid, email, capability_url, pswd=None)¶

Bases: object

Initiate an Earthdata session for interacting with the NSIDC DAAC.

Parameters

uidstring: Earthdata Login user name (user ID).
emailstring: Complete email address, provided as a string.
passwordstring (encrypted): Password for Earthdata registration associated with the uid.
capability_urlstring: URL required to access Earthdata

Returns

Earthdata session object after a successful login

login()¶

This function tries to log the user in to Earthdata with the information provided. It prompts the user for their Earthdata password, but will only store that information within the active session. If the login fails, it will ask the user to re-enter their username and password up to five times to try and log in.

Alternatively, you can create a .netrc file in your $HOME directory with the following line:

machine urs.earthdata.nasa.gov login <uid> password <password>

Where <uid> is your NASA Earthdata user ID and <password> is your password Then change the permissions of that file to 600 This will allow you to have read and write access to the file No other user can access the file

$ chmod 600 ~/.netrc

The function checks for this file to retrieve credentials, prior to prompting for manual input.

Examples

>>> icepyx.core.Earthdata.Earthdata.login('sam.smith','sam.smith@domain.com')
Earthdata Login password:  ········

geospatial¶

icepyx.core.geospatial.geodataframe(extent_type, spatial_extent, file=False)¶

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: A string of the spatial extent. If file is False, the string 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, the string is 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

See also

icepyx.Query

Examples

>>> reg_a = icepyx.Query('ATL06',[-55, 68, -48, 71],['2019-02-20','2019-02-28'])
>>> gdf = geospatial.geodataframe(reg_a.extent_type, reg_a._spat_extent)
>>> gdf.geometry
0    POLYGON ((-55.00000 68.00000, -55.00000 71.000...
Name: geometry, dtype: geometry

granules¶

class icepyx.core.granules.Granules¶

Bases: object

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, session=None, 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.
sessionrequests.session object: A session object authenticating the user to download data using their Earthdata login information. The session object will automatically be passed from the query object if you have successfully logged in there.
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 log in to Earthdata 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)¶

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.

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, session=None, 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)
sessionrequests.session object: A session object authenticating the user to order data using their Earthdata login information. The session object will automatically be passed from the query object if you have successfully logged in there.
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=True, cycles=False, tracks=False)¶

Returns a list of granule information for the granule dictionary. 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

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 Fal: Return a list of the available Reference Ground Tracks (RGTs) for 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_dataset(dset)¶

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

See also

query.Query.dataset_all_info

validate_inputs¶

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

icepyx.core.validate_inputs.dset_version(latest_vers, version)¶: Check if the submitted dataset version is valid, and warn the user if a newer version is available.

icepyx.core.validate_inputs.spatial(spatial_extent)¶: Validate the input spatial extent and return the needed parameters to the query object.

icepyx.core.validate_inputs.temporal(date_range, start_time, end_time)¶: Validate the input temporal parameters and return the needed parameters to the query object.

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

variables¶

class icepyx.core.variables.Variables(vartype, avail=None, wanted=None, session=None, dataset=None, version=None, source=None)¶

Bases: object

Get, create, interact, and manipulate lists of variables and variable paths contained in ICESat-2 datasets.

Parameters

vartypestring: One of [‘order’, ‘file’] to indicate the source of the input variables. This field will be auto-populated when a variable object is created as an attribute of a query object.
availdictionary, default None: Dictionary (key:values) of available variable names (keys) and paths (values).
wanteddictionary, default None: As avail, but for the desired list of variables
sessionrequests.session object: A session object authenticating the user to download data using their Earthdata login information. The session object will automatically be passed from the query object if you have successfully logged in there.
datasetstring, default None: Properly formatted string specifying a valid ICESat-2 dataset
versionstring, default None: Properly formatted string specifying a valid version of the ICESat-2 dataset
sourcestring, default None: For vartype file, a path to a directory or single input source files (not yet implemented)

append(defaults=False, var_list=None, beam_list=None, keyword_list=None)¶

Add to the list of desired variables using user specified beams and variable list. A pregenerated default variable list can be used by setting defaults to True. Note: The calibrated backscatter cab_prof is not in the default list for ATL09

Parameters

defaultsboolean, default False: Include the variables in the default variable list. Defaults are defined per-data product. When specified in conjuction with a var_list, default variables not on the user- specified list will be added to the order.
var_listlist of strings, default None: A list of variables to request, if not all available variables are wanted. A list of available variables can be obtained by entering var_list=[‘’] into the function.
beam_listlist of strings, default None: A list of beam strings, if only selected beams are wanted (the default value of None will automatically include all beams). For ATL09, acceptable values are [‘profile_1’, ‘profile_2’, ‘profile_3’]. For all other datasets, acceptable values are [‘gt1l’, ‘gt1r’, ‘gt2l’, ‘gt2r’, ‘gt3l’, ‘gt3r’].
keyword_listlist of strings, default None: A list of subdirectory names (keywords), from any heirarchy level within the data structure, to select variables within the dataset that include that keyword in their path. A list of availble keywords can be obtained by entering keyword_list=[‘’] into the function.

Notes

See also the ICESat-2_DAAC_DataAccess2_Subsetting example notebook

Examples

>>> reg_a = icepyx.query.Query('ATL06',[-55, 68, -48, 71],['2019-02-20','2019-02-28'])
>>> reg_a.earthdata_login(user_id,user_email)
Earthdata Login password:  ········

To add all variables related to a specific ICESat-2 beam

>>> reg_a.order_vars.append(beam_list=['gt1r'])

To include the default variables:

>>> reg_a.order_vars.append(defaults=True)

To add specific variables in orbit_info

>>> reg_a.order_vars.append(keyword_list=['orbit_info'],var_list=['sc_orient_time'])

To add all variables and paths in ancillary_data

>>> reg_a.order_vars.append(keyword_list=['ancillary_data'])

avail(options=False, internal=False)¶

Get the list of available variables and variable paths from the input dataset

[‘ancillary_data/atlas_sdp_gps_epoch’,: ‘ancillary_data/control’, ‘ancillary_data/data_end_utc’, ‘ancillary_data/data_start_utc’, . . . ‘quality_assessment/gt3r/signal_selection_source_fraction_3’]

static parse_var_list(varlist)¶: Parse a list of path strings into tiered lists and names of variables

‘geophysical’, ‘ground_track’, ‘gt1l’, ‘gt1r’, ‘gt2l’, ‘gt2r’, ‘gt3l’, ‘gt3r’, ‘land_ice’, ‘land_ice_segments’, ‘none’, ‘orbit_info’, ‘quality_assessment’, ‘residual_histogram’, ‘segment_quality’, ‘signal_selection_status’], dtype=’<U23’)

remove(all=False, var_list=None, beam_list=None, keyword_list=None)¶

Remove the variables and paths from the wanted list using user specified beam, keyword,: and variable lists.

Notes

See also the ICESat-2_DAAC_DataAccess2_Subsetting example notebook

Examples

>>> reg_a = icepyx.query.Query('ATL06',[-55, 68, -48, 71],['2019-02-20','2019-02-28'])
>>> reg_a.earthdata_login(user_id,user_email)
Earthdata Login password:  ········

To clear the list of wanted variables

>>> reg_a.order_vars.remove(all=True)

To remove all variables related to a specific ICESat-2 beam

>>> reg_a.order_vars.remove(beam_list=['gt1r'])

To remove specific variables in orbit_info

>>> reg_a.order_vars.remove(keyword_list=['orbit_info'],var_list=['sc_orient_time'])

To remove all variables and paths in ancillary_data

>>> reg_a.order_vars.remove(keyword_list=['ancillary_data'])