root/MGET/Branches/Jason/PythonPackage/src/GeoEco/DataProducts/NOAA/OSCAR.py @ 913

# OSCAR.py - Provides methods for working with ocean currents data
# from OSCAR (http://www.oscar.noaa.gov/).
#
# Copyright (C) 2011 Jason J. Roberts
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License (available in the file LICENSE.TXT)
# for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.

import datetime

from GeoEco.DataManagement.ArcGISRasters import ArcGISRaster
from GeoEco.Datasets import Dataset, QueryableAttribute, Grid
from GeoEco.Datasets.OPeNDAP import THREDDSCatalog, OPeNDAPURL, OPeNDAPGrid
from GeoEco.DynamicDocString import DynamicDocString
from GeoEco.Internationalization import _


class _OSCAR5DayThirdDegreeCurrents4D(OPeNDAPGrid):
    __doc__ = DynamicDocString()

    def __init__(self, vectorComponent, timeout, maxRetryTime, cacheDirectory):
        self._CachedTCenterCoords = None
        super(_OSCAR5DayThirdDegreeCurrents4D, self).__init__(OPeNDAPURL('http://dapper.pmel.noaa.gov/dapper/oscar/world_sfc-third.nc', timeout=timeout, maxRetryTime=maxRetryTime, cacheDirectory=cacheDirectory),
                                                              vectorComponent,
                                                              'Grid',
                                                              lazyPropertyValues={'SpatialReference': Dataset.ConvertSpatialReference('proj4', '+proj=latlong +ellps=WGS84 +datum=WGS84 +no_defs', 'obj'),
                                                                                  'Dimensions': 'tzyx',
                                                                                  'CoordDependencies': (None, None, None, None),
                                                                                  'CoordIncrements': (None, 1., 1./3., 1./3.),
                                                                                  'TCornerCoordType': 'center',
                                                                                  'PhysicalDimensions': 'tzyx',
                                                                                  'PhysicalDimensionsFlipped': (False, False, False, False),
                                                                                  'UnscaledDataType': 'float32',
                                                                                  'UnscaledNoDataValue': -9999.,        # OSCAR uses NaN; we must convert it to -9999 because some callers cannot deal with NaN
                                                                                  'ScalingFunction': None})
        
    def _GetLazyPropertyPhysicalValue(self, name):

        # If the caller wants the CornerCoords, get the t coordinate
        # from the server (in case they change it) and use hard-coded
        # values for the rest (I feel confident they won't change
        # these).
        
        if name == 'CornerCoords':
            return (self._GetCoords('t', 0, [0], [0], 0.), 15.0, -80., 20.)       # Center of lower-left cell: 15 m deep, latitude -80, longitude +20

        # If the caller wants the shape, get it from the server but
        # take care to reduce the longitude shape so it does not
        # exceed 360 degrees. (OSCAR goes from 20 to 420, with 40
        # degrees of duplicated data.)

        if name == 'Shape':
            shape = super(_OSCAR5DayThirdDegreeCurrents4D, self)._GetLazyPropertyPhysicalValue('Shape')
            return (shape[0], 1, 481, 1080)

        # Otherwise get it from the server.

        return super(_OSCAR5DayThirdDegreeCurrents4D, self)._GetLazyPropertyPhysicalValue(name)

    def _GetCoords(self, coord, coordNum, slices, sliceDims, fixedIncrementOffset):
        if coord != 't':
            raise RuntimeError(_('_OSCAR5DayThirdDegreeCurrents4D._GetCoords() called with coord == \'%(coord)s\'. This should never happen. Please contact the author of this tool for assistance.') % {u'coord': coord})

        import numpy

        if self._CachedTCenterCoords is None:
            self.ParentCollection._Open()
            self._CachedTCenterCoords = numpy.array(map(lambda days: datetime.timedelta(int(days)) + datetime.datetime(1992, 10, 5), list(self.ParentCollection._PydapDataset['time'][:])), dtype='object')
            self._CachedTMinCoords = numpy.array([self._CachedTCenterCoords[0] - (self._CachedTCenterCoords[1] - self._CachedTCenterCoords[0])/2] + map(lambda a, b: a + (b-a)/2, self._CachedTCenterCoords[:-1], self._CachedTCenterCoords[1:]))
            self._CachedTMaxCoords = numpy.array(map(lambda a, b: a + (b-a)/2, self._CachedTCenterCoords[:-1], self._CachedTCenterCoords[1:]) + [self._CachedTCenterCoords[-1] + (self._CachedTCenterCoords[-1] - self._CachedTCenterCoords[-2])/2])

        if slices is None:
            if fixedIncrementOffset < 0:
                return self._CachedTMinCoords.copy()
            if fixedIncrementOffset == 0:
                return self._CachedTCenterCoords.copy()
            return self._CachedTMaxCoords.copy()
            
        if fixedIncrementOffset < 0:
            return self._CachedTMinCoords.__getitem__(*slices)
        if fixedIncrementOffset == 0:
            return self._CachedTCenterCoords.__getitem__(*slices)
        return self._CachedTMaxCoords.__getitem__(*slices)

    def _ReadNumpyArray(self, sliceList):

        # OSCAR uses NaN as the No Data value. Some of our callers
        # cannot deal with that so we convert it to -9999.

        import numpy

        data, noDataValue = super(_OSCAR5DayThirdDegreeCurrents4D, self)._ReadNumpyArray(sliceList)
        data[numpy.isnan(data)] = -9999.
        return data, -9999.


class OSCAR5DayThirdDegreeCurrents(Grid):
    __doc__ = DynamicDocString()

    def _GetParameter(self):
        return self._Parameter

    Parameter = property(_GetParameter, doc=DynamicDocString())

    def __init__(self, parameter, timeout=60, maxRetryTime=120, cacheDirectory=None):
        self.__doc__.Obj.ValidateMethodInvocation()

        # Initialize our properties.

        self._Parameter = parameter
        self._Timeout = timeout
        self._MaxRetryTime = maxRetryTime
        self._CacheDirectory = cacheDirectory
        self._Grid = None

        if parameter == u'eke':
            self._DisplayName = _(u'eddy kinetic energy calcuated from the OSCAR 5-day unfiltered 1/3 degree ocean surface currents')
        elif parameter == u'dir':
            self._DisplayName = _(u'direction of the OSCAR 5-day unfiltered 1/3 degree ocean surface currents')
        elif parameter == u'mag':
            self._DisplayName = _(u'magnitude of the OSCAR 5-day unfiltered 1/3 degree ocean surface currents')
        else:
            self._DisplayName = _(u'%(name)s component of the OSCAR 5-day unfiltered 1/3 degree ocean surface currents') % {u'name': parameter}

        # Initialize the base class.

        super(OSCAR5DayThirdDegreeCurrents, self).__init__(queryableAttributes=(QueryableAttribute(u'Parameter', _(u'Geophysical parameter'), UnicodeStringTypeMetadata(allowedValues=[u'dir', u'dir_anom', u'eke', u'mag', u'mag_anom', u'u', u'v', u'u_anom', u'v_anom'], makeLowercase=True)),),
                                                           queryableAttributeValues={u'Parameter': parameter},
                                                           lazyPropertyValues={'SpatialReference': Dataset.ConvertSpatialReference('proj4', '+proj=latlong +ellps=WGS84 +datum=WGS84 +no_defs', 'obj'),
                                                                               'Dimensions': u'tyx',
                                                                               'CoordDependencies': (None, None, None),
                                                                               'CoordIncrements': (None, 1./3., 1./3.),
                                                                               'TIncrementUnit': None,
                                                                               'TSemiRegularity': None,
                                                                               'TCountPerSemiRegularPeriod': None,
                                                                               'TCornerCoordType': u'center',
                                                                               'PhysicalDimensions': u'tyx',
                                                                               'PhysicalDimensionsFlipped': (False, True, False),
                                                                               'UnscaledDataType': u'float32',
                                                                               'UnscaledNoDataValue': -9999.,
                                                                               'ScalingFunction': None})

    def _Close(self):
        if hasattr(self, '_Grid') and self._Grid is not None:
            self._Grid.Close()
            self._Grid = None
        super(OSCAR5DayThirdDegreeCurrents, self)._Close()

    def _GetDisplayName(self):
        return self._DisplayName
        
    def _GetLazyPropertyPhysicalValue(self, name):

        # If the caller wants the CornerCoords or Shape, get them from
        # the contained 4D grid, dropping the z dimension.

        if name in ['CornerCoords', 'Shape']:
            if self._Grid is None:
                self._Grid = self._ConstructGridForParameter(self._Parameter, self._Timeout, self._MaxRetryTime, self._CacheDirectory)

            if name == 'CornerCoords':
                cornerCoords = self._Grid.GetLazyPropertyValue('CornerCoords')
                return (cornerCoords[0], cornerCoords[2], cornerCoords[3])

            if name == 'Shape':
                shape = self._Grid.Shape
                return (shape[0], shape[2], shape[3])

        return None

    def _GetCoords(self, coord, coordNum, slices, sliceDims, fixedIncrementOffset):

        # Get the t coordinates from the contained grid.
        
        if coord != 't':
            raise RuntimeError(_('OSCAR5DayThirdDegreeCurrents._GetCoords() called with coord == \'%(coord)s\'. This should never happen. Please contact the author of this tool for assistance.') % {u'coord': coord})

        if self._Grid is None:
            self._Grid = self._ConstructGridForParameter(self._Parameter, self._Timeout, self._MaxRetryTime, self._CacheDirectory)
        
        return self._Grid._GetCoords(coord, coordNum, slices, sliceDims, fixedIncrementOffset)

    def _ReadNumpyArray(self, sliceList):

        # The contained grid has four dimensions, while we only have
        # three. We want to omit the z dimension because it always has
        # a length of 1 (OSCAR only provides currents for the ocean
        # surface.)
        #
        # Add a z slice to the caller's sliceList, retrieve the slice,
        # and remove the z dimension from the returned 4D array before
        # returning it.

        if self._Grid is None:
            self._Grid = self._ConstructGridForParameter(self._Parameter, self._Timeout, self._MaxRetryTime, self._CacheDirectory)

        sliceList = [sliceList[0], slice(0, 1), sliceList[1], sliceList[2]]
        data, noDataValue = self._Grid._ReadNumpyArray(sliceList)
        return data.reshape(data.shape[0], data.shape[2], data.shape[3]), noDataValue

    @classmethod
    def _ConstructGridForParameter(cls, parameter, timeout, maxRetryTime, cacheDirectory):

        # If the caller just wants u, v, u_anom, or v_anom, construct
        # and return a _OSCAR5DayThirdDegreeCurrents4D instance.
        
        if parameter in [u'u', u'v', u'u_anom', u'v_anom']:
            return _OSCAR5DayThirdDegreeCurrents4D(parameter, timeout, maxRetryTime, cacheDirectory)

        # The caller wants something derived from both u and v. First
        # create u and v component grids.

        if parameter.endswith('_anom'):
            uGrid = _OSCAR5DayThirdDegreeCurrents4D(u'u_anom', timeout, maxRetryTime, cacheDirectory)
            vGrid = _OSCAR5DayThirdDegreeCurrents4D(u'v_anom', timeout, maxRetryTime, cacheDirectory)
        else:
            uGrid = _OSCAR5DayThirdDegreeCurrents4D(u'u', timeout, maxRetryTime, cacheDirectory)
            vGrid = _OSCAR5DayThirdDegreeCurrents4D(u'v', timeout, maxRetryTime, cacheDirectory)

        # Now construct and return the appropriate DerivedGrid
        # instance.

        qav = {}
        for qa in uGrid.GetAllQueryableAttributes():
            qav[qa.Name] = uGrid.GetQueryableAttributeValue(qa.Name)
        qav[u'Parameter'] = parameter

        from GeoEco.Datasets.Virtual import DerivedGrid

        if parameter in [u'dir', u'dir_anom']:
            return DerivedGrid([uGrid, vGrid],
                               'numpy.arctan2(0 - self._Grids[0].Data.__getitem__(tuple(sliceList)), 0 - self._Grids[1].Data.__getitem__(tuple(sliceList))) / numpy.pi * 180 + 180',    # north = 0, east = 90, south = 180, west = 270
                               _(u'OSCAR %(parameter)s') % {u'parameter': parameter},
                               u'float32',
                               noDataValue=uGrid.NoDataValue,
                               queryableAttributes=tuple(uGrid.GetAllQueryableAttributes()),
                               queryableAttributeValues=qav)

        if parameter == u'eke':
            return DerivedGrid([uGrid, vGrid],
                               '0.5 * (self._Grids[0].Data.__getitem__(tuple(sliceList))**2 + self._Grids[1].Data.__getitem__(tuple(sliceList))**2)',
                               _(u'OSCAR %(parameter)s') % {u'parameter': parameter},
                               u'float32',
                               noDataValue=uGrid.NoDataValue,
                               queryableAttributes=tuple(uGrid.GetAllQueryableAttributes()),
                               queryableAttributeValues=qav)

        if parameter in [u'mag', u'mag_anom']:
            return DerivedGrid([uGrid, vGrid],
                               '(self._Grids[0].Data.__getitem__(tuple(sliceList))**2 + self._Grids[1].Data.__getitem__(tuple(sliceList))**2) ** 0.5',
                               _(u'OSCAR %(parameter)s') % {u'parameter': parameter},
                               u'float32',
                               noDataValue=uGrid.NoDataValue,
                               queryableAttributes=tuple(uGrid.GetAllQueryableAttributes()),
                               queryableAttributeValues=qav)
            
        raise RuntimeError(_(u'Programming error in this tool: OSCAR5DayThirdDegreeCurrents._ConstructGridForParameter() does not recognize parameter "%(parameter)s". Please contact the author of this tool for assistance.') % {u'parameter': parameter})

    @classmethod
    def _RotateAndClip(cls, grid, rotationOffset, spatialExtent, startDate, endDate):
        from GeoEco.Datasets.Virtual import RotatedGlobalGrid, ClippedGrid
        
        # Rotate the grid, if requested.
        
        if rotationOffset is not None:
            grid = RotatedGlobalGrid(grid, rotationOffset, u'Map units')

        # Clip the grid, if requested.
        
        if spatialExtent is not None or startDate is not None or endDate is not None:
            xMin, yMin, xMax, yMax = None, None, None, None
            if spatialExtent is not None:
                from GeoEco.Types import EnvelopeTypeMetadata
                xMin, yMin, xMax, yMax = EnvelopeTypeMetadata.ParseFromArcGISString(spatialExtent)

            if startDate is not None:
                startDate = datetime.datetime(startDate.year, startDate.month, startDate.day, 0, 0, 0)

            if endDate is not None:
                endDate = datetime.datetime(endDate.year, endDate.month, endDate.day, 23, 59, 59)
                
            grid = ClippedGrid(grid, u'Map coordinates', xMin=xMin, xMax=xMax, yMin=yMin, yMax=yMax, tMin=startDate, tMax=endDate)

        # Return the grid.

        return grid

    @classmethod
    def CreateArcGISRasters(cls, parameter,
                            outputWorkspace, mode=u'add', rasterNameExpressions=['%(Parameter)s', '%%Y', '%(Parameter)s_%%Y%%j.img'],
                            rotationOffset=None, spatialExtent=None, startDate=None, endDate=None,
                            timeout=60, maxRetryTime=120, cacheDirectory=None,
                            calculateStatistics=True, buildPyramids=False):
        cls.__doc__.Obj.ValidateMethodInvocation()
        grid = OSCAR5DayThirdDegreeCurrents(parameter, timeout, maxRetryTime, cacheDirectory)
        try:
            from GeoEco.Datasets.ArcGIS import ArcGISWorkspace, ArcGISRaster
            from GeoEco.Datasets.Virtual import GridSliceCollection
            grid = cls._RotateAndClip(grid, rotationOffset, spatialExtent, startDate, endDate)
            workspace = ArcGISWorkspace(outputWorkspace, ArcGISRaster, pathCreationExpressions=rasterNameExpressions, cacheTree=True, queryableAttributes=tuple(grid.GetAllQueryableAttributes() + [QueryableAttribute(u'DateTime', _(u'Date'), DateTimeTypeMetadata())]))
            workspace.ImportDatasets(GridSliceCollection(grid, tQACoordType=u'center').QueryDatasets(), mode, calculateStatistics=calculateStatistics, buildPyramids=buildPyramids)
        finally:
            grid.Close()
        return outputWorkspace

    @classmethod
    def CreateClimatologicalArcGISRasters(cls, parameter,
                                          statistic, binType,
                                          outputWorkspace, mode=u'add', rasterNameExpressions=['%(Parameter)s', u'%(ClimatologyBinType)s_Climatology', u'%(Parameter)s_%(ClimatologyBinName)s_%(Statistic)s.img'],
                                          binDuration=1, startDayOfYear=1,
                                          rotationOffset=None, spatialExtent=None, startDate=None, endDate=None,
                                          timeout=60, maxRetryTime=120, cacheDirectory=None,
                                          calculateStatistics=True, buildPyramids=False):
        cls.__doc__.Obj.ValidateMethodInvocation()
        grid = OSCAR5DayThirdDegreeCurrents(parameter, timeout, maxRetryTime, cacheDirectory)
        try:
            from GeoEco.Datasets.ArcGIS import ArcGISWorkspace, ArcGISRaster
            from GeoEco.Datasets.Virtual import ClimatologicalGridCollection
            grid = cls._RotateAndClip(grid, rotationOffset, spatialExtent, startDate, endDate)
            collection = ClimatologicalGridCollection(grid, statistic, binType, binDuration, startDayOfYear, reportProgress=True)
            workspace = ArcGISWorkspace(outputWorkspace, ArcGISRaster, pathCreationExpressions=rasterNameExpressions, cacheTree=True, queryableAttributes=tuple(collection.GetAllQueryableAttributes()))
            workspace.ImportDatasets(collection.QueryDatasets(), mode, calculateStatistics=calculateStatistics, buildPyramids=buildPyramids)
        finally:
            grid.Close()
        return outputWorkspace

    @classmethod
    def CreateVectorsAsArcGISFeatureClasses(cls, outputWorkspace, mode=u'add', featureClassNameExpressions=['uv_vectors', '%%Y', 'uv_vectors_%%Y%%j.shp'],
                                            scaleFactor=0.444, uniformLength=False,
                                            rotationOffset=None, spatialExtent=None, startDate=None, endDate=None,
                                            timeout=60, maxRetryTime=120, cacheDirectory=None):
        cls.__doc__.Obj.ValidateMethodInvocation()

        # Create u and v component grids.
        
        uGrid = OSCAR5DayThirdDegreeCurrents(u'u', timeout, maxRetryTime, cacheDirectory)
        try:
            vGrid = OSCAR5DayThirdDegreeCurrents(u'v', timeout, maxRetryTime, cacheDirectory)
            try:
                uGrid = cls._RotateAndClip(uGrid, rotationOffset, spatialExtent, startDate, endDate)
                vGrid = cls._RotateAndClip(vGrid, rotationOffset, spatialExtent, startDate, endDate)

                # Query for parallel lists of 2D u and v grid slices.

                from GeoEco.Datasets.Virtual import GridSliceCollection

                uSlices = GridSliceCollection(uGrid, tQACoordType=u'center').QueryDatasets()
                vSlices = GridSliceCollection(vGrid, tQACoordType=u'center').QueryDatasets()

                # Construct a list of
                # ShapefileFromVectorComponentGrids from the slices.

                from GeoEco.SpatialAnalysis.Lines import ShapefileFromVectorComponentGrids

                queryableAttributes = tuple(uGrid.GetAllQueryableAttributes() + [QueryableAttribute(u'DateTime', _(u'Date'), DateTimeTypeMetadata())])
                vectorShapefiles = []

                for i in range(len(uSlices)):
                    queryableAttributeValues = {}
                    for qa in queryableAttributes:
                        queryableAttributeValues[qa.Name] = uSlices[i].GetQueryableAttributeValue(qa.Name)

                    vectorShapefiles.append(ShapefileFromVectorComponentGrids(uSlices[i], vSlices[i], scaleFactor, uniformLength, queryableAttributes=queryableAttributes, queryableAttributeValues=queryableAttributeValues))

                # Import the ShapefileFromVectorComponentGrids into
                # the output workspace.

                from GeoEco.Datasets.ArcGIS import ArcGISWorkspace, ArcGISTable

                workspace = ArcGISWorkspace(outputWorkspace, ArcGISTable, pathCreationExpressions=featureClassNameExpressions, cacheTree=True, queryableAttributes=queryableAttributes)
                workspace.ImportDatasets(vectorShapefiles, mode)

                # Return successfully.
                
                return outputWorkspace

            finally:
                vGrid.Close()
        finally:
            uGrid.Close()

    @classmethod
    def InterpolateAtArcGISPoints(cls, parameter,
                                   points, valueField, tField, method=u'Nearest', where=None, noDataValue=None,
                                   timeout=60, maxRetryTime=120, cacheDirectory=None,
                                   orderByFields=None, numBlocksToCacheInMemory=128, xBlockSize=16, yBlockSize=16, tBlockSize=3):
        cls.__doc__.Obj.ValidateMethodInvocation()
        grid = OSCAR5DayThirdDegreeCurrents(parameter, timeout, maxRetryTime, cacheDirectory)
        try:
            if orderByFields is not None:
                orderBy = u', '.join(map(lambda f: f + u' ASC', orderByFields))
            else:
                from GeoEco.ArcGIS import GeoprocessorManager
                if GeoprocessorManager.GetArcGISMajorVersion() > 9 or GeoprocessorManager.GetArcGISMinorVersion() >= 2:
                    orderBy = tField + u' ASC'
                else:
                    orderBy = None
            from GeoEco.Datasets.ArcGIS import ArcGISTable
            from GeoEco.SpatialAnalysis.Interpolation import Interpolator
            Interpolator.InterpolateGridsValuesForTableOfPoints([grid], ArcGISTable(points), [valueField], tField=tField, where=where, orderBy=orderBy, method=method, noDataValue=noDataValue, gridsWrap=True, numBlocksToCacheInMemory=numBlocksToCacheInMemory, xBlockSize=xBlockSize, yBlockSize=yBlockSize, tBlockSize=tBlockSize)
        finally:
            grid.Close()
        return points


###############################################################################
# Metadata: module
###############################################################################

from GeoEco.ArcGIS import ArcGISDependency
from GeoEco.Datasets.ArcGIS import _CalculateStatisticsDescription, _BuildPyramidsDescription
from GeoEco.Dependencies import PythonAggregatedModuleDependency
from GeoEco.Metadata import *
from GeoEco.OceanographicAnalysis.Eddies import OkuboWeissEddies, _OkuboWeissAlgorithmDescription, _OkuboWeissReferences
from GeoEco.Types import *

AddModuleMetadata(shortDescription=_(u'Methods for accessing the NOAA Ocean Surface Current Analyses - Real time (OSCAR) dataset (http://www.oscar.noaa.gov).'))

###############################################################################
# Metadata: _OSCAR5DayThirdDegreeCurrents4D class
###############################################################################

AddClassMetadata(_OSCAR5DayThirdDegreeCurrents4D,
    shortDescription=_(u'An OPeNDAPGrid for the NOAA OSCAR 5-day unfiltered 1/3 degree ocean surface currents dataset.'),
    longDescription=_(
u"""This class is intended for private use within GeoEco and is not
intended for external callers."""))

_OSCAR_LongDescription = _(
u"""The `NOAA Ocean Surface Current Analyses - Real Time (OSCAR) <http://www.oscar.noaa.gov/>`_
project publishes global estimates of ocean surface currents by
combining satellite observations from altimeters that measure the
height of the sea surface (e.g. TOPEX/Poseidon), scatterometers that
estimate ocean wind vectors (e.g. QuikSCAT), and sea surface
temperature sensors (e.g. AVHRR). The goal is to provide ocean current
estimates that are more accurate than those based on altimetry alone,
particularly in tropical regions, by combining geostrophic, Ekman, and
Stommel shear dynamics and a complementary term from the surface
buoyancy gradient (Bonjean and Lagerloef, 2002).

This %(name)s accesses a long term archive of OSCAR's 5-day unfiltered
1/3 degree global product. This product begins 21 October 1992 and
continues to be updated through the present day. Although the R in
OSCAR stands for "real time", it does not appear that the archive is
updated on a real time basis. The data may be weeks or months behind.

Although the time increment for this product is listed as 5 days,
images occasionally occur 6 days apart according to a regular pattern.

This product is provided in a geographic projection with a cell size
of 1/3 degree. It encompasses latitudes 80 N to 80 S and 360 degrees
of longitude. The images are centered on approximately 160 W to
provide an uninterrupted view of the tropical Indian, Pacific, and
Atlantic Oceans.

The OSCAR OPeNDAP dataset accessed by this %(name)s is
http://dapper.pmel.noaa.gov/dapper/oscar/world_sfc-third.nc.

**References**

Bonjean, F. and Lagerloef, G.S.E. (2002) Diagnostic Model and Analysis
of the Surface Currents in the Tropical Pacific Ocean. J. Physical
Oceano. 32(10):2938-2954.

Please see the `OSCAR Bibliography <http://www.oscar.noaa.gov/pubs.html>`_
for a complete list of OSCAR publications. Bonjean and Lagerloef
(2002) appears to be the seminal OSCAR paper.

The OSCAR website requests that you acknowledge your use of the data.
Please see the website for specific instructions (they may appear
`here <http://www.oscar.noaa.gov/datadisplay/oscar_datadownload.php>`_).""")

###############################################################################
# Metadata: OSCAR5DayThirdDegreeCurrents class
###############################################################################

AddClassMetadata(OSCAR5DayThirdDegreeCurrents,
    shortDescription=_(u'A 3D Grid representing the NOAA OSCAR 5-day unfiltered 1/3 degree ocean surface currents.'),
    longDescription=_OSCAR_LongDescription % {u'name': 'class'})

# Constructor

AddMethodMetadata(OSCAR5DayThirdDegreeCurrents.__init__,
    shortDescription=_(u'Constructs a new OSCAR5DayThirdDegreeCurrents instance.'),
    isExposedToPythonCallers=True,
    dependencies=[PythonAggregatedModuleDependency('numpy')])

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.__init__, u'self',
    typeMetadata=ClassInstanceTypeMetadata(cls=OSCAR5DayThirdDegreeCurrents),
    description=_(u'OSCAR5DayThirdDegreeCurrents instance.'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.__init__, u'parameter',
    typeMetadata=UnicodeStringTypeMetadata(allowedValues=[u'dir', u'dir_anom', u'eke', u'mag', u'mag_anom', u'u', u'v', u'u_anom', u'v_anom'], makeLowercase=True),
    description=_(
u"""Geophysical parameter to use, one of:

* dir - Direction of water flow, in degrees. Due north is 0, due east
  is 90, due south is 180, due west is 270.

* dir_anom - Direction of water flow (from u_anom and v_anom).

* eke - Eddy kinetic energy, in m^2/s^2, computed as 0.5*(u^2 + v^2).

* mag - Absolute magnitude (or modulus) of the water velocity vector,
  in m/s.

* mag_anom - Absolute magnitude of water velocity (from u_anom and
  v_anom).

* u - Eastward sea water velocity, in m/s.

* v - Northward sea water velocity, in m/s.

* u_anom - Eastward sea water velocity anomaly, in m/s.

* v_anom - Northward sea water velocity anomaly, in m/s.

The anomalies are the difference between the velocity on that date and
the long term mean velocity. The mean is usually computed over all of
the years that have complete data. For example, at the time this tool
was developed in late 2011, the mean was computed over 1993-2010,
inclusive. (1992 and 2011 were excluded, presumably because they were
incomplete years.)

Please see the OSCAR documentation for more information about these
variables."""),
    arcGISDisplayName=_(u'Geophysical parameter'))

CopyArgumentMetadata(THREDDSCatalog.__init__, u'timeout', OSCAR5DayThirdDegreeCurrents.__init__, u'timeout')
CopyArgumentMetadata(THREDDSCatalog.__init__, u'maxRetryTime', OSCAR5DayThirdDegreeCurrents.__init__, u'maxRetryTime')
CopyArgumentMetadata(THREDDSCatalog.__init__, u'cacheDirectory', OSCAR5DayThirdDegreeCurrents.__init__, u'cacheDirectory')

AddResultMetadata(OSCAR5DayThirdDegreeCurrents.__init__, u'grid',
    typeMetadata=ClassInstanceTypeMetadata(cls=OSCAR5DayThirdDegreeCurrents),
    description=_(u'OSCAR5DayThirdDegreeCurrents instance.'))

# Public method: OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters

AddMethodMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters,
    shortDescription=_(u'Creates rasters for NOAA OSCAR 5-day unfiltered 1/3 degree ocean surface currents.'),
    longDescription=_OSCAR_LongDescription % {u'name': 'tool'},
    isExposedToPythonCallers=True,
    isExposedByCOM=True,
    isExposedAsArcGISTool=True,
    arcGISDisplayName=_(u'Create Rasters for OSCAR Currents'),
    arcGISToolCategory=_(u'Data Products\\NOAA OSCAR'),
    dependencies=[ArcGISDependency(9, 1), PythonAggregatedModuleDependency('numpy')])

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'cls',
    typeMetadata=ClassOrClassInstanceTypeMetadata(cls=OSCAR5DayThirdDegreeCurrents),
    description=_(u'OSCAR5DayThirdDegreeCurrents class or instance.'))

CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.__init__, u'parameter', OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'parameter')

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'outputWorkspace',
    typeMetadata=ArcGISWorkspaceTypeMetadata(createParentDirectories=True),
    description=_(
u"""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."""),
    arcGISDisplayName=_(u'Output workspace'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'mode',
    typeMetadata=UnicodeStringTypeMetadata(allowedValues=[u'Add', u'Replace'], makeLowercase=True),
    description=_(
u"""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 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."""),
    arcGISDisplayName=_(u'Overwrite mode'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'rasterNameExpressions',
    typeMetadata=ListTypeMetadata(elementType=UnicodeStringTypeMetadata(), minLength=1),
    description=_(
u"""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
the geophysical parameter and year. 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:

* %(Parameter)s - Geophysical parameter represented by the the output
  raster, either "dir", "dir_anom", "eke", "mag", "mag_anom", "u",
  "v", "u_anom", or "v_anom".

* %%Y - four-digit year of the raster.

* %%m - two-digit month of the raster.

* %%d - two-digit day of the month of the raster.

* %%j - three-digit day of the year of the raster.
"""),
    arcGISDisplayName=_(u'Raster name expressions'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'rotationOffset',
    typeMetadata=FloatTypeMetadata(canBeNone=True),
    description=_(
u"""Angle to rotate the outputs about the polar axis, in degrees. If
not provided, the outputs will be centered on 160.16666666666666 W
(the Pacific Ocean).

Use this parameter to shift the center longitude of the outputs to a
different location. Positive values shift it to the east, negative
values to the west. For example, to center the outputs close to the
Prime Meridian, provide -200 for this parameter. (Note that it is not
possible to center the outputs exactly on the Prime Meridian because
the OSCAR grid is offset by 1/6 degree from it.)

The outputs can only be rotated in whole cells of the OSCAR grids,
which are 1/3 degree wide. The value you provide will be rounded off
to the closest cell."""),
    arcGISDisplayName=_(u'Rotate by'),
    arcGISCategory=_(u'Spatiotemporal extent'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'spatialExtent',
    typeMetadata=EnvelopeTypeMetadata(canBeNone=True),
    description=_(
u"""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, which are 1/3
degree wide. The values you provide will be rounded off to the closest
cell."""),
    arcGISDisplayName=_(u'Spatial extent'),
    arcGISCategory=_(u'Spatiotemporal extent'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'startDate',
    typeMetadata=DateTimeTypeMetadata(canBeNone=True),
    description=_(
u"""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 image will be used, which is
usually 21 October 1992.

The time component of the start date is ignored."""),
    arcGISDisplayName=_(u'Start date'),
    arcGISCategory=_(u'Spatiotemporal extent'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'endDate',
    typeMetadata=DateTimeTypeMetadata(canBeNone=True),
    description=_(
u"""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 image will be used. The OSCAR OPeNDAP
dataset that is accessed is a long term archive that may not be
updated daily. For example, when this tool was written in late 2011,
the archive ended in September 2011.

The time component of the end date is ignored."""),
    arcGISDisplayName=_(u'End date'),
    arcGISCategory=_(u'Spatiotemporal extent'))

CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.__init__, u'timeout', OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'timeout')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.__init__, u'maxRetryTime', OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'maxRetryTime')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.__init__, u'cacheDirectory', OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'cacheDirectory')

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'calculateStatistics',
    typeMetadata=BooleanTypeMetadata(),
    description=_CalculateStatisticsDescription,
    arcGISDisplayName=_(u'Calculate statistics'),
    arcGISCategory=_(u'Additional raster processing options'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'buildPyramids',
    typeMetadata=BooleanTypeMetadata(),
    description=_BuildPyramidsDescription,
    arcGISDisplayName=_(u'Build pyramids'),
    arcGISCategory=_(u'Additional raster processing options'))

AddResultMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'updatedOutputWorkspace',
    typeMetadata=ArcGISWorkspaceTypeMetadata(),
    description=_(u'Updated output workspace.'),
    arcGISDisplayName=_(u'Updated output workspace'),
    arcGISParameterDependencies=[u'outputWorkspace'])

# Public method: OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters

AddMethodMetadata(OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters,
    shortDescription=_(u'Creates climatological rasters for NOAA OSCAR 5-day unfiltered 1/3 degree ocean surface currents.'),
    longDescription=_OSCAR_LongDescription % {u'name': 'tool'},
    isExposedToPythonCallers=True,
    isExposedByCOM=True,
    isExposedAsArcGISTool=True,
    arcGISDisplayName=_(u'Create Climatological Rasters for OSCAR Currents'),
    arcGISToolCategory=_(u'Data Products\\NOAA OSCAR'),
    dependencies=[ArcGISDependency(9, 1), PythonAggregatedModuleDependency('numpy')])

CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'cls', OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters, u'cls')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'parameter', OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters, u'parameter')

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters, u'statistic',
    typeMetadata=UnicodeStringTypeMetadata(allowedValues=[u'Count', u'Maximum', u'Mean', u'Minimum', u'Range', u'Standard Deviation', u'Sum'], makeLowercase=True),
    description=_(
u"""Statistic to calculate for each cell, one of:

* Count - number of images 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 images with
  data for the cell.

* Sum - the sum for the cell.
"""),
    arcGISDisplayName=_(u'Statistic'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters, u'binType',
    typeMetadata=UnicodeStringTypeMetadata(allowedValues=[u'Daily', u'Monthly', u'Cumulative'], makeLowercase=True),
    description=_(
u"""Climatology bins to use, one of:

* Daily - daily bins. Images will be classified into bins according to
  their days of the year. The number of days in each bin is determined
  by the Climatology Bin Duration parameter (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;
  images for the 366th day of leap years will be counted in the bin
  that includes day 365. For example, if the bin duration is 15, 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. Images will be classified into bins according to
  their months of the year. The number of months in each bin is
  determined by the Climatology Bin Duration parameter (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 parameter is ignored.

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."""),
    arcGISDisplayName=_(u'Climatology bin type'))

CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'outputWorkspace', OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters, u'outputWorkspace')

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters, u'mode',
    typeMetadata=UnicodeStringTypeMetadata(allowedValues=[u'Add', u'Replace'], makeLowercase=True),
    description=_(
u"""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. Choose this option when you want to regenerate the
  climatologies using the latest OSCAR data.

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."""),
    arcGISDisplayName=_(u'Overwrite mode'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters, u'rasterNameExpressions',
    typeMetadata=ListTypeMetadata(elementType=UnicodeStringTypeMetadata(), minLength=1),
    description=_(
u"""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
the geophysical parameter and climatology 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:

* %(Parameter)s - Geophysical parameter represented by the the output
  raster, either "dir", "dir_anom", "eke", "mag", "mag_anom", "u",
  "v", "u_anom", or "v_anom".

* %(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".

* %(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".

* %(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
"""),
    arcGISDisplayName=_(u'Raster name expressions'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters, u'binDuration',
    typeMetadata=IntegerTypeMetadata(minValue=1),
    description=_(
u"""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."""),
    arcGISDisplayName=_(u'Climatology bin duration'),
    arcGISCategory=_(u'Climatology options'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters, u'startDayOfYear',
    typeMetadata=IntegerTypeMetadata(minValue=1, maxValue=365),
    description=_(
u"""Use this parameter to create bin defintions that deviate from the
traditional calendar. The interpretation of this parameter depends on
the Bin Type:

* Daily - this parameter defines the day of the year of the first
  climatology bin. For example, if this parameter 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.

* Monthly - this parameter 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
  this parameter 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 this
  parameter 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.

* Cumulative - this parameter is ignored.
"""),
    arcGISDisplayName=_(u'Start climatology at this day of the year'),
    arcGISCategory=_(u'Climatology options'))

CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'rotationOffset', OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters, u'rotationOffset')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'spatialExtent', OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters, u'spatialExtent')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'startDate', OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters, u'startDate')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'endDate', OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters, u'endDate')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'timeout', OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters, u'timeout')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'maxRetryTime', OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters, u'maxRetryTime')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'cacheDirectory', OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters, u'cacheDirectory')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'calculateStatistics', OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters, u'calculateStatistics')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'buildPyramids', OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters, u'buildPyramids')

CopyResultMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'updatedOutputWorkspace', OSCAR5DayThirdDegreeCurrents.CreateClimatologicalArcGISRasters, u'updatedOutputWorkspace')

# Public method: OSCAR5DayThirdDegreeCurrents.CreateVectorsAsArcGISFeatureClasses

AddMethodMetadata(OSCAR5DayThirdDegreeCurrents.CreateVectorsAsArcGISFeatureClasses,
    shortDescription=_(u'Creates line feature classes representing the vectors of NOAA OSCAR 5-day unfiltered 1/3 degree ocean surface currents.'),
    longDescription=_(
u"""The lines output by this tool are similar to those in a "quiver
plot". When displayed on a map, they can help visualize the direction
and speed of ocean currents. In ArcMap, select the "Arrow at End"
symbology. You may also want to reduce the line decoration (the arrow)
to a small size, such as 2.0.

""") + _OSCAR_LongDescription % {u'name': 'tool'},
    isExposedToPythonCallers=True,
    isExposedByCOM=True,
    isExposedAsArcGISTool=True,
    arcGISDisplayName=_(u'Create Vectors for OSCAR Currents'),
    arcGISToolCategory=_(u'Data Products\\NOAA OSCAR'),
    dependencies=[ArcGISDependency(9, 1), PythonAggregatedModuleDependency('numpy')])

CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'cls', OSCAR5DayThirdDegreeCurrents.CreateVectorsAsArcGISFeatureClasses, u'cls')

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateVectorsAsArcGISFeatureClasses, u'outputWorkspace',
    typeMetadata=ArcGISWorkspaceTypeMetadata(createParentDirectories=True),
    description=_(
u"""Directory or geodatabase to receive the feature classes.

Unless you have a specific reason to store the feature classes in a
geodatabase, we recommend you store them in a directory because it
will be faster and allows them to be organized as a tree (of
shapefiles). If you do store the feature classes in a geodatabase, you
must change the Feature Class Name Expressions parameter; see below
for more information."""),
    arcGISDisplayName=_(u'Output workspace'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateVectorsAsArcGISFeatureClasses, u'mode',
    typeMetadata=UnicodeStringTypeMetadata(allowedValues=[u'Add', u'Replace'], makeLowercase=True),
    description=_(
u"""Overwrite mode, one of:

* Add - create feature classes that do not exist and skip those that
  already exist. This is the default.

* Replace - create feature classes that do not exist and overwrite
  those that already exist.

The ArcGIS Overwrite Outputs geoprocessing setting has no effect on
this tool. If 'Replace' is selected the feature classes will be
overwritten, regardless of the ArcGIS Overwrite Outputs setting."""),
    arcGISDisplayName=_(u'Overwrite mode'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateVectorsAsArcGISFeatureClasses, u'featureClassNameExpressions',
    typeMetadata=ListTypeMetadata(elementType=UnicodeStringTypeMetadata(), minLength=1),
    description=_(
u"""List of expressions specifying how the output feature classes
should be named.

The default expression assumes the output workspace is a directory and
creates shapefiles in a "uv_vectors" subdirectory with a subdirectory
level below that for each year.

If the output workspace is a geodatabase, you should provide only one
or two expressions. If you provide one expression, it specifies the
feature class name. If you provide two, the first one specifies the
feature dataset name and the second specifies the feature class 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 feature class:

* %%Y - four-digit year of the output feature class.

* %%m - two-digit month of the output feature class.

* %%d - two-digit day of the month of the output feature class.

* %%j - three-digit day of the year of the output feature class.
"""),
    arcGISDisplayName=_(u'Feature class name expressions'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateVectorsAsArcGISFeatureClasses, u'scaleFactor',
    typeMetadata=FloatTypeMetadata(mustBeGreaterThan=0.0),
    description=_(
u"""Factor for scaling lines lengths.

Use this parameter to scale the lines output by this tool to lengths
that are visually appealing. If the lines are too short, they will
resemble a grid of dots and you will not be able to discern the flow
of the vector field. If the lines are too long, they will overlap each
other and resemble a plate of spaghetti.

If the vectors all have about the same magnitude, then a good approach
is to scale the lines so that the longest one is about as long as the
raster cell size. But if there are a few very long vectors, then you
may prefer to scale the lines so that the average-length vector is as
long as the raster cell size.

For OSCAR geostrophic currents, the raster cell size is 1/3 degree and
currents are given in m/s. So, if the maximum (or mean) velocity in
your region of interest is about 0.75 m/s:

    scale factor = 0.333 / 0.75 = 0.444
"""),
    arcGISDisplayName=_(u'Scale factor'),
    arcGISCategory=_(u'Vector options'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateVectorsAsArcGISFeatureClasses, u'uniformLength',
    typeMetadata=BooleanTypeMetadata(),
    description=_(
u"""If False (the default) then the lengths of the lines are
determined by multiplying the magnitude of the vector by the Scale
Factor parameter.

If True, all lines will have the same length, which will be determined
by multiplying the cell size of the OSCAR grids (i.e. 1/3 degree) by
the the Scale Factor. Use this option when you want to the lines'
colors to indicate the magnitude of the vector, rather than the lines'
lengths. Start with a Scale Factor of 1 and increase it or decrease it
slightly to achieve the desired visual effect."""),
    arcGISDisplayName=_(u'Create all lines with the same length'),
    arcGISCategory=_(u'Vector options'))

CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'rotationOffset', OSCAR5DayThirdDegreeCurrents.CreateVectorsAsArcGISFeatureClasses, u'rotationOffset')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'spatialExtent', OSCAR5DayThirdDegreeCurrents.CreateVectorsAsArcGISFeatureClasses, u'spatialExtent')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'startDate', OSCAR5DayThirdDegreeCurrents.CreateVectorsAsArcGISFeatureClasses, u'startDate')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'endDate', OSCAR5DayThirdDegreeCurrents.CreateVectorsAsArcGISFeatureClasses, u'endDate')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'timeout', OSCAR5DayThirdDegreeCurrents.CreateVectorsAsArcGISFeatureClasses, u'timeout')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'maxRetryTime', OSCAR5DayThirdDegreeCurrents.CreateVectorsAsArcGISFeatureClasses, u'maxRetryTime')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'cacheDirectory', OSCAR5DayThirdDegreeCurrents.CreateVectorsAsArcGISFeatureClasses, u'cacheDirectory')

CopyResultMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'updatedOutputWorkspace', OSCAR5DayThirdDegreeCurrents.CreateVectorsAsArcGISFeatureClasses, u'updatedOutputWorkspace')

# Public method: OSCAR5DayThirdDegreeCurrents.InterpolateAtArcGISPoints

AddMethodMetadata(OSCAR5DayThirdDegreeCurrents.InterpolateAtArcGISPoints,
    shortDescription=_(u'Interpolates the values of NOAA OSCAR 5-day unfiltered 1/3 degree ocean surface currents at points.'),
    longDescription=_(
u"""This tool performs the same basic operation as the ArcGIS Spatial
Analyst's Extract Values to Points tool, but it reads data directly
from OSCAR's server using the `OPeNDAP <http://opendap.org/>`_
protocol, rather than reading rasters stored on your machine.

""") + _OSCAR_LongDescription % {u'name': 'tool'},
    isExposedToPythonCallers=True,
    isExposedByCOM=True,
    isExposedAsArcGISTool=True,
    arcGISDisplayName=_(u'Interpolate OSCAR Currents at Points'),
    arcGISToolCategory=_(u'Data Products\\NOAA OSCAR'),
    dependencies=[ArcGISDependency(9, 1), PythonAggregatedModuleDependency('numpy')])

CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'cls', OSCAR5DayThirdDegreeCurrents.InterpolateAtArcGISPoints, u'cls')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'parameter', OSCAR5DayThirdDegreeCurrents.InterpolateAtArcGISPoints, u'parameter')

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.InterpolateAtArcGISPoints, u'points',
    typeMetadata=ArcGISFeatureLayerTypeMetadata(mustExist=True, allowedShapeTypes=[u'Point']),
    description=_(u'Points at which values should be interpolated.'),
    arcGISDisplayName=_(u'Point features'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.InterpolateAtArcGISPoints, u'valueField',
    typeMetadata=ArcGISFieldTypeMetadata(mustExist=True, allowedFieldTypes=[u'short', u'long', u'float', u'double']),
    description=_(
u"""Field of the points to receive the interpolated values.

The field must have a floating-point or integer data type. If the
field cannot represent the interpolated value at full precision, the
closest approximation will be stored and a warning will be issued.
This will happen, for example, when you interpolate values into an
integer field."""),
    arcGISDisplayName=_(u'Field to receive the interpolated values'),
    arcGISParameterDependencies=[u'points'])

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.InterpolateAtArcGISPoints, u'tField',
    typeMetadata=ArcGISFieldTypeMetadata(mustExist=True, allowedFieldTypes=[u'date']),
    description=_(
u"""Field of the points that specifies the date and time of the point.

The field must have a date or datetime data type. If the field can
only represent dates with no time component, the time will assumed to
be 00:00:00.

The OSCAR products use the UTC time zone, and it is assumed that the
points do as well."""),
    arcGISDisplayName=_(u'Date field'),
    arcGISParameterDependencies=[u'points'])

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.InterpolateAtArcGISPoints, u'method',
    typeMetadata=UnicodeStringTypeMetadata(allowedValues=[u'Nearest', u'Linear'], makeLowercase=True),
    description=_(
u"""Interpolation method to use, one of:

* Nearest - nearest neighbor interpolation. The interpolated value
  will simply be the value of the cell that contains the point. This
  is the default.

* Linear - linear interpolation (also known as trilinear
  interpolation). This method averages the values of the eight nearest
  cells in the x, y, and time dimensions, weighting the contribution
  of each cell by the area of it that would be covered by a
  hypothetical cell centered on the point being interpolated. If the
  cell containing the point contains NoData, the result is NoData. If
  any of the other seven cells contain NoData, they are omitted from
  the average, and the result is based on the weighted average of the
  cells that do contain data. This is the same algorithm implemented
  by the ArcGIS Spatial Analyst's Extract Values to Points tool.
"""),
    arcGISDisplayName=_(u'Interpolation method'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.InterpolateAtArcGISPoints, u'where',
    typeMetadata=SQLWhereClauseTypeMetadata(canBeNone=True),
    description=_(
u"""SQL WHERE clause expression that specifies the subset of points to
use. If this parameter is not provided, all of the points will be
used.

The exact syntax of this expression depends on the type of feature
class you're using. ESRI recommends you reference fields using the
following syntax:

* For shapefiles, ArcInfo coverages, or feature classes stored in file
  geodatabases, ArcSDE geodatabases, or ArcIMS, enclose field names in
  double quotes: "MY_FIELD"

* For feature classes stored in personal geodatabases, enclose field
  names in square brackets: [MY_FIELD].
"""),
    arcGISDisplayName=_(u'Where clause'),
    arcGISCategory=_(u'Interpolation options'),
    arcGISParameterDependencies=[u'points'])

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.InterpolateAtArcGISPoints, u'noDataValue',
    typeMetadata=FloatTypeMetadata(canBeNone=True),
    description=_(
u"""Value to use when the interpolated value is NoData.

If a value is not provided for this parameter, a database NULL value
will be stored in the field when the interpolated value is NoData. If
the field cannot store NULL values, as is the case with shapefiles,
the value -9999 will be used."""),
    arcGISDisplayName=_(u'Value to use when the interpolated value is NoData'),
    arcGISCategory=_(u'Interpolation options'))

CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'timeout', OSCAR5DayThirdDegreeCurrents.InterpolateAtArcGISPoints, u'timeout')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'maxRetryTime', OSCAR5DayThirdDegreeCurrents.InterpolateAtArcGISPoints, u'maxRetryTime')
CopyArgumentMetadata(OSCAR5DayThirdDegreeCurrents.CreateArcGISRasters, u'cacheDirectory', OSCAR5DayThirdDegreeCurrents.InterpolateAtArcGISPoints, u'cacheDirectory')

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.InterpolateAtArcGISPoints, u'orderByFields',
    typeMetadata=ListTypeMetadata(elementType=ArcGISFieldTypeMetadata(mustExist=True), minLength=1, canBeNone=True),
    description=_(
u"""Fields for defining the order in which the points are processed.

The points may be processed faster if they are ordered
spatiotemporally, such that points that are close in space and time
are processed sequentially. Ordering the points this way increases the
probability that the value of a given point can be interpolated from
data that is cached in memory, rather than from data that must be read
from the disk or network, which is much slower. Choose fields that
faciliate this. For example, if your points represent the locations of
animals tracked by satellite telemetry, order the processing first by
the animal ID and then by the transmission date or number.

If you omit this parameter, the Date Field will be used automatically.

This parameter requires ArcGIS 9.2 or later."""),
    arcGISDisplayName=_(u'Order by fields'),
    arcGISCategory=_(u'Performance tuning options'),
    arcGISParameterDependencies=[u'points'],
    dependencies=[ArcGISDependency(9, 2)])

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.InterpolateAtArcGISPoints, u'numBlocksToCacheInMemory',
    typeMetadata=IntegerTypeMetadata(minValue=0, canBeNone=True),
    description=_(
u"""Maximum number of blocks of OSCAR data to cache in memory.

To minimize the number of times that the disk or network must be
accessed, this tool employs a simple caching strategy, in addition to
disk caching described by the Cache Directory parameter. When it
processes the first point, it reads a square block of cells centered
on that point and caches it in memory. When it processes the second
and subsequent points, it first checks whether the cells needed for
that point are contained by the block cached in memory. If so, it
processes that point using the in-memory block, rather than reading
from disk or the network again. If not, it reads another square block
centered on that point and adds it to the cache.

The tool processes the remaining points, adding additional blocks to
the cache, as needed. To prevent the cache from exhausing all memory,
it is only permitted to grow to the size specified by this parameter.
When the cache is full but a new block is needed, the oldest block is
discarded to make room for the newest block.

The maximum size of the cache in bytes may be calculated by
multiplying 4 by the number of blocks and by the block sizes. For
example, if there are 128 blocks with size x=32 by y=32 by t=2, the
maximum size of the cache is 1048576 bytes (1 MB).

If this parameter is 0, no blocks will be cached in memory."""),
    arcGISDisplayName=_(u'Number of blocks of data to cache in memory'),
    arcGISCategory=_(u'Performance tuning options'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.InterpolateAtArcGISPoints, u'xBlockSize',
    typeMetadata=IntegerTypeMetadata(minValue=0, canBeNone=True),
    description=_(
u"""Size of the blocks of OSCAR data to cache in memory, in the x
direction (longitude). The size is given as the number of cells.

If this parameter is 0, no blocks will be cached in memory."""),
    arcGISDisplayName=_(u'In-memory cache block size, in X direction'),
    arcGISCategory=_(u'Performance tuning options'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.InterpolateAtArcGISPoints, u'yBlockSize',
    typeMetadata=IntegerTypeMetadata(minValue=0, canBeNone=True),
    description=_(
u"""Size of the blocks of OSCAR data to cache in memory, in the y
direction (latitude). The size is given as the number of cells.

If this parameter is 0, no blocks will be cached in memory."""),
    arcGISDisplayName=_(u'In-memory cache block size, in Y direction'),
    arcGISCategory=_(u'Performance tuning options'))

AddArgumentMetadata(OSCAR5DayThirdDegreeCurrents.InterpolateAtArcGISPoints, u'tBlockSize',
    typeMetadata=IntegerTypeMetadata(minValue=0, canBeNone=True),
    description=_(
u"""Size of the blocks of OSCAR data to cache in memory, in the t
direction (time). The size is given as the number of cells.

If this parameter is 0, no blocks will be cached in memory."""),
    arcGISDisplayName=_(u'In-memory cache block size, in T direction'),
    arcGISCategory=_(u'Performance tuning options'))

AddResultMetadata(OSCAR5DayThirdDegreeCurrents.InterpolateAtArcGISPoints, u'updatedPoints',
    typeMetadata=ArcGISFeatureLayerTypeMetadata(),
    description=_(u'Updated points.'),
    arcGISDisplayName=_(u'Updated points'),
    arcGISParameterDependencies=[u'points'])

###############################################################################
# Names exported by this module
###############################################################################

__all__ = ['OSCAR5DayThirdDegreeCurrents']