|
Creates climatological rasters for a 4D variable of the equatorial (Mercator) region of the HYCOM GLBa0.08 dataset
This tool produces rasters showing the climatological average value (or other statistic) of a HYCOM GLBa0.08 4D variable. Given a desired variable, a statistic, and a climatological bin definition, this tool downloads daily images for each depth layer of 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.
This tool accesses the "All Experiments (Aggregated)" dataset of the HYCOM + NCODA Global 1/12 Degree Analysis (GLBa0.08) using the OPeNDAP protocol.
The dataset consists of a collection of 3D and 4D gridded variables. The 3D variables represent conditions at the surface of the ocean and have dimensions of x, y, and time. The 4D variables represent conditions at depth and have dimensions of x, y, depth, and time.
HYCOM uses an unusual georeferencing scheme in which the Earth is represented by a grid that uses three different projections. The southern portion of the grid, encompassing approximately 66 S to 78 S, is in an equirectangular projection, with rectangular cells having the dimensions of 0.08 degrees longitude and 0.032 degrees latitude. The equatorial portion of the grid, encompassing approximately 47 N to 66 S, is in a Mercator projection with square cells approximately 8.9 km on a side (equivalent to 0.08 degrees of longitude at the equator). The northern portion of the grid, encompassing approximately 90 N to 47 N, is in a complicated "bi-polar" projection.
This tool accesses the equatorial (Mercator) portion of the HYCOM grid, and is therefore very appropriate if your region of interest is between 47 N and 66 S. This tool can optionally extend the northern extent of of the Mercator grid to 60 N by interpolating values from the bi-polar region. If your region of interest is between 47 N and 60 N, enable that option but review the HYCOM data carefully to ensure the interpolated values appear to be reasonable for your application. Also be aware of the increasing map distortion caused by the Mercator projection as you approach high latitudes; at 60 degrees latitude, the cells are actually only one-half as wide (4.5 km) as the projection claims (8.9 km).
If your area of interest is north of 60 N or south of 66 S, do not use this tool because it cannot access HYCOM data for those regions.
For more information on HYCOM's georeferencing, please see the HYCOM User's Guide, chapter 3: The HYCOM Grid, sections 2.3: I/O File Formats in HYCOM, and 5.1: File "regional.grid.[ab]".
The temporal extent of this dataset is 11 November 2003 to several days beyond the current date, with a time step of 1 day. The time slices represent 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 regularly observed netCDF files on their servers that suggested this window actually extends 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 dataset's 4D variables are estimated at 33 depth levels: 0, 10, 20, 30, 50, 75, 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.
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.
Command line syntax| Expression | Explanation |
|---|---|
| <salinity | temperature | u | v> | HYCOM 4D variable (dimensions x, y, depth, and time), one of:
Please see the HYCOM documentation for more information about these variables. |
| <Count | Maximum | Mean | Minimum | Range | Standard Deviation | Sum> | Statistic to calculate for each cell, one of:
|
| <Daily | Monthly | 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. |
| <outputWorkspace> | 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. |
| {Add | 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. |
| {rasterNameExpressions;rasterNameExpressions...} | 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, climatology bin type, and depth. 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:
|
| {binDuration} | 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. |
| {startDayOfYear} | Use this parameter to create bin defintions that deviate from the traditional calendar. The interpretation of this parameter depends on the Bin Type:
|
| {rotationOffset} | Distance to rotate the output rasters about the polar axis, in the units specified by the Linear Units parameter. If not provided, the output rasters will be centered on approximately 105.88 W. Use this parameter to shift the center longitude of the rasters to a different location. Positive values shift it to the east, negative values to the west. The rasters can only be rotated in whole grid cells. The value you provide will be rounded off to the closest cell. For example, to center the rasters on the Prime Meridian, provide 105.88 for this parameter and specify 'Degrees' for the Linear Unit parameter. But because 105.88 is not evenly divisible by the the cell size (0.08 degrees), it will be rounded to 105.92 and the central meridian of the rasters will actually be 0.04, rather than 0. |
| {extendYExtent} | If this option is enabled, the northern extent of the HYCOM data will be extended from 47 N to 60 N by interpolating values from the bi-polar portion of HYCOM's grid. The northern extent of the Mercator region of HYCOM's grid is about 47 N. Above this latitude, HYCOM uses a complicated bi-polar projection that cannot be represented by most GIS programs. Because of that, this tool does not provide direct access to the bi-polar data above 47 N. But if this option is enabled, the tool will extend the Mercator region up to 60 N by interpolating values above 47 N from the bi-polar region using the nearest neighbor algorithm. Under this scheme, the value of each Mercator cell above 47 N will be copied from the bi-polar cell that is closest in latitude and longitude. A nearest neighbor algorithm was used for its computational simplicity and efficiency and to preserve sharp gradients that would be smoothed out by alternative techniques. |
| {spatialExtent} | Spatial extent of the output rasters, in the units specified by the Linear Units parameter. If you do not specify a spatial extent, it will default to approximately 47 N to 66 S, (unless you enable the option that extends the northernmost extent to 60 N). The rasters can only be clipped in whole grid cells. The values you provide will be rounded off to the closest cell. |
| {Degrees | Meters} | Specifies the unit of the Spatial Extent parameter, one of:
|
| {minDepth} | Minimum depth, in meters, for the outputs to create. The 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 minimum depth, 0 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 HYCOM depth layers and selecting the deepest cells that have data. Because HYCOM depth layers are spaced farther apart at deeper depths, the deepest HYCOM layer with data at a specific location might be substantially shallower than the actual seafloor depth. Bear this in mind when considering the likely accuracy of the output. |
| {maxDepth} | Maximum depth, in meters, for the outputs to create. The 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, 5500 will be used. This is the depth of the deepest HYCOM layer. 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. |
| {startDate} | 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 GOMa0.08 dataset provides a five-day forecast; its temporal extent ranges from 11 November 2003 to today's date plus five days. If you do not specify a start date, 11 November 2003 will be used. The time component of the start date is ignored. |
| {endDate} | 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 GLBa0.08 dataset provides a five-day forecast; its temporal extent ranges from 11 November 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. |
| {timeout} | 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. |
| {maxRetryTime} | 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:
|
| {cacheDirectory} | 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:
|
| {calculateStatistics} | 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. |
| {buildPyramids} | 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. |
Scripting syntax| Expression | Explanation |
|---|---|
| HYCOM variable (Required) | HYCOM 4D variable (dimensions x, y, depth, and time), one of:
Please see the HYCOM documentation for more information about these variables. |
| Statistic (Required) | Statistic to calculate for each cell, one of:
|
| Climatology bin type (Required) | 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. |
| Output workspace (Required) | 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. |
| Overwrite mode (Optional) | 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. |
| Raster name expressions (Optional) | 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, climatology bin type, and depth. 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:
|
| Climatology bin duration (Optional) | 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. |
| Start climatology at this day of the year (Optional) | Use this parameter to create bin defintions that deviate from the traditional calendar. The interpretation of this parameter depends on the Bin Type:
|
| Rotate raster by (Optional) | Distance to rotate the output rasters about the polar axis, in the units specified by the Linear Units parameter. If not provided, the output rasters will be centered on approximately 105.88 W. Use this parameter to shift the center longitude of the rasters to a different location. Positive values shift it to the east, negative values to the west. The rasters can only be rotated in whole grid cells. The value you provide will be rounded off to the closest cell. For example, to center the rasters on the Prime Meridian, provide 105.88 for this parameter and specify 'Degrees' for the Linear Unit parameter. But because 105.88 is not evenly divisible by the the cell size (0.08 degrees), it will be rounded to 105.92 and the central meridian of the rasters will actually be 0.04, rather than 0. |
| Extend northern extent of HYCOM data from 47 N to 60 N (Optional) | If this option is enabled, the northern extent of the HYCOM data will be extended from 47 N to 60 N by interpolating values from the bi-polar portion of HYCOM's grid. The northern extent of the Mercator region of HYCOM's grid is about 47 N. Above this latitude, HYCOM uses a complicated bi-polar projection that cannot be represented by most GIS programs. Because of that, this tool does not provide direct access to the bi-polar data above 47 N. But if this option is enabled, the tool will extend the Mercator region up to 60 N by interpolating values above 47 N from the bi-polar region using the nearest neighbor algorithm. Under this scheme, the value of each Mercator cell above 47 N will be copied from the bi-polar cell that is closest in latitude and longitude. A nearest neighbor algorithm was used for its computational simplicity and efficiency and to preserve sharp gradients that would be smoothed out by alternative techniques. |
| Spatial extent (Optional) | Spatial extent of the output rasters, in the units specified by the Linear Units parameter. If you do not specify a spatial extent, it will default to approximately 47 N to 66 S, (unless you enable the option that extends the northernmost extent to 60 N). The rasters can only be clipped in whole grid cells. The values you provide will be rounded off to the closest cell. |
| Linear unit (Optional) | Specifies the unit of the Spatial Extent parameter, one of:
|
| Minimum depth (Optional) | Minimum depth, in meters, for the outputs to create. The 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 minimum depth, 0 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 HYCOM depth layers and selecting the deepest cells that have data. Because HYCOM depth layers are spaced farther apart at deeper depths, the deepest HYCOM layer with data at a specific location might be substantially shallower than the actual seafloor depth. Bear this in mind when considering the likely accuracy of the output. |
| Maximum depth (Optional) | Maximum depth, in meters, for the outputs to create. The 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, 5500 will be used. This is the depth of the deepest HYCOM layer. 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. |
| Start date (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. The HYCOM GOMa0.08 dataset provides a five-day forecast; its temporal extent ranges from 11 November 2003 to today's date plus five days. If you do not specify a start date, 11 November 2003 will be used. The time component of the start date is ignored. |
| End date (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. The HYCOM GLBa0.08 dataset provides a five-day forecast; its temporal extent ranges from 11 November 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. |
| Timeout value (Optional) | 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. |
| Maximum retry time (Optional) | 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:
|
| Cache directory (Optional) | 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:
|
| Calculate statistics (Optional) | 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. |
| Build pyramids (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. |