GeoEco.DataProducts.NASA.PODAAC.GHRSSTLevel4

class GeoEco.DataProducts.NASA.PODAAC.GHRSSTLevel4(username, password, shortName, variableName, datasetType='netcdf', applyMask=False, maskBitsToCheck=None, convertToCelsius=True, timeout=60, maxRetryTime=300, cacheDirectory=None, metadataCacheLifetime=86400.0)

Bases: Grid

A Grid representing a GHRSST Level 4 product from NASA JPL PO.DAAC, distributed by NASA Earthdata.

The Group for High-Resolution Sea Surface Temperature (GHRSST) provides a new generation of global high-resolution (<10km) SST products to the operational oceanographic, meteorological, climate and general scientific community. The overall aim of the GHRSST is to provide the best quality sea surface temperature data for applications in short, medium and decadal/climate time scales in the most cost effective and efficient manner through international collaboration and scientific innovation.

This class accesses Level 4 (L4) gap-free gridded SST products published in near real-time by the GHRSST Global Data Assembly Center (GDAC) at the NASA JPL Physical Oceanography Distributed Active Archive Center (PO.DAAC) and subsequently hosted and distributed by NASA Earthdata. These products provide regional and global daily cloud-free estimates of SST at spatial resolutions ranging from 0.25 degrees to down 1 km. To fill in cloudy areas, data from multiple satellite and in-situ sensors are combined and regions without any data are filled in various interpolation and modeling techniques.

All products accessed by this class are published at a daily timestep. Some products are updated on a continual basis and available in near real time; others are updated infrequently and are intended mainly for historical analysis. The temporal extent, spatial resolution and extent, and sensors and interpolation technique used vary by product. All products use the WGS 1984 geographic coordinate system. GHRSST temperatures are published in kelvin. By default, this class converts them to degrees Celsius but provides an option to obtain the original kelvin values.

This class supports many but not all of the GHRSST L4 published by PO.DAAC. If you see a GHRSST L4 product on PO.DAAC that is not available with this tool, please contact the MGET development team for assistance.

Please see these instructions on how to acknowledge your use of PO.DAAC products.

Requires: Python numpy module, Python requests module, Python netCDF4 module.

Parameters:

username (str) – NASA Earthdata account user name. Minimum length꞉ 1.
password (str) – NASA Earthdata account password. Minimum length꞉ 1.
shortName (str) –
PO.DAAC Short Name of the GHRSST L4 product to access. Currently, the following products are supported:
All products use the WGS 1984 geographic coordinate system and are published at a daily time-step. Some products are updated on a continual basis and available in near real time; others are updated infrequently and are intended mainly for historical analysis. The temporal extent, spatial resolution and extent, sensors and, interpolation technique used vary by product. Please see the products’ documentation for details.

This tool supports many but not all of the GHRSST L4 products published by PO.DAAC. If you see a product on PO.DAAC that is not available with this tool, please contact the MGET development team for assistance.

Allowed values꞉ 'AVHRR_OI-NCEI-L4-GLOB-v2.0', 'AVHRR_OI-NCEI-L4-GLOB-v2.1', 'CMC0.1deg-CMC-L4-GLOB-v3.0', 'CMC0.2deg-CMC-L4-GLOB-v2.0', 'DMI_OI-DMI-L4-GLOB-v1.0', 'GAMSSA_28km-ABOM-L4-GLOB-v01', 'Geo_Polar_Blended-OSPO-L4-GLOB-v1.0', 'Geo_Polar_Blended_Night-OSPO-L4-GLOB-v1.0', 'K10_SST-NAVO-L4-GLOB-v01', 'MUR-JPL-L4-GLOB-v4.1', 'MUR25-JPL-L4-GLOB-v04.2', 'MW_IR_OI-REMSS-L4-GLOB-v5.0', 'MW_IR_OI-REMSS-L4-GLOB-v5.1', 'MW_OI-REMSS-L4-GLOB-v5.0', 'MW_OI-REMSS-L4-GLOB-v5.1', 'OISST_HR_NRT-GOS-L4-BLK-v2.0', 'OISST_HR_NRT-GOS-L4-MED-v2.0', 'OISST_UHR_NRT-GOS-L4-BLK-v2.0', 'OISST_UHR_NRT-GOS-L4-MED-v2.0', 'OSTIA-UKMO-L4-GLOB-REP-v2.0', 'OSTIA-UKMO-L4-GLOB-v2.0', 'RAMSSA_09km-ABOM-L4-AUS-v01'. Case sensitive.
variableName (str) –
GHRSST variable to access, one of:
- analysed_sst - product-specific estimate of SST.
- analysis_error - product-specific estimate of of the error in the SST estimate.
Please see the product documentation for details about what these variables mean and how they were calculated. These variable names are case-sensitive.

Allowed values꞉ 'analysed_sst', 'analysis_error'. Case sensitive.
datasetType (str, optional) –
Dataset type to access. Currently only netCDF is supported. netCDF files will be downloaded and cached locally. If you specify a Cache Directory, they will be stored there and not deleted. Otherwise a temporary directory will be created to hold the files while the download is in progress and deleted when the relevent data are extracted and execution is complete.

The disadvantage with this approach is that when your study area is small and you’re accessing a global product, a lot of bandwidth and disk space is wasted. This problem can become acute if you’re accessing a global product with very high resolution, such as one of the 1 km resolution datasets. If this proves too problematic, contact the MGET development team for assistance. We may be able to implement an alternative access method that allows downloads to be limited to a geographic bounding box.

Allowed values꞉ 'netCDF'.
applyMask (bool, optional) –
If False, the default, no masking will be performed to the GHRSST analysed_sst variable beyond what the GHRSST team has already done. For most GHRSST L4 products, this is sufficient because land and sea ice have already been masked and will appear as the NoDataValue.

If True, analysed_sst will be masked where the GHRSST mask variable is some value other than 1. The value 1 indicates water that is free of sea ice. To check for specific bits of the mask instead, use maskBitsToCheck.
maskBitsToCheck (int, optional) – Integer defining the bits of the GHRSST mask variable to check. This is ignored unless applyMask is True. If it is, and this parameter is omitted (the default) then cells will be masked when the mask variable is something other than 1. If parameter is given, then if the GHRSST mask variable has a 1 for any bit that this parameter also has a 1, then the cell is masked. Minimum value꞉ 0.
convertToCelsius (bool, optional) – If True (the default), temperature values will be converted from kelvin to degrees Celsius. If False, temperature values will be in the original kelvin values.
timeout (int, optional) –
Number of seconds to wait for the server to respond before failing with a timeout error.

If you also provide a Maximum Retry Time and it is larger than the timeout value, the failed request will be retried automatically (with the same timeout value) until it succeeds or the Maximum Retry Time has elapsed.

If you receive a timeout error you should investigate the server to determine if it is malfunctioning or just slow. Check the Earthdata website to see if NASA has posted a notice about the problem, or contact the NASA directly. If the server just slow, increase the timeout value to a larger number, to give the server more time to respond.

Minimum value꞉ 1.
maxRetryTime (int, optional) –
Number of seconds to retry requests to the server before giving up.

Use this parameter to cope with transient failures. For example, you may find that the server is rebooted nightly during a maintenance cycle. If you start a long running operation and want it to run overnight without failing, set the maximum retry time to a duration that is longer than the time that the server is offline during the maintenance cycle.

To maximize performance while minimizing load during failure situations, retries are scheduled with progressive delays:
- The first retry is issued immediately.
- Then, so long as fewer than 10 seconds have elapsed since the original request was issued, retries are issued every second.
- After that, retries are issued every 30 seconds until the maximum retry time is reached or the request succeeds.
Minimum value꞉ 1.
cacheDirectory (str, optional) –
Directory for caching local copies of downloaded data. A cache directory is optional but highly recommended if you plan to repeatedly access data for the same range of dates.

When data are requested, the cache directory will be checked for data that was downloaded and cached during prior requests. If cached data exists that can fulfill part of the current request, the request will be serviced by reading from cache files rather than downloading from the server. If the entire request can be serviced from the cache, the server will not be accessed at all and the request will be completed extremely quickly. Any parts of the request that cannot be serviced from the cache will be downloaded from the server and added to the cache, speeding up future requests for the same data.

If you use a cache directory, be aware of these common pitfalls:
- The caching algorithm permits the cache to grow to infinite size and never deletes any cached data. If you access a large amount of data (e.g. an entire 20 terabyte collection of satellite images) it will all be added to the cache. Be careful that you do not fill up your hard disk. To mitigate this, manually delete the entire cache or selected directories or files within it.
- The caching algorithm stores data in uncompressed files, so that subsets of those files may be quickly accessed. To save space on your hard disk, you can enable compression of the cache directory using the operating system. On Windows, right click on the directory in Windows Explorer, select Properties, click Advanced, and enable “Compress contents to save disk space”.
- The caching algorithm cannot detect when portions of a dataset have been replaced on the server, thereby making the cached data obsolete. Thus, if a data provider republishes a dataset with improved data values, the caching algorithm will continue to use the old, obsolete values. To mitigate this, you should monitor when data providers reprocess their datasets, and delete the cached files when they become obsolete.
Minimum length꞉ 1.
metadataCacheLifetime (float, optional) –
Maximum amount of time, in seconds, that granule metadata downloaded from the NASA Earthdata Common Metadata Repository (CMR) will be cached.

Downloading metadata from the NASA Earthdata CMR can be slow. If this parameter and a cache directory are both provided, when the CMR is queried for all granule metadata for a given collection_concept_id, the downloaded metadata will be cached in the directory for this amount of time. During this period, the cached metadata will be accessed instead of the server, which can greatly speed up processing involving NASA Earthdata granules. However, if new datasets are stored in the CMR, they will not be discovered until the cached metadata has expired.

If this parameter is not provided (the default), then granule metadata will not be cached.

Minimum value꞉ 1.0.

Returns:

GHRSSTLevel4 instance.

Return type:

GHRSSTLevel4

Properties

property CenterCoords: (object) Coordinates of the grid cell centers, indexed using the 1-character dimension of interest and optionally a range to retrieve a numpy.ndarray of coordinates (e.g. CenterCoords['x', 0:4]) or an integer to retrieve a float for a single coordinate (e.g. CenterCoords['x', 10]). Coordinates for the t dimension are returned as datetime instances. Read only.

property CoordDependencies: (tuple of str) Same length as Dimensions. Dimensions that each dimension depends on for determining its coordinates. None for dimensions that have a constant coordinate increment. Read only.

property CoordIncrements: (tuple of float) Same length as Dimensions. Coordinate increment for each dimension. None for dimensions that do not have a constant coordinate increment. Read only.

property Data: (object) This grid’s data, indexable using slices (e.g. grid.Data[:, 5:10, -10:]) or integers (e.g. grid.Data[0,1,-2]) or both in combination. Strides and negative indexes are supported in the traditional manner. If the grid is writable, Data can be assigned to write values to the grid, e.g. grid.Data[0,1] = 5 or grid.Data[:,:] = numpy.zeros(grid.Shape). Returns and accepts numpy.ndarray, float, and int. Read only.

property DataIsScaled: (bool) If True, the underlying raw data are stored as the UnscaledDataType to save storage space and then transformed by a scaling equation on the fly when they are returned by Data. The raw data can be accessed with UnscaledData. If False, the raw data are returned as is, with no transformation needed, and UnscaledDataType and DataType are the same, and UnscaledData returns the same values as Data. Read only.

property DataType: (str) Numeric data type of the grid, after the scaling function (if any) has been applied to the raw data. numpy.ndarrays returned by Data have this type. Read only. Allowed values꞉ 'int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32', 'float32', 'float64'. Case sensitive.

property Dimensions: (str) Dimensions of this grid. Read only. Allowed values꞉ 'yx', 'zyx', 'tyx', 'tzyx'. Case sensitive.

property DisplayName: (str) Informal name of this object, suitable to be displayed to the user. Read only. Minimum length꞉ 1.

property MaxCoords: (object) Maximum coordinate value for each cell (i.e., the coordinates of the cells’ right edges), indexed using the 1-character dimension of interest and optionally a range to retrieve a numpy.ndarray of coordinates (e.g. MaxCoords['x', 0:4]) or an integer to retrieve a float for a single coordinate (e.g. MaxCoords['x', 10]). Coordinates for the t dimension are returned as datetime instances. Read only.

property MinCoords: (object) Minimum coordinate value for each cell (i.e., the coordinates of the cells’ left edges), indexed using the 1-character dimension of interest and optionally a range to retrieve a numpy.ndarray of coordinates (e.g. MinCoords['x', 0:4]) or an integer to retrieve a float for a single coordinate (e.g. MinCoords['x', 10]). Coordinates for the t dimension are returned as datetime instances. Read only.

property NoDataValue: (object or None) int, float, or single-element numpy array giving the value that indicates that cells of Data should be interpreted as having no data (these are also known as missing, NA, or NULL cells), or None if all cells must have data. Read only.

property ParentCollection: (DatasetCollection or None) Parent DatasetCollection that this object is part of (if any). Read only.

property Shape: (tuple of int) Same length as Dimensions. Length (number of grid cells) of each dimension. Read only.

property TCountPerSemiRegularPeriod: (int or None) Number of time slices per semi-regular period (i.e. per year). None if the grid’s dimensions do not contain a t coordinate or the t coordinate is not semi-regular. Read only.

property TIncrementUnit: (str or None) Unit of the t coordinate. None if the grid’s dimensions do not contain a t coordinate. Read only. Allowed values꞉ 'year', 'month', 'day', 'hour', 'minute', 'second'. Case sensitive.

property TSemiRegularity: (str or None) Type of semi-regularity used for the t coordinate. None if the grid’s dimensions do not contain a t coordinate or the t coordinate is not semi-regular. Read only. Allowed values꞉ 'annual'. Case sensitive.

property UnscaledData: (object) This grid’s data underlying raw data, before it has been transformed by a scaling equation. UnscaledData is indexable using slices (e.g. grid.UnscaledData[:, 5:10, -10:]) or integers (e.g. grid.UnscaledData[0,1,-2]) or both in combination. Strides and negative indexes are supported in the traditional manner. If the grid is writable, UnscaledData can be assigned to write values to the grid, e.g. grid.UnscaledData[0,1] = 5 or grid.UnscaledData[:,:] = numpy.zeros(grid.Shape). Returns and accepts numpy.ndarray, float, and int. Read only.

property UnscaledDataType: (str) Numeric data type of the grid’s raw data, before it has been transformed by a scaling equation. numpy.ndarrays returned by UnscaledData have this type. If no transformation is needed (DataIsScaled is False), then UnscaledDataType and ScaledDataType are the same, and UnscaledData returns the same values as Data. Read only. Allowed values꞉ 'int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32', 'float32', 'float64'. Case sensitive.

property UnscaledNoDataValue: (object or None) int or float value that indicates that cells of UnscaledData should be interpreted as having no data (these are also known as missing, NA, or NULL cells), or None if all cells must have data. Read only.

Methods

`CannyEdgesAsArcGISRasters`	Creates rasters indicating the positions of fronts in GHRSST Level 4 images published by NASA JPL PO.DAAC, using the Canny edge detection algorithm.
`Close`	Closes any open files or connections associated with this object and releases any other resources allocated to access it.
`ConvertSpatialReference`	Converts a spatial reference from one format to another, such as an OGC WKT string to a Proj4 string.
`CreateArcGISRasters`	Creates rasters for a GHRSST Level 4 product published by NASA JPL PO.DAAC.
`CreateClimatologicalArcGISRasters`	Creates climatological rasters for a GHRSST Level 4 product published by NASA JPL PO.DAAC.
`DeleteLazyPropertyValue`	Deletes the lazy property with the specified name.
`GetAllQueryableAttributes`	Returns a list of all queryable attributes.
`GetIndicesForCoords`	Given a `tuple` or `list` of coordinates, returns a `list` of `int` indices into `Data` for the cell that contains the coordinates.
`GetLazyPropertyValue`	Returns the value of the lazy property with the specified name.
`GetQueryableAttribute`	Returns the queryable attribute with the specified name.
`GetQueryableAttributeValue`	Returns the value of the queryable attribute with the specified name.
`GetQueryableAttributesWithDataType`	Returns a list queryable attributes having the specified data type.
`GetSpatialReference`	Returns the spatial reference of this dataset.
`HasLazyPropertyValue`	Returns True if the specified lazy property has a value.
`InterpolateAtArcGISPoints`	Interpolates values of a GHRSST Level 4 product published by NASA JPL PO.DAAC at points.
`SetLazyPropertyValue`	Sets the lazy property with the specified name to the specified value.
`SetSpatialReference`	Sets the spatial reference of this dataset.
`TestCapability`	Tests whether a capability is supported by this class or an instance of it.
`numpy_equal_nan`