 |  |  | GeoEco Python Reference |  |  |  |
| | | GeoEco Python Reference | | | |
Creates climatological rasters for a HYCOM GOMl0.04 3D variable
| Class: | HYCOMGOMl0043D |
| Intended use: | Recommended for external callers |
| COM: | Exposed as the CreateClimatologicalArcGISRasters method of COM class GeoEco.HYCOMGOMl0043D |
| ArcGIS: | Exposed as the Create Climatological Rasters for HYCOM GOMl0.04 3D Variable geoprocessing tool |
| Method type: | Classmethod |
| updatedOutputWorkspace = HYCOMGOMl0043D.CreateClimatologicalArcGISRasters( | variableName, statistic, binType, outputWorkspace[, mode[, rasterNameExpressions[, binDuration[, startDayOfYear[, spatialExtent[, linearUnit[, startDate[, endDate[, timeout[, maxRetryTime[, cacheDirectory[, calculateStatistics[, buildPyramids]]]]]]]]]]]]]) |
| Python type: | unicode |
| Allowed values: | u'emp', u'mld', u'mlp', u'qtot', u'ssh', u'surface_salinity_trend', u'surface_temperature_trend' |
HYCOM 3D variable (dimensions x, y, and time), one of:
Please see the HYCOM documentation for more information about these variables.
| Python type: | unicode |
| Allowed values: | u'Count', u'Maximum', u'Mean', u'Minimum', u'Range', u'Standard Deviation', u'Sum' |
Statistic to calculate for each cell, one of:
| Python type: | unicode |
| Allowed values: | u'Daily', u'Monthly', u'Cumulative' |
Climatology bins to use, one of:
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 Climatology At This Day Of The Year parameter.
| Python type: | unicode |
| Minimum length: | 1 |
| Maximum length: | 255 |
| Must exist: | No |
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 much faster and allows the rasters to be organized in a tree. If you do store the rasters in a geodatabase, you must change the Raster Name Expressions parameter; see below for more information.
| Python type: | unicode |
| Default value: | u'add' |
| Allowed values: | u'Add', u'Replace' |
Overwrite mode, one of:
The ArcGIS Overwrite Outputs geoprocessing setting has no effect on this tool. If 'Replace' is selected the rasters will be overwritten, regardless of the ArcGIS Overwrite Outputs setting.
| Python type: | list of unicode |
| Default value: | [u'%(VariableName)s', u'%(ClimatologyBinType)s_Climatology', u'%(VariableName)s_%(ClimatologyBinName)s_%(Statistic)s.img'] |
| Minimum length: | 1 |
List of expressions specifying how the output rasters should be named.
The default expression assumes you are storing rasters in a file system directory and creates them in a tree structure with levels for variable and climatology bin type. When storing rasters in a directory, the final expression specifies the file name of the raster and any preceding expressions specify subdirectories. The extension of the final expression determines the output raster format: .asc for ArcInfo ASCII Grid, .bmp for BMP, .gif for GIF, .img for an ERDAS IMAGINE file, .jpg for JPEG, .jp2 for JPEG 2000, .png for PNG, .tif for GeoTIFF, or no extension for ArcInfo Binary Grid. The default expression uses .img.
When storing rasters in a geodatabase, you should provide only one expression. That expression specifies the raster's 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:
If the Bin Type is "Daily", the following additional codes are available:
If the Bin Type is "Monthly", the following additional codes are available:
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
| Python type: | int |
| Default value: | 1 |
| Minimum value: | 1 |
Duration of each bin, in days or months, when the Bin Type is Daily or Monthly, respectively. The default is 1. See the Bin Type parameter for more information.
| Python type: | int |
| Default value: | 1 |
| Minimum value: | 1 |
Use this parameter to create bin defintions that deviate from the traditional calendar. The interpretation of this parameter depends on the Bin Type:
| Python type: | unicode or None |
| Default value: | None |
| 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]+)?) |
Spatial extent of the outputs, in the units specified by the Linear Units parameter.
If you do not specify a spatial extent, it will default to approximately 18 to 32 N, 98 to 76 W. The outputs can only be clipped in whole grid cells. The values you provide will be rounded off to the closest cell.
| Python type: | unicode |
| Default value: | u'Degrees' |
| Allowed values: | u'Degrees', u'Meters' |
Specifies the unit of the Spatial Extent parameter, one of:
| Python type: | datetime.datetime or None |
| Default value: | None |
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. The HYCOM GOMl0.04 dataset provides a five-day forecast; its temporal extent ranges from 1 January 2003 to today's date plus five days. If you do not specify a start date, 1 January 2003 will be used.
The time component of the start date is ignored.
| Python type: | datetime.datetime or None |
| Default value: | None |
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. The HYCOM GOMl0.04 dataset provides a five-day forecast; its temporal extent ranges from 1 January 2003 to today's date plus five days. If you do not specify an end date, the most recent day available will be used (typically today's date plus five days).
The time component of the end date is ignored.
| Python type: | int or None |
| Default value: | 600 |
| Minimum value: | 1 |
Number of seconds to wait for the THREDDS or OPeNDAP 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 timout 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 server's website to see if the operator has posted a notice about the problem, or contact the operator directly. If the server just slow, increase the timeout value to a larger number, to give the server more time to respond.
| Python type: | int or None |
| Default value: | None |
| Minimum value: | 1 |
Number of seconds to retry requests to the THREDDS or OPeNDAP server before giving up.
Use this parameter to cope with a server that experiences transient failures. For example, some servers are rebooted as part of nightly maintenance cycles. 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:
| Python type: | unicode or None |
| Default value: | None |
| Minimum length: | 1 |
| Maximum length: | 255 |
| Must exist: | No |
Directory to cache OPeNDAP datasets.
A cache directory can dramatically speed up scenarios that involve accessing the same subsets the HYCOM data over and over again. When OPeNDAP data is requested from the HYCOM server, 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 the OPeNDAP server. If the entire request can be serviced from the cache, the OPeNDAP 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 OPeNDAP 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:
| Python type: | bool |
| Default value: | True |
If True, statistics will be calculated for the output rasters using the ArcGIS Calculate Statistics geoprocessing tool. 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.
| Python type: | bool |
| Default value: | False |
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.
| Python type: | unicode |
| Minimum length: | 1 |
| Maximum length: | 255 |
| Must exist: | No |
Updated output workspace.
This tool produces rasters showing the climatological average value (or other statistic) of a HYCOM GLMl0.04 3D variable. Given a desired variable, a statistic, and a climatological bin definition, this tool downloads daily images for the variable, 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 rasters in the bin.
At the time this tool was developed, the HYCOM + NCODA Gulf of Mexico 1/25 Degree Analysis (GLMl0.04) consisted of two gridded datasets:
The datasets have identical spatiotemporal extents and resolutions and the same oceanographic variables. This tool treats them as one continuous dataset and takes time slices prior to 1 July 2010 from expt_20.1 and on or after that date from expt_30.1. (On the HYCOM server, the datasets actually overlap slightly, with expt_20.1 ending slightly after 30 June 2010 and expt_30.1 starting slightly before 1 July 2010. The tool ignores the overlapping time slices and switches from expt_20.1 to expt_30.1 on 1 July.)
The grids are in Mercator projection based on a sphere with radius 6371001 m, with square cells approximately 4.5 km on a side. The geographic extent is approximately 18 to 32 N, 98 to 76 W. The time step is 1 day, with time slices representing the instantaneous condition of the ocean estimated at 00:00 UTC on each day.
The HYCOM documentation states that HYCOM provides a five day forecast and five day hindcast from the current date, although we have observed netCDF files on their servers that suggested this window may extend seven days in both directions. HYCOM revises the data within this window daily, using the latest ocean observations assimilated from buoys, satellites, and other sensors. Use caution when working with time slices close to the current date, as it appears that time slices continue to be revised until they are 7 days older than the current date.
Occasionally, HYCOM fails to generate data for a time slice, presumably due to an outage or other problem in their data processing infrastructure. For example, in 2004, HYCOM failed to generate data for three of the 366 time slices of that year. Although HYCOM omits these time slices from their server, this tool represents them as grids filled with the No Data value.
The datasets include both 3D variables (dimensions x, y, and time) and 4D variables (dimensions x, y, depth, and time). The 4D variables are estimated at 40 depth levels: 0, 5, 10, 15, 20, 25, 30, 40, 50, 60, 70, 80, 90, 100, 125, 150, 200, 250, 300, 400, 500, 600, 700, 800, 900, 1000, 1100, 1200, 1300, 1400, 1500, 1750, 2000, 2500, 3000, 3500, 4000, 4500, 5000, and 5500 m.
This tool accesses the HYCOM datasets using the OPeNDAP protocol, allowing data to be retrieved very efficiently. However, during periods of high load, the HYCOM OPeNDAP server often requires five to ten minutes to return the first slice of data. Please be patient; after the first one is returned, the rest will go much faster. During periods of extreme load, the tool may fail with a timeout error. If this happens, increase the timeout value and try again, or wait until later when the server is less busy.
References
Chassignet, E.P., Hurlburt, H.E., Metzger, E.J., Smedstad, O.M., Cummings, J.A., Halliwell, G.R., Bleck, R., Baraille, R., Wallcraft., A.J., Lozano, C., Tolman, H.L., Srinivasan, A., Hankin, S., Cornillon, P., Weisberg, R., Barth, A., He, R., Werner, F. and Wilkin, J. (2009). US GODAE: Global Ocean Prediction with the HYbrid Coordinate Ocean Model (HYCOM). Oceanography 22: 64-75.
The HYCOM User's Guide and many other technical documents are available on the HYCOM web site.
| | | GeoEco Python Reference | | | |