GeoEco.DataProducts.NASA.PODAAC.GHRSSTLevel4.CreateClimatologicalArcGISRasters

classmethod GHRSSTLevel4.CreateClimatologicalArcGISRasters(username, password, shortName, variableName, statistic, binType, outputWorkspace, mode='add', binDuration=1, startDayOfYear=1, rotationOffset=None, spatialExtent=None, startDate=None, endDate=None, datasetType='netcdf', timeout=60, maxRetryTime=300, cacheDirectory=None, metadataCacheLifetime=86400.0, rasterExtension='.img', rasterNameExpressions=None, convertToCelsius=True, calculateStatistics=True, buildPyramids=False)

Creates climatological rasters for a GHRSST Level 4 product published by NASA JPL PO.DAAC.

This tool produces rasters showing the climatological mean value (or other statistic) of a time series of GHRSST L4 SST images. Given a desired GHRSST L4 product, a statistic, and a climatological bin definition, this tool efficiently downloads the images, classifies them into bins, and produces a single raster for each bin. Each cell of the raster is produced by calculating the statistic on the values of that cell extracted from all of the images in the bin.

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 tool 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 tool 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 tool converts them to degrees Celsius but provides an option to obtain the original kelvin values.

This tool 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: ArcGIS Pro 3.2.0 or later or ArcGIS Server equivalent to ArcGIS Pro 3.2.0 or later, 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.

  • statistic (str) –

    Statistic to calculate for each cell, one of:

    • Count - number of grids in which the cell had data.

    • Maximum - maximum value for the cell.

    • Mean - mean value for the cell, calculated as the sum divided by the count.

    • Minimum - minimum value for the cell.

    • Range - range for the cell, calculated as the maximum minus the minimum.

    • Standard_Deviation - sample standard deviation for the cell (i.e. the standard deviation estimated using Bessel’s correction). In order to calculate this, there must be at least two grids with data for the cell.

    • Sum - the sum for the cell.

    Allowed values꞉ 'Count', 'Maximum', 'Mean', 'Minimum', 'Range', 'Standard_Deviation', 'Sum'.

  • binType (str) –

    Climatology bins to use, one of:

    • Daily - daily bins. Time slices will be classified into bins according to their days of the year. The number of days in each bin is determined by the Bin Duration (which defaults to 1). The number of bins is calculated by dividing 365 by the bin duration. If there is no remainder, then that number of bins will be created; slices for the 366th day of leap years will be counted in the bin that includes day 365. For example, if the bin duration is 5, 73 bins will be created. The first will be for days 1-5, the second will be for days 5-10, and so on; the 73rd bin will be for days 361-365 during normal years and 361-366 during leap years. If dividing 365 by the bin duration does yield a remainder, then one additional bin will be created to hold the remaining days. For example, if the bin duration is 8, 46 bins will be created. The first will be for days 1-8, the second for days 9-16, and so on; the 46th will be for days 361-365 during normal years and 361-366 during leap years.

    • Monthly - monthly bins. Time slices will be classified into bins according to their months of the year. The number of months in each bin is determined by the Bin Duration (which defaults to 1). The number of bins is calculated by dividing 12 by the bin duration. If there is no remainder, then that number of bins will be created. For example, if the bin duration is 3, there will be four bins: January-March, April-June, July-September, and October-December. If there is a remainder, then one additional bin will be created. For example, if the bin duration is 5, 3 bins will be created: January-May, June-October, November-December.

    • Cumulative - one bin. A single climatology raster will be calculated from the entire dataset. The Bin Duration is ignored.

    • ENSO Daily, ENSO Monthly, ENSO Cumulative - the same as above, except each of the bins above will be split into three, based on the phase of the El Niño Southern Oscillation (ENSO), as determined by the Oceanic Niño Index (ONI) calculated by the NOAA NCEP Climate Prediction Center. The ONI classifies each month into one of three phases: neutral, El Niño, or La Niña. This tool first classifies time slices according to their dates into ENSO phases (it downloads ONI data from the NOAA Physical Sciences Laboratory), then produces a climatology bin for each phase. For example, if you request ENSO Cumulative bins, three bins will be produced: one for all time slices occurring in neutral months, one for all in El Niño months, and one for all in La Niña months. If you request ENSO Monthly bins, 36 bins will be produced: one for each combination of the 12 months and the three ENSO phases.

    For Daily and Monthly, to adjust when the bins start (e.g. to center a 4-bin seasonal climatology on solstices and equinoxes), use the Start Day Of The Year parameter.

    Allowed values꞉ 'Daily', 'Monthly', 'Cumulative', 'ENSO Daily', 'ENSO Monthly', 'ENSO Cumulative'.

  • outputWorkspace (str) – Directory or geodatabase to receive the rasters. Unless you have a specific reason to store the rasters in a geodatabase, we recommend you store them in a directory because it will be faster and allow the rasters to be organized in a tree. The tree structure and raster names will be generated automatically unless you provide a value for the Raster Name Expressions parameter. Minimum length꞉ 1.

  • mode (str, optional) –

    Overwrite mode, one of:

    • Add - create rasters that do not exist and skip those that already exist. This is the default.

    • Replace - create rasters that do not exist and overwrite those that already exist.

    The ArcGIS Overwrite Output environment setting has no effect on this tool. If ‘Replace’ is selected the rasters will be overwritten, regardless of the ArcGIS Overwrite Output setting.

    Allowed values꞉ 'Add', 'Replace'.

  • binDuration (int, optional) – Duration of each bin, in days or months, when the Bin Type is Daily/ENSO Daily or Monthly/ENSO Monthly, respectively. The default is 1. See Bin Type for more information. Minimum value꞉ 1.

  • startDayOfYear (int, optional) –

    Use this to create bin defintions that deviate from the traditional calendar. The interpretation of this depends on the Bin Type:

    • If Bin Type is Daily or ENSO Daily, then Start Day of Year defines the day of the year of the first climatology bin. For example, if Start Day of Year is 100 and the Bin Duration is 10, the first bin will be numbered 100-109. The bin spanning the end of the year will be numbered 360-004. The last bin will be numbered 095-099. To define a four-bin climatology with bins that are centered approximately on the equinoxes and solstices (i.e., a seasonal climatology), set the Bin Duration to 91 and the start day to 36 (February 5). This will produce bins with dates 036-126, 127-217, 218-308, and 309-035.

    • If Bin Type is Monthly or ENSO Monthly, then Start Day of Year defines the day of the year of the first climatology bin, and the day of the month of that bin will be used as the first day of the month of all of the bins. For example, if Start Day of Year is 46, which is February 15, and the Bin Duration is 1, then the bins will be February 15 - March 14, March 15 - April 14, April 15 - May 14, and so on. Calculations involving Start Day of Year always assume a 365 day year (a non-leap year). To define a four-bin climatology using the months traditionally associated with spring, summer, fall, and winter in many northern hemisphere cultures, set the Bin Duration to 3 and the start day to 60 (March 1). This will produce bins with months 03-05, 06-08, 09-11, and 12-02.

    • If Bin Type is Cumulative or ENSO Cumulative, then Start Day of Year is ignored.

    Minimum value꞉ 1. Maximum value꞉ 365.

  • rotationOffset (float, optional) – Degrees to rotate the outputs about the polar axis. This parameter may only be used for global products. The outputs can only be rotated in whole cells. The value you provide will be rounded off to the closest cell. The value may be positive or negative.

  • spatialExtent (str, optional) – Spatial extent of the outputs, in degrees. This parameter is applied after the rotation parameter and uses coordinates that result after rotation. The outputs can only be clipped in whole grid cells. The values you provide will be rounded off to the closest cell. Minimum length꞉ 1. Must match regular expression꞉ ([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)\s+([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)\s+([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)\s+([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?).

  • startDate (datetime, optional) – Start date for the outputs to create. Outputs will be created for images that occur on or after the start date and on or before the end date. If you do not provide a start date, the date of the first available time slice will be used.

  • endDate (datetime, optional) – End date for the outputs to create. Outputs will be created for images that occur on or after the start date and on or before the end date. If you do not specify an end date, the date of the most recent time slice will be used.

  • 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'.

  • 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.

  • rasterExtension (str, optional) – File extension to use for output rasters. This parameter is ignored if the rasters are stored in a geodatabase rather than the file system, or if the Raster Name Expressions parameter is provided (in which case it determines the file extension). The default is ‘.img’, for ERDAS IMAGINE format. Another popular choice is ‘.tif’, the GeoTIFF format. Please see the ArcGIS documentation for the extensions of the supported formats. Minimum length꞉ 1.

  • rasterNameExpressions (list of str, optional) –

    List of expressions specifying how the output rasters should be named. If you do not provide anything, a default naming scheme will be used.

    If the output workspace is a file system directory, you may provide one or more expressions. Each expression defines a level in a directory tree. The final expression specifies the raster file name. If the output workspace is a geodatabase, you should provide only one expression, which specifies the raster name.

    Each expression may contain any sequence of characters permitted by the output workspace. Each expression may optionally contain one or more of the following case-sensitive codes. The tool replaces the codes with appropriate values when creating each raster:

    • %(ShortName)s - PO.DAAC Short Name of the GHRSST L4 product.

    • %(VariableName)s - GHRSST variable represented in the output raster, either “analysed_sst” or “analysis_error”.

    • %(ClimatologyBinType)s - type of the climatology bin, either Daily if 1-day bins, Xday if multi-day bins (X is replaced by the duration), Monthly if 1-month bins, Xmonth if multi-month bins, or Cumulative. If an ENSO bin type is used, ENSO_ will be prepended to those strings (e.g. ENSO_Daily, ENSO_Monthly).

    • %(ClimatologyBinName)s - name of the climatology bin corresponding represented by the output raster, either dayXXX for 1-day bins (XXX is replaced by the day of the year), daysXXXtoYYY for multi-day bins (XXX is replaced by the first day of the bin, YYY is replaced by the last day), monthXX for 1-month bins (XX is replaced by the month), monthXXtoYY (XX is replaced by the first month of the bin, YY by the last month), or cumulative. If an ENSO bin type is used, neutral_, ElNino_, and LaNina_ will be prepended to those strings for each of the three ENSO phased rasters (e.g. neutral_cumulative, ElNino_cumulative, and LaNina_cumulative when ENSO Cumulative bins are requested).

    • %(Statistic)s - statistic that was calculated, in lowercase and with spaces replaced by underscores; one of: count, maximum, mean, minimum, range, standard_deviation, sum.

    If the Bin Type is Daily, the following additional codes are available:

    • %(FirstDay)i - first day of the year of the climatology bin represented by the output raster.

    • %(LastDay)i - last day of the year of the climatology bin represented by the output raster. For 1-day climatologies, this will be the same as %(FirstDay)i.

    If the Bin Type is Monthly, the following additional codes are available:

    • %(FirstMonth)i - first month of the climatology bin represented by the output raster.

    • %(DayOfFirstMonth)i - first day of the first month of the climatology bin represented by the output raster.

    • %(LastMonth)i - last month of the climatology bin represented by the output raster.

    • %(DayOfLastMonth)i - last day of the last month of the climatology bin represented by the output raster.

    Note that the additional codes are integers and may be formatted using “printf”-style formatting codes. For example, to format the FirstDay as a three-digit number with leading zeros:

    %(FirstDay)03i

    Minimum length꞉ 1.

  • 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.

  • calculateStatistics (bool, optional) – If True and the output rasters use an integer data type, raster attribute tables (RATs) will be built for the output rasters using the ArcGIS Build Raster Attribute Table tool. Raster attribute tables are essentially histograms: they store the counts of cells having each value. If you do not need this information, you can skip the building of raster attribute tables to speed up the creation of the output rasters. Note that for certain raster formats, such as ArcInfo Binary Grid, the explicit buliding of raster attribute tables is not necessary because it happens automatically when the rasters are created. This option is ignored if the output rasters use a floating point data type.

  • buildPyramids (bool, optional) – If True, pyramids will be built for the output rasters using the ArcGIS Build Pyramids tool. Pyramids, also known as overviews, are reduced resolution versions of the rasters that can improve the speed at which they are displayed in the ArcGIS user interface.

Returns:

Updated output workspace.

Return type:

str