GeoEco.DataProducts.CMEMS.CMEMSARCOArray.CreateClimatologicalArcGISRasters

classmethod CMEMSARCOArray.CreateClimatologicalArcGISRasters(username, password, datasetID, variableShortName, statistic, binType, outputWorkspace, mode='Add', log10Transform=False, xCoordType='center', yCoordType='center', zCoordType='center', tCoordType='min', binDuration=1, startDayOfYear=1, rotationOffset=None, spatialExtent=None, minDepth=None, maxDepth=None, startDate=None, endDate=None, rasterExtension='.img', rasterNameExpressions=None, calculateStatistics=True, buildPyramids=False)

Creates climatological rasters for a 3D, or 4D gridded time series dataset published by Copernicus Marine Service.

Requires: ArcGIS Pro 3.2.0 or later or ArcGIS Server equivalent to ArcGIS Pro 3.2.0 or later, Python numpy module, Python copernicusmarine module.

Parameters:

  • username (str) – Copernicus Marine Service user name. Minimum length꞉ 1.

  • password (str) – Copernicus Marine Service password. Minimum length꞉ 1.

  • datasetID (str) – Dataset ID to access. You can find the Dataset ID by going to the Copernicus Marine Data Store, viewing your product of interest, clicking on Data Access, and scrolling to the Dataset ID table. The dataset must have 2, 3, or 4 dimensions. Two of the dimensions must be longitude and latitude. The third and fourth dimension can be depth or time. Minimum length꞉ 1.

  • variableShortName (str) –

    ”Short name” of the variable to access. You can find the variable’s short name by going to to the Copernicus Marine Data Store, viewing your product of interest, clicking on Data Access, scrolling to the Dataset ID table, and clicking on Form under the Subset column. When the form appears, look under the Variables heading. Each variable has a long description in black font, followed by the variable short name and units (in brackets) in a lighter color. Do not include the units as part of the short name. Minimum length꞉ 1.

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

  • log10Transform (bool, optional) –

    “If True, a log10 (base 10 logarithm) function will be applied to the data after it is downloaded before further processing. This transformation may be useful when working with data that are always positive but heavily skewed, such as chlorophyll concentration or other biological oceanographic data. For example, it is a common practice to log10 transform chlorophyll data before detecting chlorophyll fronts or utilizing chlorophyll in a species distribution model.

    Note that it is only possible to take the logarithm of a positive number. If the data contain values less than or equal to zero, a warning will be issued and they will be treated as missing values.

  • xCoordType (str, optional) – Specifies whether the latitude coordinates used by Copernicus for this dataset are the left edges ('min'), the centers ('center'), or the right edges ('max') of the cells. This cannot be determined automatically but for most Copernicus datasets the longitude coordinates are the centers of the cells. To determine the appropriate value for your dataset of interest, consult the dataset’s documentation or contact Copernicus for help. Alternatively, download the dataset to a raster using 'center', load it into a GIS, and overlay a high resolution shoreline. Examine the overlap to determine whether 'min' or 'max' would provide a better match up between the raster and the shoreline. Allowed values꞉ 'min', 'center', 'max'.

  • yCoordType (str, optional) – Specifies whether the latitude coordinates used by Copernicus for this dataset are the bottom edges ('min'), the centers ('center'), or the top edges ('max') of the cells. This cannot be determined automatically but for most Copernicus datasets the latitude coordinates are the centers of the cells. To determine the appropriate value for your dataset of interest, consult the dataset’s documentation or contact Copernicus for help. Alternatively, download the dataset to a raster using 'center', load it into a GIS, and overlay a high resolution shoreline. Examine the overlap to determine whether 'min' or 'max' would provide a better match up between the raster and the shoreline. Allowed values꞉ 'min', 'center', 'max'.

  • zCoordType (str, optional) – Specifies whether the depth coordinates used by Copernicus for this dataset are the shallow edges ('min'), the centers ('center'), or the deep edges ('max') of the cells. This cannot be determined automatically but for most Copernicus datasets the depth coordinates are the centers of the cells. To determine the appropriate value for your dataset of interest, consult the dataset’s documentation or contact Copernicus for help. Allowed values꞉ 'min', 'center', 'max'.

  • tCoordType (str, optional) – Specifies whether the time coordinates used by Copernicus for this dataset are the starting times ('min'), the center times ('center'), or the ending times ('max') of the time slices. This cannot be determined automatically but most Copernicus datasets that are “instantaneous” use center times, while most datasets that represent mean values (e.g. daily or monthly means) use starting times. To determine the appropriate value for your dataset of interest, consult the dataset’s documentation or contact Copernicus for help. Allowed values꞉ 'min', 'center', 'max'.

  • 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]+)?).

  • minDepth (float, optional) –

    Minimum depth, in meters, for the outputs to create. This parameter is ignored if the dataset does not have a depth coordinate. Its value must be between 0 and 20000, inclusive. Outputs will be created for layers with depths that are greater than or equal to the minimum depth and less than or equal to the maximum depth. If you do not specify a minimum depth, the minimum depth of the dataset will be used.

    The value 20000 is a special code representing conditions at the seafloor. Use this value if you need an estimate of “bottom temperature” or the value of another variable at the seafloor. If this value is requested, an output will be created with a fake depth of 20000 meters. The cells of this output will be assigned by stacking all of the depth layers and selecting the deepest cells that have data.

    Note that some Copernicus datasets offer a variable representing values at the seafloor that Copernicus computed ahead of time. This tool is not aware of those variables and cannot access them automatically. But you can manually access such a variable just like any other by providing its name for the Variable Short Name parameter. Accessing those precomputed variables will be faster than using a depth of 20000 to compute them yourself. Variables of that kind will be treated by this tool as not having a depth coordinate. Minimum value꞉ 0.0. Maximum value꞉ 20000.0.

  • maxDepth (float, optional) –

    Maximum depth, in meters, for the outputs to create. This parameter is ignored if the dataset does not have a depth coordinate. Its value must be between 0 and 20000, inclusive. Outputs will be created for images with depths that are greater than or equal to the minimum depth and less than or equal to the maximum depth. If you do not specify a maximum depth, the maximum depth of the dataset will be used.

    The value 20000 is a special code representing conditions at the seafloor. Please see the documenation for the Minimum Depth parameter for discussions of this value. Minimum value꞉ 0.0. Maximum value꞉ 20000.0.

  • startDate (datetime, optional) – Start date of the range of time slices to include in the climatology. If you do not provide a start date, the climatology will start from the first time slice in the dataset.

  • endDate (datetime, optional) – End date of the range of time slices to include in the climatology. If you do not provide an end date, the climatology will extend to the last time slice in the dataset.

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

    • %(DatasetID)s - Copernicus dataset ID.

    • %(ShortVariableName)s - Copernicus short variable name.

    • %(Depth)s - depth of the raster. Only avilable for datasets that have depth coordinates.

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

  • calculateStatistics (bool, optional) – If True, statistics will be calculated for the output rasters. This is usually a good idea for most raster formats because ArcGIS will only display them with helpful colors and gradients if statistics have been calculated. For certain formats, the explicit calculation of statistics is not necessary because it happens automatically when the rasters are created. If you’re using one of those formats, you can set this option to False to speed up the creation of the output rasters.

  • 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