icepyx.GenQuery

class icepyx.GenQuery(spatial_extent=None, date_range=None, start_time=None, end_time=None, **kwargs)

Base class for querying data.

Generic components of query object that specifically handles spatio-temporal constraints applicable to all datasets. Extended by Query (ICESat-2) and Quest (other products).

Parameters:

spatial_extentlist of coordinates or string (i.e. file name)

Spatial extent of interest, provided as a bounding box, list of polygon coordinates, or geospatial polygon file. NOTE: Longitude values are assumed to be in the range -180 to +180, with 0 being the Prime Meridian (Greenwich). See xdateline for regions crossing the date line. You can submit at most one bounding box or list of polygon coordinates. Per NSIDC requirements, geospatial polygon files may only contain one feature (polygon). 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. 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 or dict, as follows

Date range of interest, provided as start and end dates, inclusive. Accepted input date formats are:

YYYY-MM-DD string

YYYY-DOY string

datetime.date object (if times are included)

datetime.datetime objects (if no times are included)

where YYYY = 4 digit year, MM = 2 digit month, DD = 2 digit day, DOY = 3 digit day of year. Date inputs are accepted as a list or dictionary with start_date and end_date keys. Currently, a list of specific dates (rather than a range) is not accepted. TODO: allow searches with a list of dates, rather than a range.

start_timestr, datetime.time, default None

Start time in UTC/Zulu (24 hour clock). Input types are an HH:mm:ss string or datetime.time object where HH = hours, mm = minutes, ss = seconds. If None is given (and a datetime.datetime object is not supplied for date_range), a default of 00:00:00 is applied.

end_timestr, datetime.time, default None

End time in UTC/Zulu (24 hour clock). Input types are an HH:mm:ss string or datetime.time object where HH = hours, mm = minutes, ss = seconds. If None is given (and a datetime.datetime object is not supplied for date_range), a default of 23:59:59 is applied. If a datetime.datetime object was created without times, the datetime package defaults will apply over those of icepyx

xdatelineboolean, default None

Keyword argument to enforce spatial inputs that cross the International Date Line. Internally, this will translate your longitudes to 0 to 360 to construct the correct, valid Shapely geometry.

WARNING: This will allow your request to be properly submitted and visualized. However, this flag WILL NOT automatically correct for incorrectly ordered spatial inputs.

See also

Query
Quest

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 = GenQuery(reg_a_bbox, reg_a_dates)
>>> print(reg_a)
Extent type: bounding_box
Coordinates: [-55.0, 68.0, -48.0, 71.0]
Date range: (2019-02-20 00:00:00, 2019-02-28 23:59:59)

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 = GenQuery(reg_a_poly, reg_a_dates)
>>> print(reg_a)
Extent type: polygon
Coordinates: [-55.0, 68.0, -55.0, 71.0, -48.0, 71.0, -48.0, 68.0, -55.0, 68.0]
Date range: (2019-02-20 00:00:00, 2019-02-28 23:59:59)

Initializing Query with a geospatial polygon file.

>>> aoi = str(Path('./doc/source/example_notebooks/supporting_files/simple_test_poly.gpkg').resolve())
>>> reg_a_dates = ['2019-02-22','2019-02-28']
>>> reg_a = GenQuery(aoi, reg_a_dates)
>>> print(reg_a)
Extent type: polygon
Coordinates: [-55.0, 68.0, -55.0, 71.0, -48.0, 71.0, -48.0, 68.0, -55.0, 68.0]
Date range: (2019-02-22 00:00:00, 2019-02-28 23:59:59)

__init__(spatial_extent=None, date_range=None, start_time=None, end_time=None, **kwargs)

Methods

__init__([spatial_extent, date_range, ...])

Attributes

`dates`	Return an array showing the date range of the query object.
`end_time`	Return the end time specified for the end date.
`spatial`	Return the spatial object, which provides the underlying functionality for validating and formatting geospatial objects.
`spatial_extent`	Return an array showing the spatial extent of the query object. Spatial extent is returned as an input type (which depends on how you initially entered your spatial data) followed by the geometry data. Bounding box data is [lower-left-longitude, lower-left-latitute, ... upper-right-longitude, upper-right-latitude]. Polygon data is [longitude1, latitude1, longitude2, latitude2, ... longitude_n,latitude_n, longitude1,latitude1].
`start_time`	Return the start time specified for the start date.
`temporal`	Return the Temporal object containing date/time range information for the query object.