diff --git a/Lib/__init__.py b/Lib/__init__.py index 8a0c7e76..23c2a595 100644 --- a/Lib/__init__.py +++ b/Lib/__init__.py @@ -14,7 +14,7 @@ "mvBaseWriter", "mvSphereMesh", "mvVsWriter", "mvCdmsRegrid"] # Errors -from .error import CDMSError # noqa +from .error import CDMSError # noqa # CDMS datatypes from .cdmsobj import CdArray, CdChar, CdByte, CdDouble, CdFloat, CdFromObject, CdInt, CdLong, CdScalar, CdShort, CdString # noqa diff --git a/Lib/avariable.py b/Lib/avariable.py index fb8356fe..f3e847bf 100644 --- a/Lib/avariable.py +++ b/Lib/avariable.py @@ -38,8 +38,15 @@ def getMinHorizontalMask(var): """ Get the minimum mask associated with 'x' and 'y' (i.e. with the min number of ones) across all axes - @param var CDMS variable with a mask - @return mask array or None if order 'x' and 'y' were not found + + Parameters + ---------- + var + CDMS variable with a mask + + Return + ------ + mask array or None if order 'x' and 'y' were not found """ from distarray import MultiArrayIter @@ -153,7 +160,24 @@ def __array__(self, t=None, context=None): # Numeric, ufuncs call this return numpy.ma.filled(self.getValue(squeeze=0)) def __call__(self, *args, **kwargs): - "Selection of a subregion using selectors" + """ + Selection of a subregion using selectors. + + Parameters + ---------- + raw: + if set to 1, return numpy.ma only + squeeze: + if set to 1, eliminate any dimension of length 1 + grid: + if given, result is regridded ont this grid. + order: + if given, result is permuted into this order + + Returns + ------- + Subregion selected + """ # separate options from selector specs d = kwargs.copy() raw = d.setdefault('raw', 0) @@ -241,9 +265,19 @@ def _returnArray(self, ar, squeeze, singles=None): return result def generateGridkey(self, convention, vardict): - """ generateGridkey(): Determine if the variable is gridded, - and generate ((latname, lonname, order, maskname, class), lat, lon) if gridded, - or (None, None, None) if not gridded. vardict is the variable dictionary of the parent""" + """Determine if the variable is gridded. + + Parameters + ---------- + convention: + Metadata convention class + vardict: + Variable metedata + + Returns + ------- + ((latname, lonname, order, maskname, class), lat, lon) if gridded + (None, None, None) if not gridded """ lat, nlat = convention.getVarLatId(self, vardict) lon, nlon = convention.getVarLonId(self, vardict) @@ -312,9 +346,19 @@ def generateGridkey(self, convention, vardict): return None, lat, lon def generateRectGridkey(self, lat, lon): - """ generateRectGridkey(): Determine if the variable is gridded, rectilinear, - and generate (latname, lonname, order, maskname, class) if gridded, - or None if not gridded""" + """Determine if the variable is gridded, rectilinear. + + Parameters + ---------- + lat: + latitude axis + lon: + longitude axis + + Returns + ------- + (latname, lonname, order, maskname, class) if gridded, + None if not gridded.""" ilat = ilon = -1 k = 0 @@ -370,15 +414,29 @@ def getConvention(self): # A child class may want to override this def getAxis(self, n): - "Get the n-th axis" + """Get the n-th axis. + Parameters + ---------- + n: + Axis number + Returns + ------- + if n < 0: n = n + self.rank() + self.getDomain()[n][0]""" if n < 0: n = n + self.rank() return self.getDomain()[n][0] def getAxisIndex(self, axis_spec): - """Return the index of the axis specificed by axis_spec. - Argument axis_spec and be as for axisMatches - Return -1 if no match. + """Get the index of the axis specificed by axis_spec. + + Parameters + ---------- + axis_spec: + + Returns + ------- + the axis index or -1 if no match is found. """ for i in range(self.rank()): if axisMatches(self.getAxis(i), axis_spec): @@ -386,10 +444,14 @@ def getAxisIndex(self, axis_spec): return -1 def hasCellData(self): - ''' + """ If any of the variable's axis has explicit bounds, we have cell data otherwise we have point data. - ''' + + Returns + ------- + True or False if axis has cell data. + """ for axis in self.getAxisList(): if (axis.getExplicitBounds() is not None): return True @@ -397,25 +459,40 @@ def hasCellData(self): def getAxisListIndex(self, axes=None, omit=None, order=None): """Return a list of indices of axis objects; - If axes is not None, include only certain axes. - less the ones specified in omit. If axes is None, - use all axes of this variable. + + Note + ---- + If axes is **not** `None`, include only certain axes. + less the ones specified in omit. + + If axes is `None`, use all axes of this variable. + Other specificiations are as for axisMatchIndex. """ return axisMatchIndex(self.getAxisList(), axes, omit, order) def getAxisList(self, axes=None, omit=None, order=None): """Get the list of axis objects; - If axes is not None, include only certain axes. - If omit is not None, omit those specified by omit. - Arguments omit or axes may be as specified in axisMatchAxis - order is an optional string determining the output order + + Note + ---- + If axes is **not** `None`, include only certain axes. + If omit is **not** `None`, omit those specified by omit. + + Arguments omit or axes may be as specified in axisMatchAxis + + order is an optional string determining the output order """ alist = [d[0] for d in self.getDomain()] return axisMatchAxis(alist, axes, omit, order) def getAxisIds(self): - "Get a list of axis identifiers" + """Get a list of axis identifiers. + + Returns + ------- + array list of axis ids""" + return [x[0].id for x in self.getDomain()] # Return the grid @@ -423,8 +500,15 @@ def getGrid(self): return self._grid_ def getMissing(self, asarray=0): - """Return the missing value as a scalar, or as - a numpy array if asarray==1""" + """ + Parameters + ---------- + asarray : + '0' : scalar + '1' : numpy array + Return + ------ + the missing value as a scalar, or as a numpy array if asarray==1""" if hasattr(self, 'missing_value'): try: @@ -454,9 +538,16 @@ def _setmissing(self, name, value): self.setMissing(value) def setMissing(self, value): - """Set the missing value, which may be a scalar, - a single-valued numpy array, or None. The value is - cast to the same type as the variable.""" + """Set the missing value. + + Parameters + ---------- + value + scalar, a single-valued numpy array, or None. + + Note + ---- + The value is cast to the same type as the variable.""" # Check for None first, so that constructors can # set missing_value before typecode() is initialized. @@ -487,7 +578,12 @@ def setMissing(self, value): self.missing_value = value def getTime(self): - "Get the first time dimension, or None if not found" + """Get the first time dimension. + + Returns + ------- + First Time dimension axis or `None`. + """ for k in range(self.rank()): axis = self.getAxis(k) if axis.isTime(): @@ -497,7 +593,12 @@ def getTime(self): return None def getForecastTime(self): - "Get the first forecast time dimension, or None if not found" + """Get the first forecast time dimension. + + Returns + ------- + First forecast time dimension axis or `None`. + """ for k in range(self.rank()): axis = self.getAxis(k) if axis.isForecast(): @@ -510,8 +611,11 @@ def getForecast(self): return self.getForecastTime() def getLevel(self): - """Get the first vertical level dimension in the domain, - or None if not found. + """Get the first vertical level dimension in the domain. + + Returns + ------- + First vertical level dimension axis or `None`. """ for k in range(self.rank()): axis = self.getAxis(k) @@ -522,7 +626,12 @@ def getLevel(self): return None def getLatitude(self): - "Get the first latitude dimension, or None if not found." + """Get the first latitude dimension. + + Returns + ------- + First latitude dimension axis or `None`. + """ grid = self.getGrid() if grid is not None: result = grid.getLatitude() @@ -540,7 +649,14 @@ def getLatitude(self): return result def getLongitude(self): - "Get the first latitude dimension, or None if not found." + """Get the first longitude dimension. + + Returns + ------- + First longitude dimension axis or `None`. + + """ + grid = self.getGrid() if grid is not None: result = grid.getLongitude() @@ -559,18 +675,27 @@ def getLongitude(self): # Get an order string, such as "tzyx" def getOrder(self, ids=0): - """getOrder(ids=0) returns the order string, such as tzyx. - - if ids == 0 (the default) for an axis that is not t,z,x,y - the order string will contain a '-' in that location. - The result string will be of the same length as the number - of axes. This makes it easy to loop over the dimensions. - - if ids == 1 those axes will be represented in the order - string as (id) where id is that axis' id. The result will - be suitable for passing to order2index to get the - corresponding axes, and to orderparse for dividing up into - components. + """ + parameters + ---------- + id: + 0 or 1 + returns + ------- + the order string, such as t, z, y, x (time, level, lat, lon). + + Note + ---- + * if ids == 0 (the default) for an axis that is not t,z,x,y + the order string will contain a (-) character in that location. + The result string will be of the same length as the number + of axes. This makes it easy to loop over the dimensions. + + * if ids == 1 those axes will be represented in the order + string as (id) where id is that axis' id. The result will + be suitable for passing to order2index to get the + corresponding axes, and to orderparse for dividing up into + components. """ order = "" for k in range(self.rank()): @@ -682,27 +807,44 @@ def subSlice(self, *specs, **keys): return resultArray def getSlice(self, *specs, **keys): - """x.getSlice takes arguments of the following forms and produces - a return array. The keyword argument squeeze determines whether - or not the shape of the returned array contains dimensions whose - length is 1; by default this argument is 1, and such dimensions - are 'squeezed out'. + """getSlice takes arguments of the following forms and produces + a return array. + + Parameter + --------- + raw: + if set to 1, return numpy.ma only + squeeze: + if set to 1, eliminate any dimension of length 1 + grid: + if given, result is regridded ont this grid. + order: + if given, result is permuted into this order + numericSqueeze: + if index slice is given, eliminate that dimension. + isitem: + if given, result is return as a scaler for 0-D data + + + Note + ---- There can be zero or more positional arguments, each of the form: - (a) a single integer n, meaning slice(n, n+1) - (b) an instance of the slice class - (c) a tuple, which will be used as arguments to create a slice - (d) None or ':', which means a slice covering that entire dimension - (e) Ellipsis (...), which means to fill the slice list with ':' - leaving only enough room at the end for the remaining - positional arguments + + #. a single integer n, meaning slice(n, n+1) + #. an instance of the slice class + #. a tuple, which will be used as arguments to create a slice + #. `None` or `:`, which means a slice covering that entire dimension + #. Ellipsis (...), which means to fill the slice list with `:` + leaving only enough room at the end for the remaining positional arguments + There can be keyword arguments of the form key = value, where - key can be one of the names 'time', 'level', 'latitude', or - 'longitude'. The corresponding value can be any of (a)-(d) above. + key can be one of the names `time`, `level`, `latitude`, or + `longitude`. The corresponding value can be any of (1)-(5) above. There must be no conflict between the positional arguments and the keywords. - In (a)-(c) negative numbers are treated as offsets from the end + In (1)-(5) negative numbers are treated as offsets from the end of that dimension, as in normal Python indexing. """ # Turn on squeeze and raw options by default. @@ -724,36 +866,45 @@ def expertSlice(self, slicelist): raise CDMSError(NotImplemented + 'expertSlice') def getRegion(self, *specs, **keys): - """getRegion - Read a region of data. A region is an n-dimensional - rectangular region specified in coordinate space. - 'slices' is an argument list, each item of which has one of the following forms: - - x, where x is a scalar - Map the scalar to the index of the closest coordinate value - - (x,y) - Map the half-open coordinate interval [x,y) to index interval - - (x,y,'cc') - Map the closed interval [x,y] to index interval. Other options are 'oo' (open), - 'oc' (open on the left), and 'co' (open on the right, the default). - - (x,y,'co',cycle) - Map the coordinate interval with wraparound. If no cycle is specified, wraparound - will occur iff axis.isCircular() is true. - NOTE: Only one dimension may be wrapped. - - Ellipsis - Represents the full range of all dimensions bracketed by non-Ellipsis items. - - ':' or None - Represents the full range of one dimension. - - For example, suppose the variable domain is (time,level,lat,lon). Then - - getRegion((10,20),850,Ellipsis,(-180,180)) - - retrieves: - - all times t such that 10.<=t<20. - - level 850 - - all values of all dimensions between level and lon (namely, lat) - - longitudes x such that -180<=x<180. This will be wrapped unless - lon.topology=='linear' + """ Read a region of data. A region is an n-dimensional rectangular region specified in coordinate space. + + Parameters + ---------- + slice + is an argument list, each item of which has one of the following forms: + * x, where x is a scalar + * Map the scalar to the index of the closest coordinate value. + * (x, y) + * Map the half-open coordinate interval [x,y) to index interval. + * (x, y, 'cc') + * Map the closed interval [x,y] to index interval. Other options + are 'oo' (open), 'oc' (open on the left), and 'co' + (open on the right, the default). + * (x, y, 'co', cycle) + * Map the coordinate interval with wraparound. If no cycle is + specified, wraparound will occur iff axis.isCircular() is true. + Ellipsis + Represents the full range of all dimensions bracketed by non-Ellipsis items. + None, colon + Represents the full range of one dimension. + + Note + ---- + Only one dimension may be wrapped. + + + Example + ------- + Suppose the variable domain is `(time, level, lat, lon)`. Then + + >>> getRegion((10, 20), 850, Ellipsis,(-180, 180)) + + retrieves: + + * all times t such that 10.<=t<20. + * level 850. + * all values of all dimensions between level and lon (namely, lat). + * longitudes x such that -180<=x<180. This will be wrapped unless lon.topology=='linear'. """ # By default, squeeze and raw options are on @@ -1005,14 +1156,29 @@ def subRegion(self, *specs, **keys): return result.getSlice(squeeze=0, raw=1) def getValue(self, squeeze=1): - """Return the entire set of values.""" + """Get the entire set of values. + Returns + ------- + All values and elimite the 1-D dimension. + """ return self.getSlice(Ellipsis, squeeze=squeeze) def assignValue(self, data): raise CDMSError(NotImplemented + 'assignValue') def reorder(self, order): - """return self reordered per the specification order""" + """Reorder per the specification order. + + Parameters + ---------- + order: string + can be "tzyx" with all possible axes permutation. + + Returns + ------- + New reordered variable. + """ + if order is None: return self axes = self.getAxisList() @@ -1025,17 +1191,27 @@ def regrid(self, togrid, missing=None, order=None, mask=None, **keywords): """return self regridded to the new grid. One can use the regrid2.Regridder optional arguments as well. - Example: - new_cdmsVar = cdmsVar.regrid(newGrid) # uses esmf - new_cdmsVar = cdmsVar.regrid(newGrid, regridMethod = 'conserve', - coordSys = 'cart') - - @param togrid destination grid. CDMS grid - @param missing missing values - @param order axis order - @param mask grid/data mask - @param keywords optional keyword arguments dependent on regridTool - @return regridded variable + Example + ------- + >>> new_cdmsVar = cdmsVar.regrid(newGrid) # uses libcf + >>> new_cdmsVar = cdmsVar.regrid(newGrid, regridMethod = 'conserve', coordSys = 'cart') + + Parameters + ---------- + togrid + togrid destination grid. CDMS grid + missing : Optional + missing missing values + order : Optional + order axis order + mask : Optional + mask grid/data mask + **keyords + keywords optional keyword arguments dependent on regridTool + + Returns + ------- + regridded variable """ # there is a circular dependency between cdms2 and regrid2. In # principle, cdms2 files should not import regrid2, we're bending @@ -1185,10 +1361,17 @@ def regrid(self, togrid, missing=None, order=None, mask=None, **keywords): def pressureRegrid(self, newLevel, missing=None, order=None, method="log"): """Return the variable regridded to new pressure levels. The variable should be a function of lat, lon, pressure, and (optionally) time. - is an axis of the result pressure levels. - is optional, either "log" to interpolate in the log of pressure (default), - or "linear" for linear interpolation. - and are as for regrid.PressureRegridder. + + Parameters + ---------- + newLevel : + is an axis of the result pressure levels. + method : + is optional, either `log` to interpolate in the log of pressure (default), + or `linear` for linear interpolation. + missing and order : + are as for regrid.PressureRegridder. + """ from regrid2 import PressureRegridder @@ -1203,11 +1386,19 @@ def crossSectionRegrid(self, newLevel, newLatitude, missing=None, order=None, method="log"): """Return the variable regridded to new pressure levels and latitudes. The variable should be a function of lat, level, and (optionally) time. - is an axis of the result pressure levels. - is an axis of latitude values. - is optional, either "log" to interpolate in the log of pressure (default), - or "linear" for linear interpolation. - and are as for regrid.CrossSectionRegridder. + + Parameters + ----------- + newLevel : + is an axis of the result pressure levels. + newLatitude : + is an axis of latitude values. + method : Optional + either "log" to interpolate in the log of pressure (default), + or "linear" for linear interpolation. + missing and order: + are as for regrid.CrossSectionRegridder. + """ from regrid2 import CrossSectionRegridder @@ -1224,9 +1415,12 @@ def crossSectionRegrid(self, newLevel, newLatitude, def _process_specs(self, specs, keys): """Process the arguments for a getSlice, getRegion, etc. - Returns an array of specifications for all dimensions. - Any Ellipsis has been eliminated. time, level, latitude, longitude keywords handled here + + Return + ------ + An array of specifications for all dimensions. + Any Ellipsis has been eliminated. """ myrank = self.rank() nsupplied = len(specs) @@ -1294,14 +1488,17 @@ def _single_specs(self, specs): return singles def specs2slices(self, speclist, force=None): - """Create an equivalent list of slices from an index specification + """Create an equivalent list of slices from an index specification. An index specification is a list of acceptable items, which are - -- an integer - -- a slice instance (slice(start, stop, stride)) - -- the object "unspecified" - -- the object None - -- a colon + + * an integer + * a slice instance (slice(start, stop, stride)) + * the object "unspecified" + * the object None + * a colon + The size of the speclist must be self.rank() + """ if len(speclist) != self.rank(): raise CDMSError("Incorrect length of speclist in specs2slices.") @@ -1446,11 +1643,16 @@ def _decodedType(self): return result def isEncoded(self): - "True iff self is represented as packed data." + "True if self is represented as packed data." return (hasattr(self, "scale_factor") or hasattr(self, "add_offset")) def decode(self, ar): - "Decode compressed data. ar is a masked array, scalar, or numpy.ma.masked" + """Decode compressed data. + + Parameter + --------- + ar is a masked array, scalar, or numpy.ma.masked.""" + resulttype = self._decodedType() if hasattr(self, 'scale_factor'): scale_factor = self.scale_factor @@ -1477,7 +1679,9 @@ def decode(self, ar): return ar def getGridIndices(self): - """Return a tuple of indices corresponding to the variable grid.""" + """Return + ------ + a tuple of indices corresponding to the variable grid.""" grid = self.getGrid() result = [] if grid is not None: @@ -1619,13 +1823,14 @@ def astype(self, tc): def orderparse(order): """Parse an order string. Returns a list of axes specifiers. + Note + ---- Order elements can be: - Letters t, x, y, z meaning time, longitude, latitude, level - Numbers 0-9 representing position in axes - The letter - meaning insert the next available axis here. - The ellipsis ... meaning fill these positions with any - remaining axes. - (name) meaning an axis whose id is name + * Letters t, x, y, z meaning time, longitude, latitude, level + * Numbers 0-9 representing position in axes + * The letter - meaning insert the next available axis here. + * The ellipsis ... meaning fill these positions with any remaining axes. + * (name) meaning an axis whose id is name """ if not isinstance(order, string_types): raise CDMSError('order arguments must be strings.') @@ -1656,13 +1861,14 @@ def orderparse(order): def order2index(axes, order): """Find the index permutation of axes to match order. The argument order is a string. + Note + ---- Order elements can be: - Letters t, x, y, z meaning time, longitude, latitude, level - Numbers 0-9 representing position in axes - The letter - meaning insert the next available axis here. - The ellipsis ... meaning fill these positions with any - remaining axes. - (name) meaning an axis whose id is name + * Letters t, x, y, z meaning time, longitude, latitude, level. + * Numbers 0-9 representing position in axes + * The letter - meaning insert the next available axis here. + * The ellipsis ... meaning fill these positions with any remaining axes. + * (name) meaning an axis whose id is name. """ if isinstance(order, string_types): result = orderparse(order) diff --git a/Lib/axis.py b/Lib/axis.py index 7cf59059..b070ba54 100644 --- a/Lib/axis.py +++ b/Lib/axis.py @@ -21,7 +21,7 @@ import warnings from six import string_types standard_library.install_aliases() -from collections import UserList # noqa +from collections import UserList # noqa _debug = 0 std_axis_attributes = ['name', 'units', 'length', 'values', 'bounds'] @@ -195,19 +195,28 @@ def mapLinearIntersection(xind, yind, iind, aMinusEps, aPlusEps, bPlusEps, bMinusEps, boundLeft, nodeSubI, boundRight): """ - Return true iff the coordinate interval (a,b) intersects the node - nodeSubI or cell bounds [boundLeft,boundRight], where the interval - (a,b) is defined by: - - xind = 'c' if (a,b) is closed on the left, 'o' if open, - yind same for right endpoint - aMinusEps,aPlusEps = a +/- epsilon - bPlusEps,bMinusEps = b +/- epsilon - - and the intersection option iind = 'n','b','e','s' specifies - whether the intersection is with respect to the node value - nodeSubI ('n' or 'e') or the cell bounds [boundLeft,boundRight]. - See mapLinearExt. + Parameters + ---------- + xind: + 'c' if (a,b) is closed on the left, 'o' if open, + yind: + same for right endpoint +j + Returns + ------- + True if the coordinate interval (a,b) intersects the node nodeSubI or cell + bounds [boundLeft,boundRight], where the interval (a,b) is defined by: + + * aMinusEps,aPlusEps = a +/- epsilon + * bPlusEps,bMinusEps = b +/- epsilon + + and the intersection option iind = 'n','b','e','s' specifies whether + the intersection is with respect to the node value nodeSubI ('n' or 'e') + or the cell bounds [boundLeft,boundRight]. + + See Also + -------- + mapLinearExt """ @@ -242,8 +251,8 @@ def mapLinearIntersection(xind, yind, iind, def mapLinearExt(axis, bounds, interval, indicator='ccn', epsilon=None, stride=1, wrapped=0): """Map coordinate interval to index interval, without - wraparound. interval has the form (x,y) where x and y are the - endpoints in coordinate space. indicator is a three-character + wraparound. Interval has the form (x,y) where x and y are the + endpoints in coordinate space. Indicator is a three-character string, where the first character is 'c' if the interval is closed on the left, 'o' if open, and the second character has the same meaning for the right-hand point. The third character indicates @@ -254,9 +263,10 @@ def mapLinearExt(axis, bounds, interval, indicator='ccn', 's' - the cell bounds are a subset of the interval 'e' - same as 'n', plus an extra node on either side. - Returns the corresponding index interval (i,j), where i ar[index], index==len(ar) - (b) ar is monotonically decreasing: - value >= ar[index], index==0..len(ar)-1 - value < ar[index], index==len(ar) + """Lookup value in array ar. + + Parameters + ---------- + ar: + Input array + value: + Value to search + Returns + ------- + index: + * ar is monotonically increasing. + * value <= ar[index], index==0..len(ar)-1 + * value > ar[index], index==len(ar) + * ar is monotonically decreasing: + * value >= ar[index], index==0..len(ar)-1 + * value < ar[index], index==len(ar) """ ar = numpy.ma.filled(ar) ascending = (ar[0] < ar[-1]) or len(ar) == 1 @@ -646,10 +666,22 @@ def isSubsetVector(vec1, vec2, tol): def isOverlapVector(vec1, vec2, atol=1.e-8): - """Returns (isoverlap, index) where: - isoverlap is true iff a leading portion of vec1 is a subset of vec2; - index is the index such that vec1[0]<=vec2[index]. If index==len(vec2), - then vec1[0]>vec2[len(vec2)-1] + """ + Parameters + ---------- + vec1: + Input arrays to compare + vec2: + Input arrays to compare + atol: float, optional + Absolute tolerance, The absolute differenc is equal to **atol** Default is 1e-8 + + Returns + ------- + (isoverlap, index) : + where isoverlap is true if a leading portion of vec1 is a subset of vec2; + * index is the index such that vec1[0] <= vec2[index] + * If indexl == len(vec2), then vec1[0] > vec2[len(vec2) - 1] """ index = lookupArray(vec2, vec1[0]) if index == 0 and abs(vec1[0] - vec2[0]): @@ -667,8 +699,32 @@ def isOverlapVector(vec1, vec2, atol=1.e-8): def allclose(ax1, ax2, rtol=1.e-5, atol=1.e-8): - """True if all elements of axes ax1 and ax2 are close, - in the sense of numpy.ma.allclose.""" + """ + Parameters + ---------- + ax1, ax2: array_like + + Returns + ------- + bool + True if all elements of axes ax1 and ax2 are close, + in the sense of numpy.ma.allclose. + + See Also + -------- + all, any + + Examples + -------- + >>> a = ma.array([1e10, 1e-7, 42.0], mask=[0, 0, 1]) + >>> a + masked_array(data = [10000000000.0 1e-07 --], + mask = [False False True], + fill_value = 1e+20) + >>> b = ma.array([1e10, 1e-8, 42.0], mask=[0, 0, 1]) + >>> ma.allclose(a, b) + False + """ return ((ax1 is ax2) or numpy.ma.allclose( ax1[:], ax2[:], rtol=rtol, atol=atol)) @@ -1184,16 +1240,16 @@ def getModulo(self): def mapInterval(self, interval, indicator='ccn', cycle=None): """ - Map coordinate interval to index interval. interval has one of the forms: + Map coordinate interval to index interval. interval has one of the forms - (x,y) - (x,y,indicator): indicator overrides keywork argument - (x,y,indicator,cycle): indicator, cycle override keyword arguments - None: indicates the full interval + * `(x,y)` + * `(x,y,indicator)`: indicator overrides keywork argument + * `(x,y,indicator,cycle)`: indicator, cycle override keyword arguments + * `None`: indicates the full interval - where x and y are the endpoints in coordinate space. indicator is a - two-character string, where the first character is 'c' if the interval - is closed on the left, 'o' if open, and the second character has the + where `x` and `y` are the endpoints in coordinate space. indicator is a + two-character string, where the first character is `c` if the interval + is closed on the left, `o` if open, and the second character has the same meaning for the right-hand point. Set cycle to a nonzero value to force wraparound. @@ -1206,12 +1262,14 @@ def mapInterval(self, interval, indicator='ccn', cycle=None): (1) if j<=N, the interval does not wrap around the axis endpoint (2) if j>N, the interval wraps around, and is equivalent to the two consecutive intervals [i,N), [0,j-N) + For example, if the vector is [0,2,4,...,358] of length 180, and the coordinate interval is [-5,5), the return index interval is [178,183). This is equivalent to the two intervals [178,180) and [0,3). - Note: if the interval is interior to the axis, but does not span any - axis element, a singleton (i,i+1) indicating an adjacent index is returned. +.. note:: + if the interval is interior to the axis, but does not span any axis element, + a singleton (i,i+1) indicating an adjacent index is returned. """ i, j, k = self.mapIntervalExt(interval, indicator, cycle) j = min(j, i + len(self)) @@ -2372,49 +2430,72 @@ def isVirtual(self): # Functions for selecting axes +# Functions for selecting axes def axisMatchAxis(axes, specifications=None, omit=None, order=None): - """Given a list of axes and a specification or list of + """Match a list of axes following a specification or list of specificatons, and a specification or list of specifications - of those axes to omit, return a list of - those axes in the list that match the specification but - do not include in the list any axes that matches an omit - specification. + of those axes to omit. + + Parameters + ---------- + specifications: + * is None, include all axes less the omitted ones. + + * Individual specifications must be integer indices into axes or + matching criteria as detailed in axisMatches. + + omit: + * is None, do not omit any axis. - If specifications is None, include all axes less the omitted ones. + * Individual specifications must be integer indices into axes or + matching criteria as detailed in axisMatches. - Individual specifications must be integer indices into axes or - matching criteria as detailed in axisMatches. + order: + * A string containing the symbols `t,x,y,z` or `-`. If a `-` is + given, any elements of the result not chosen otherwise are filled + in from left to right with remaining candidates. - Axes are returned in the order they occur in the axes argument unless - order is given. + Return + ------ + A list of axes that match the specification omitting any axes that matches + an omit specification. - order can be a string containing the symbols t,x,y,z, or -. - If a - is given, any elements of the result not chosen otherwise are - filled in from left to right with remaining candidates. + Axes are returned in the order they occur in the axes argument unless order is given. """ return [axes[i] for i in axisMatchIndex(axes, specifications, omit, order)] def axisMatchIndex(axes, specifications=None, omit=None, order=None): - """Given a list of axes and a specification or list of + """Match a list of axes following a specification or list of specificatons, and a specification or list of specifications - of those axes to omit, return a list of the indices of - those axes in the list that match the specification but - do not include in the list any axes that matches an omit - specification. + of those axes to omit. - If specifications is None, include all axes less the omitted ones. + Parameters + ---------- + specifications: + * is None, include all axes less the omitted ones. - Individual specifications must be integer indices into axes or - matching criteria as detailed in axisMatches. + * Individual specifications must be integer indices into axes or + matching criteria as detailed in axisMatches. - The indices of axes are returned in the order the axes - occur in the axes argument, unless order is given. + omit: + * is None, do not omit any axis. + + * Individual specifications must be integer indices into axes or + matching criteria as detailed in axisMatches. + + order: + * A string containing the symbols `t,x,y,z` or `-`. If a `-` is + given, any elements of the result not chosen otherwise are filled + in from left to right with remaining candidates. + + Return + ------ + A list of axis' indices which match the specification omitting any axes that matches an omit specification. + + Axes are returned in the order they occur in the axes argument unless order is given. - order can be a string containing the symbols t,x,y,z, or -. - If a - is given, any elements of the result not chosen otherwise are - filled in from left to right with remaining candidates. """ if specifications is None: speclist = axes @@ -2525,22 +2606,35 @@ def axisMatchIndex(axes, specifications=None, omit=None, order=None): def axisMatches(axis, specification): - """Return 1 or 0 depending on whether axis matches the specification. + """ + Parameters + ---------- + axis: + See note below + specifications: + See note below + + Returns + ------- + 1 or 0 depending on whether axis matches the specification. + + Note + ---- Specification must be one of: - 1. a string representing an axis id or one of - the keywords time, fctau0, latitude or lat, longitude or lon, or - lev or level. - axis may be surrounded with parentheses or spaces. + #. a string representing an axis id or one of the keywords time, + fctau0, latitude or lat, longitude or lon, or lev or level. - We first attempt to match the axis id and the specification. - Keywords try to match using isTime, isLatitude, etc. - Comparisons to keywords and axis ids is case-insensitive. + #. Axis may be surrounded with parentheses or spaces. - 2. a function that takes an axis as an argument and returns a value. - if the value returned is true, the axis matches. + * We first attempt to match the axis id and the specification. + * Keywords try to match using isTime, isLatitude, etc. + * Comparisons to keywords and axis ids is case-insensitive. - 3. an axis object; will match if it is the same object as axis. + #. a function that takes an axis as an argument and returns a value. + * if the value returned is true, the axis matches. + + #. an axis object; will match if it is the same object as axis. """ if isinstance(specification, string_types): s = specification.lower() @@ -2579,7 +2673,20 @@ def axisMatches(axis, specification): def concatenate(axes, id=None, attributes=None): - """Concatenate the axes, return a transient axis.""" + """Concatenate multiple axes including boundaries. + + Parameters + ---------- + axes: + Axes to concatenate + id: + New axis identification (default None) + attributes: + Attributes to attached to the new Axis + + Returns + ------- + Transient axis.""" data = numpy.ma.concatenate([ax[:] for ax in axes]) boundsArray = [ax.getBounds() for ax in axes] @@ -2591,7 +2698,18 @@ def concatenate(axes, id=None, attributes=None): def take(ax, indices): - """Take values indicated by indices list, return a transient axis.""" + """Take elements form an array along an axis + Parameters + ---------- + ax: + The source array. + indices: + The indices of the values to extract. + Returns + ------- + axis: TransientAxis + The return array has the same type of ax. + """ # Bug in ma compatibility module data = numpy.ma.take(ax[:], indices) diff --git a/Lib/bindex.py b/Lib/bindex.py index ec1303e0..df14ead0 100644 --- a/Lib/bindex.py +++ b/Lib/bindex.py @@ -9,10 +9,17 @@ def bindexHorizontalGrid(latlin, lonlin): """Create a bin index for a horizontal grid. - 'latlin' is the raveled latitude values. - 'lonlin' is the raveled longitude values. - Returns the index. + Parameters + ---------- + latlin: + latlin is the raveled latitude values. + latlon: + lonlin is the raveled longitude values. + + Returns + ------- + resulting index. """ lonlin = numpy.mod(lonlin, 360) NI, NJ = _bindex.getLens() @@ -27,13 +34,22 @@ def bindexHorizontalGrid(latlin, lonlin): def intersectHorizontalGrid(latspecs, lonspecs, latlin, lonlin, index): """Intersect a horizontal grid with a lat-lon region. - 'latspecs' and 'lonspecs' are the latitude/longitude specs - as defined in the grid module. - 'latlin' and 'lonlin' are the raveled latitude/longitude arrays. - 'index' is the bin index as returned from bindex. + Parameters + ---------- + latspecs: + latitude specs as defined in the grid module. + lonspecs: + longitude specs as defined in the grid module. + latlin: + latlin is the raveled latitude array. + lonlin: + lonlin is the raveled longitude array. + index: + index is the bin index as returned from bindex. - Returns an array of indices, in latlin/lonlin, of the points in - the intersection. + Returns + ------- + an array of indices, in latlin/lonlin, of the points in the intersection. """ points = numpy.zeros(len(latlin), dtype='l') if latspecs is None: diff --git a/Lib/cdmsobj.py b/Lib/cdmsobj.py index 70a6cf5f..524e49be 100644 --- a/Lib/cdmsobj.py +++ b/Lib/cdmsobj.py @@ -556,22 +556,24 @@ def __init__(self, node=None): self.attributes[attname] = attval def searchone(self, pattern, attname): - """Return true if the attribute with name attname is a string - attribute which contains the compiled regular expression pattern, or - if attname is None and pattern matches at least one string - attribute. Return false if the attribute is not found or is not - a string. - ::: - Input::: - pattern :: (str) (0) pattern - attname :: (str/None) (1) attribute name - ::: - Output::: - result :: (int/True/False) (0) True if the attribute with name attname - is a string attribute which contains the compiled regular expression - pattern, or if attname is None and pattern matches at least one - string attribute, False if the attribute is not found or is not a string - ::: + """Search if the attribute with name attname is a string attribute which + contains the compiled regular expression pattern, or + if attname is None and pattern matches at least one string attribute. + + Parameters + ---------- + pattern: + (str) pattern + attname: + (str/None) attribute name + + Returns + ------- + result: (int/True/False) + * 1 or True if the attribute with name attname is a string + attribute which contains the compiled regular expression pattern, + or if attname is None and pattern matches at least one string attribute, + * 0 or False if the attribute is not found or is not a string """ if attname is None: for attval in list(self.attributes.values()): @@ -592,21 +594,22 @@ def searchone(self, pattern, attname): # attribute. Return false if the attribute is not found or is not a string def matchone(self, pattern, attname): """ - Return true if the attribute with name attname is a string - attribute which matches the compiled regular expression pattern, or - if attname is None and pattern matches at least one string - attribute. Return false if the attribute is not found or is not a string - ::: - Input::: - pattern :: (str) (0) pattern - attname :: (str/None) (1) attribute name - ::: - Output::: - result :: (int/True/False) (0) True if the attribute with name attname - is a string attribute which matches the compiled regular expression - pattern, or if attname is None and pattern matches at least one - string attribute, False if the attribute is not found or is not a string - ::: + Search if the attribute with name attname is a string attribute which matches + the compiled regular expression pattern, or + if attname is None and pattern matches at least one string attribute. + + Parameters + ---------- + pattern: (str) pattern + attname: (str/None) attribute name + + Returns + ------- + result: (int/True/False) + * True if the attribute with name attname is a string attribute which + matches the compiled regular expression pattern, or if attname is None + and pattern matches at least one string attribute. + * False if the attribute is not found or is not a string. """ if attname is None: for attval in list(self.attributes.values()): @@ -626,18 +629,23 @@ def matchone(self, pattern, attname): # internal node tag. def searchPattern(self, pattern, attribute, tag): """ - Search for a pattern in a string-valued attribute. If attribute is None, search - all string attributes. If tag is not None, it must match the internal node tag. - it must match the internal node tag. - ::: - Input::: - pattern :: (str) (0) pattern - attribute :: (str/None) (1) attribute name - tag :: (str/None) (2) node tag - ::: - Output::: - result :: (list) (0) - ::: + Search for a pattern in a string-valued attribute. If attribute is None, search all string attributes. + If tag is not None, it must match the internal node tag. + + Parameters + ---------- + pattern: (str) + + attribute: (str/None) + attribute name + + tag: (str/None) + node tag + + Returns + ------- + result: (list) + """ if tag is None or string.lower(tag) == self._node_.tag: if self.searchone(pattern, attribute): @@ -652,18 +660,21 @@ def searchPattern(self, pattern, attribute, tag): # internal node tag. def matchPattern(self, pattern, attribute, tag): """ - Match for a pattern in a string-valued attribute. If attribute is None, search - all string attributes. If tag is not None, it must match the internal node tag. + Match for a pattern in a string-valued attribute. If attribute is None, search all string attributes. If tag is not None, it must match the internal node tag. - ::: - Input::: - pattern :: (str) (0) pattern - attribute :: (str/None) (1) attribute name - tag :: (str/None) (2) node tag - ::: - Output::: - result :: (list) (0) - ::: + + Parameters + ---------- + pattern: (str) + pattern + attribute: (str/None) + attribute name + tag: (str/None) + node tag + Results + ------- + result: (list) + """ if tag is None or string.lower(tag) == self._node_.tag: if self.matchone(pattern, attribute): @@ -678,17 +689,19 @@ def matchPattern(self, pattern, attribute, tag): # If the predicate returns false, return an empty list def searchPredicate(self, predicate, tag): """ - Apply a truth-valued predicate. Return a list containing a single instance: - [self] if the predicate is true and either tag is None or matches the object node tag. - If the predicate returns false, return an empty list - ::: - Input::: - predicate :: (function) (0) predicate - tag :: (str/None) (1) node tag - ::: - Output::: - result :: (list) (0) - ::: + Apply a truth-valued predicate. + + Parameters + ---------- + predicate: (function) + tag: (str/None) + node tag + Returns + ------- + result: (list) + * Return a list containing a single instance: [self] if the + predicate is true and either tag is None or matches the + object node tag. If the predicate returns false, return an empty list """ if tag is None or string.lower(tag) == self._node_.tag: try: @@ -702,20 +715,25 @@ def searchPredicate(self, predicate, tag): def dump(self, path=None, format=1): """ dump(self,path=None,format=1) + Dump an XML representation of this object to a file. - 'path' is the result file name, None for standard output. - 'format'==1 if the file is formatted with newlines for readability - ::: - Input::: - path :: (None) (0) result file name, None for standard output - format :: (int) (1) 1 if the file is formatted with newlines for readability - ::: - Output::: - None :: (None) (0) nothing returned - ::: + `path` is the result file name, None for standard output. + `format`==1 if the file is formatted with newlines for readability + + Parameters + ---------- + path: (None) + result file name, None for standard output. + format: (int) + 1 if the file is formatted with newlines for readability. + + Returns + ------- + None: (None) + nothing returned """ if self._node_ is None: - raise CDMSError("No tree node found") # noqa + raise CDMSError("No tree node found") # noqa self._node_.dump(path, format) def _getinternals(self): diff --git a/Lib/convention.py b/Lib/convention.py index 47fddf2f..ba32cbad 100644 --- a/Lib/convention.py +++ b/Lib/convention.py @@ -206,8 +206,8 @@ def axisIsLatitude(self, axis): if (hasattr(axis, 'axis') and axis.axis == 'Y'): return True elif (hasattr(axis, 'units') and axis.units.lower() in [ - 'degrees_north', 'degree_north', 'degree_n', 'degrees_n', 'degreen', 'degreesn'] and - not (axis.isLongitude() or axis.isLevel() or axis.isTime())): + 'degrees_north', 'degree_north', 'degree_n', 'degrees_n', 'degreen', 'degreesn'] and + not (axis.isLongitude() or axis.isLevel() or axis.isTime())): return True elif (hasattr(axis, 'standard_name') and axis.standard_name.lower() == 'latitude'): return True @@ -218,8 +218,8 @@ def axisIsLongitude(self, axis): if (hasattr(axis, 'axis') and axis.axis == 'X'): return True elif (hasattr(axis, 'units') and axis.units.lower() in [ - 'degrees_east', 'degree_east', 'degree_e', 'degrees_e', 'degreee', 'degreese'] and - not (axis.isLatitude() or axis.isLevel() or axis.isTime())): + 'degrees_east', 'degree_east', 'degree_e', 'degrees_e', 'degreee', 'degreese'] and + not (axis.isLatitude() or axis.isLevel() or axis.isTime())): return True elif (hasattr(axis, 'standard_name') and axis.standard_name.lower() == 'longitude'): return True diff --git a/Lib/dataset.py b/Lib/dataset.py index 9ba7e9b5..c55bc6c8 100644 --- a/Lib/dataset.py +++ b/Lib/dataset.py @@ -110,13 +110,16 @@ class DuplicateAxisError(CDMSError): def setCompressionWarnings(value=None): - """Turn on/off the warnings for compression - Usage: - setCompressionWarning(value) - Where: - value is 0/1 False/True 'no'/'yes' or None (which sets it to the opposite - Returns: - the value it has been set to + """Turn on/off the warnings for compression. + + Parameters + ---------- + value: + * 0/1 False/True 'no'/'yes' or None (which sets it to the opposite + + Returns + ------- + Return set value. """ global _showCompressWarnings if value is None: @@ -145,7 +148,16 @@ def setCompressionWarnings(value=None): def setNetcdfUseNCSwitchModeFlag(value): - """ Tells cdms2 to switch constantly between netcdf define/write modes""" + """Tells cdms2 to switch constantly between netcdf define/write modes. + Parameters + ---------- + value: + 0/1, False/True. + + Returns + ------- + No return value. + """ if value not in [True, False, 0, 1]: raise CDMSError( @@ -157,7 +169,17 @@ def setNetcdfUseNCSwitchModeFlag(value): def setNetcdfUseParallelFlag(value): - """ Sets NetCDF classic flag value""" + """Enable/Disable NetCDF MPI I/O (Paralllelism). + + Parameters + ---------- + value: + 0/1, False/True. + + Returns + ------- + No return value. + """ global CdMpi if value not in [True, False, 0, 1]: raise CDMSError( @@ -172,7 +194,12 @@ def setNetcdfUseParallelFlag(value): def getMpiRank(): - ''' Return number of processor available ''' + """ Return number of processor available. + + Returns + ------- + rank or 0 if MPI is not enabled. + """ if CdMpi: rk = MPI.COMM_WORLD.Get_rank() return rk @@ -181,6 +208,12 @@ def getMpiRank(): def getMpiSize(): + """Return MPI size. + + Returns + ------- + MPI size or 0 if MPI is not enabled. + """ if CdMpi: sz = MPI.COMM_WORLD.Get_size() return sz @@ -189,7 +222,17 @@ def getMpiSize(): def setNetcdf4Flag(value): - """ Sets NetCDF classic flag value""" + """Enable netCDF4 (HDF5) mode in libnetcdf. + + Parameters + ---------- + value: + 0/1, False/True. + + Returns + ------- + No return value. + """ if value not in [True, False, 0, 1]: raise CDMSError("Error NetCDF4 flag must be 1/0 or true/False") if value in [0, False]: @@ -199,7 +242,17 @@ def setNetcdf4Flag(value): def setNetcdfClassicFlag(value): - """ Sets NetCDF classic flag value""" + """Enable netCDF3 (classic) mode in libnetcdf. + + Parameters + ---------- + value: + 0/1, False/True. + + Returns + ------- + No return value. + """ if value not in [True, False, 0, 1]: raise CDMSError("Error NetCDF Classic flag must be 1/0 or true/False") if value in [0, False]: @@ -209,7 +262,16 @@ def setNetcdfClassicFlag(value): def setNetcdfShuffleFlag(value): - """ Sets NetCDF shuffle flag value""" + """Enable/Disable NetCDF shuffle. + + Parameters + ---------- + value: + 0/1, False/True. + Returns + ------- + No return value. + """ if value not in [True, False, 0, 1]: raise CDMSError("Error NetCDF Shuffle flag must be 1/0 or true/False") if value in [0, False]: @@ -219,7 +281,16 @@ def setNetcdfShuffleFlag(value): def setNetcdfDeflateFlag(value): - """ Sets NetCDF deflate flag value""" + """Enable/Disable NetCDF deflattion. + + Parameters + ---------- + value: + 0/1, False/True. + Returns + ------- + No return value. + """ if value not in [True, False, 0, 1]: raise CDMSError("Error NetCDF deflate flag must be 1/0 or true/False") if value in [0, False]: @@ -229,7 +300,17 @@ def setNetcdfDeflateFlag(value): def setNetcdfDeflateLevelFlag(value): - """ Sets NetCDF deflate level flag value""" + """Sets NetCDF deflate level flag value + + Parameters + ---------- + value: + Deflation Level 1-9. + + Returns + ------- + No return value. + """ if value not in [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]: raise CDMSError( "Error NetCDF deflate_level flag must be an integer < 10") @@ -237,43 +318,70 @@ def setNetcdfDeflateLevelFlag(value): def getNetcdfUseNCSwitchModeFlag(): - """ Returns NetCDF UseParallel flag value""" + """Get current netCDF define mode. + + Returns + ------- + NetCDF define mode . + """ return Cdunif.CdunifGetNCFLAGS("use_define_mode") def getNetcdfUseParallelFlag(): - """ Returns NetCDF UseParallel flag value""" + """Get NetCDF UseParallel flag value. + + Parameters + ---------- + value: + 0/1, False/True. + Returns + ------- + No return value. + """ return Cdunif.CdunifGetNCFLAGS("use_parallel") def getNetcdf4Flag(): - """ Returns NetCDF4 flag value""" + """Returns + ------- + NetCDF4 flag value.""" return Cdunif.CdunifGetNCFLAGS("netcdf4") def getNetcdfClassicFlag(): - """ Returns NetCDF classic flag value""" + """Returns + ------- + NetCDF classic flag value.""" return Cdunif.CdunifGetNCFLAGS("classic") def getNetcdfShuffleFlag(): - """ Returns NetCDF shuffle flag value""" + """Returns + ------- + NetCDF shuffle flag value.""" return Cdunif.CdunifGetNCFLAGS("shuffle") def getNetcdfDeflateFlag(): - """ Returns NetCDF deflate flag value""" + """Returns + ------- + NetCDF deflate flag value. """ return Cdunif.CdunifGetNCFLAGS("deflate") def getNetcdfDeflateLevelFlag(): - """ Returns NetCDF deflate level flag value""" + """Returns + ------- + NetCDF deflate level flag value.""" return Cdunif.CdunifGetNCFLAGS("deflate_level") def useNetcdf3(): """ Turns off (0) NetCDF flags for shuffle/cuDa/deflatelevel Output files are generated as NetCDF3 Classic after that + Returns + ------- + No return value. """ setNetcdfShuffleFlag(0) setNetcdfDeflateFlag(0) @@ -316,8 +424,22 @@ def loadURI(uri): def createDataset(path, template=None): + """Create a dataset. + + Parameters + ---------- + path: + is the XML file name, or netCDF filename for simple file creation. + template: + is a string template for the datafile(s), for dataset creation. + + Returns + ------- + writing file handle. + """ return openDataset(path, 'w', template) + # Open an existing dataset # 'uri' is a Uniform Resource Identifier, referring to a cdunif file, XML file, # or LDAP URL of a catalog dataset entry. @@ -327,18 +449,21 @@ def createDataset(path, template=None): def openDataset(uri, mode='r', template=None, dods=1, dpath=None, hostObj=None): """ - Options::: -mode :: (str) ('r') mode to open the file in read/write/append -template :: (NoneType) (None) ??? -dods :: (int) (1) ??? -dpath :: (NoneType/str) (None) ??? -::: -Input::: -uri :: (str) (0) file to open -::: -Output::: -file :: (cdms2.dataset.CdmsFile) (0) file to read from -::: + Parameters + ---------- + uri: (str) + Filename to open + mode: (str) + Either `r`,`w`,`a` mode to open the file in read/write/append + template: + A string template for the datafile(s), for dataset creation + dods: (int) + Default set to 1 + dpath: (str) + Destination path. + Returns + ------- + file handle. """ uri = uri.strip() (scheme, netloc, path, parameters, query, fragment) = urlparse(uri) @@ -442,7 +567,17 @@ def openDataset(uri, mode='r', template=None, def parselist(text, f): """Parse a string of the form [A, A, ...]. - f is a function which parses A and returns (A, nconsumed) + + Parameters + ---------- + text: + Input String. + f: + function which parses A and returns (A, nconsumed). + Returns + ------- + Parser results. + n number of matches. """ n = 0 @@ -471,9 +606,17 @@ def parselist(text, f): def parseIndexList(text): - """Parse a string of the form [i,j,k,l,...,path] where - i,j,k,l,... are indices or '-', and path is a filename. - Coerce the indices to integers, return (result, nconsumed). + """Parse a string of the form [i,j,k,l,...,path]. + + Parameters + ---------- + text: + i,j,k,l,... are indices or '-', and path is a filename. + Coerce the indices to integers. + Returns + ------- + Parser results. + n number of matches. """ m = _IndexList4.match(text) nindices = 4 @@ -524,12 +667,24 @@ def parseVarMap(text): def parseFileMap(text): - """Parse a CDMS filemap. having the form: - filemap :== [ varmap, varmap, ...] - varmap :== [ namelist, slicelist ] - namelist :== [name, name, ...] - slicelist :== [indexlist, indexlist, ,,,] - indexlist :== [i,j,k,l,path] + """Parse a CDMS filemap. + + Parameters + ---------- + filemap: + list [ varmap, varmap, ...] + varmap: + list [ namelist, slicelist ] + namelist: + list [name, name, ...] + slicelist: + list [indexlist, indexlist, ,,,] + indexlist: + list [i,j,k,l,path] + + Returns + ------- + Parsing results. """ result, n = parselist(text, parseVarMap) if n < len(text): @@ -1311,11 +1466,8 @@ def __delattr__(self, name): def sync(self): """ - Syncs the file - Output::: - None :: (None) (0) yep - ::: - """ + Syncs the file on disk. + """ if self._status_ == "closed": raise CDMSError(FileWasClosed + self.id) self._file_.sync() @@ -1348,22 +1500,20 @@ def close(self): # Return an axis object. def createAxis(self, name, ar, unlimited=0): """ - Create an axis - 'name' is the string name of the Axis - 'ar' is the 1-D data array, or None for an unlimited axis - Set unlimited to true to designate the axis as unlimited - Return an axis object. - ::: - Options::: - unlimited :: (int/True/False) (0) unlimited dimension ? - ::: - Input::: - name :: (str) (0) dimension name - ar :: (numpy.ndarray/None) (1) 1-D data array containing dimension values, or None for an unlimited axis - ::: - Output::: - axis :: (cdms2.axis.FileAxis) (0) file axis whose id is name - ::: + Create an axis. + + Parameters + ---------- + name: str + is the string name of the Axis + ar: numpy.ndarray/None + is the 1-D data array, or None for an unlimited axis + unlimited: (int/True/False) + True/0 designate that the axis as unlimited. + + Returns + ------- + an axis object (cdms2.axis.FileAxis). """ if self._status_ == "closed": raise CDMSError(FileWasClosed + self.id) @@ -1401,21 +1551,25 @@ def createAxis(self, name, ar, unlimited=0): def createVirtualAxis(self, name, axislen): """Create an axis without any associated coordinate array. This axis is read-only. This is useful for the 'bound' axis. - is the string name of the axis. - is the integer length of the axis. - Note: for netCDF output, this just creates a dimension without + Parameters + ---------- + name: + is the string name of the axis. + axislen: + is the integer length of the axis. + + Returns + ------- + axis: + file axis whose id is name (cdms2.axis.FileVirtualAxis) + + Note + ---- + For netCDF output, this just creates a dimension without the associated coordinate array. On reads the axis will look like an axis of type float with values [0.0, 1.0, ..., float(axislen-1)]. On write attempts an exception is raised. - ::: - Input::: - name :: (str) (0) dimension name - axislen :: (int) (1) - ::: - Output::: - axis :: (cdms2.axis.FileVirtualAxis) (0) file axis whose id is name - ::: """ if self._status_ == "closed": raise CDMSError(FileWasClosed + self.id) @@ -1429,21 +1583,24 @@ def createVirtualAxis(self, name, axislen): # Copy axis description and data from another axis def copyAxis(self, axis, newname=None, unlimited=0, index=None, extbounds=None): - """ - Copy axis description and data from another axis - ::: - Options::: - newname :: (None/str) (None) new name for axis - unlimited :: (int/True/False) (0) unlimited dimension ? - index :: (int/None) (None) :: index - extbounds :: (None/numpy.ndarray) (None) :: new bounds to use bounds - ::: - Input::: - axis :: (cdms2.axis.FileAxis/cdms2.axis.FileVirtualAxis) (0) axis to copy - ::: - Output::: - axis :: (cdms2.axis.FileAxis/cdms2.axis.FileVirtualAxis) (0) copy of input axis - ::: + """Copy axis description and data from another axis. + + Parameters + ---------- + axis: + axis to copy (cdms2.axis.FileAxis/cdms2.axis.FileVirtualAxis) + newname: (None/str) + new name for axis (default None) + unlimited: (int/True/False) + unlimited dimension (default 0) + index: (int/None) + (default None) + extbounds: (numpy.ndarray) + new bounds to use bounds (default None) + + Returns + -------- + copy of input axis (cdms2.axis.FileAxis/cdms2.axis.FileVirtualAxis) """ if newname is None: newname = axis.id @@ -1503,21 +1660,28 @@ def copyAxis(self, axis, newname=None, unlimited=0, # order and type are strings def createRectGrid(self, id, lat, lon, order, type="generic", mask=None): """ - Create an implicit rectilinear grid. lat, lon, and mask are objects. order and type are strings - ::: - Options::: - type :: (str) ('generic') grid type - mask :: (None/numpy.ndarray) (None) mask - ::: - Input::: - id :: (str) (0) grid name - lat :: (numpy.ndarray) (1) latitude array - lon :: (numpy.ndarray) (2) longitude array - order :: (str) (3) order - ::: - Output::: - grid :: (cdms2.grid.FileRectGrid) (0) file grid - ::: + Create an implicit rectilinear grid. lat, lon, and mask are objects. order and type are strings. + + + Parameters + ---------- + id: (str) + grid name (default 0) + lat: (numpy.ndarray) + latitude array (default 1) + lon: (numpy.ndarray) + longitude array (default 2) + order: (str) + order (default 3) + type: (str) + grid type (defalut `generic`) + mask: (None/numpy.ndarray) + mask (default None) + + Returns + ------- + grid (cdms2.grid.FileRectGrid) + """ grid = FileRectGrid(self, id, lat, lon, order, type, mask) self.grids[grid.id] = grid @@ -1528,17 +1692,19 @@ def createRectGrid(self, id, lat, lon, order, type="generic", mask=None): # Copy grid def copyGrid(self, grid, newname=None): """ - Create an implicit rectilinear grid. lat, lon, and mask are objects. order and type are strings - ::: - Options::: - newname :: (str/None) (None) new name for grid - ::: - Input::: - grid :: (cdms2.grid.FileRectGrid/cdms2.hgrid.FileCurveGrid/cdms2.gengrid.FileGenericGrid) (0) file grid - ::: - Output::: - grid :: (cdms2.grid.FileRectGrid/cdms2.hgrid.FileCurveGrid/cdms2.gengrid.FileGenericGrid) (0) file grid - ::: + Create an implicit rectilinear grid. lat, lon, and mask are objects. Order and type are strings. + + Parameters + ---------- + newname: (str/None) + new name for grid (default None) + grid: + file grid (cdms2.grid.FileRectGrid/cdms2.hgrid.FileCurveGrid/cdms2.gengrid.FileGenericGrid) + + Returns + ------- + file grid (cdms2.grid.FileRectGrid/cdms2.hgrid.FileCurveGrid/cdms2.gengrid.FileGenericGrid) + """ if newname is None: if hasattr(grid, 'id'): @@ -1587,24 +1753,26 @@ def copyGrid(self, grid, newname=None): # Return a variable object. def createVariable(self, name, datatype, axesOrGrids, fill_value=None): """ - Create a variable - 'name' is the string name of the Variable - 'datatype' is a CDMS datatype or numpy typecode - 'axesOrGrids' is a list of axes, grids. (Note: this should be generalized to allow - subintervals of axes and/or grids) - Return a variable object. - ::: - Options::: - fill_value :: (int/float/None) (None) fill_value - ::: - Input::: - name :: (str) (0) file variable name - datatype :: (str/type) (1) file variable type - axesOrGrids :: ([cdms2.axis.FileAxis]/[cdms2.grid.FileRectGrid]) (2) list of FileAxis or FileRectGrid - ::: - Output::: - axis :: (cdms2.fvariable.FileVariable) (0) file variable - ::: + Create a variable. + + Parameters + ---------- + name: + The string name of the Variable + datatype: + A CDMS datatype or numpy typecode + axesOrGrids: + is a list of axes, grids. + fill_value: + fill_value (cast into data type). + + Note + ---- + This should be generalized to allow subintervals of axes and/or grids). + + Returns + ------- + Return a variable object (cdms2.fvariable.FileVariable). """ if self._status_ == "closed": raise CDMSError(FileWasClosed + self.id) @@ -1646,17 +1814,21 @@ def createVariable(self, name, datatype, axesOrGrids, fill_value=None): # is None, search the dataset and all objects contained in it. def searchPattern(self, pattern, attribute, tag): """ - Search for a pattern in a string-valued attribute. If attribute is None, - search all string attributes. If tag is not None, it must match the internal node tag. - ::: - Input::: - pattern :: (str) (0) pattern - attribute :: (str/None) (1) attribute name - tag :: (str/None) (2) node tag - ::: - Output::: - result :: (list) (0) - ::: + Search for a pattern in a string-valued attribute. If attribute is None, search all string attributes. + If tag is not None, it must match the internal node tag. + + Parameters + ---------- + pattern: + expression pattern + attribute: + attribute name + tag: + node tag + + Returns + ------- + list of match pattern """ resultlist = [] if tag is not None: @@ -1686,15 +1858,20 @@ def matchPattern(self, pattern, attribute, tag): """ Match for a pattern in a string-valued attribute. If attribute is None, search all string attributes. If tag is not None, it must match the internal node tag. - ::: - Input::: - pattern :: (str) (0) pattern - attribute :: (str/None) (1) attribute name - tag :: (str/None) (2) node tag - ::: - Output::: - result :: (list) (0) - ::: + + Parameters + ---------- + pattern: + String expression. + attribute: + Attribute Name. If `None` search all attributre. + tag: + node tag, if `cdmsFile` only match the current dataset otherwise match + all object matching the tag. + + Returns + ------- + list of match patterns. """ resultlist = [] if tag is not None: @@ -1725,17 +1902,21 @@ def matchPattern(self, pattern, attribute, tag): # the dataset itself. def searchPredicate(self, predicate, tag): """ - Apply a truth-valued predicate. Return a list containing a single instance: - [self] if the predicate is true and either tag is None or matches the object node tag. - If the predicate returns false, return an empty list - ::: - Input::: - predicate :: (function) (0) predicate - tag :: (str/None) (1) node tag - ::: - Output::: - result :: (list) (0) - ::: + Apply a truth-valued predicate. + + Parameters + ---------- + predicate: + function use as predicate + tag: + node tag. + + Returns + ------- + List containing a single instance + [self] if the predicate is true and either tag is None or matches the object node tag. + + Empty list If the predicate returns false. """ resultlist = [] if tag is not None: @@ -1767,43 +1948,38 @@ def searchPredicate(self, predicate, tag): def createVariableCopy(self, var, id=None, attributes=None, axes=None, extbounds=None, extend=0, fill_value=None, index=None, newname=None, grid=None): """Define a new variable, with the same axes and attributes as in . - This does not copy the data itself. - Keywords: - attributes: A dictionary of attributes. Default is var.attributes. - axes: The list of axis objects. Default is var.getAxisList() - extbounds: Bounds of the (portion of) the extended dimension being written. - id or newname: String identifier of the new variable. - extend: If 1, define the first dimension as the unlimited dimension. If 0, do not define - an unlimited dimension. The default is the define the first dimension as unlimited - only if it is a time dimension. - - fill_value is the missing value flag. - - index is the extended dimension index to write to. The default index is determined - by lookup relative to the existing extended dimension. - grid is the variable grid. If none, the value of var.getGrid() is used. - ::: - Input::: - var :: (cdms2.tvariable.TransientVariable/cdms2.fvariable.FileVariable) (0) variable to copy - ::: - Options::: - id :: (str/None) (None) id of copied variable - attributes :: (None/dict) (None) use these attributes instead of the original var ones - axes :: (None/[cdms2.axis.AbstractAxis]) (None) list of axes to use for the copied variable - extbounds :: (None/numpy.ndarray) (None) Bounds of the (portion of) the extended dimension being written - extend :: (int) (0) If 1, define the first dimension as the unlimited dimension. - If 0, do not define an unlimited dimension. - The default is the define the first dimension as unlimited only if it is a time dimension. - extend :: (int) (0) If 1, define the first dimension as the unlimited dimension. - If 0, do not define an unlimited dimension. The default is the define the - first dimension as unlimited only if it is a time dimension. - fill_value :: (None/float) (None) the missing value flag - index :: (None/int) the extended dimension index to write to. The default index is determined - by lookup relative to the existing extended dimension - newname :: (str/None) id/newname of new variable - grid :: (None/cdms2.grid.AbstractGrid) grid to use - ::: - Output::: - variable :: (cdms2.fvariable.FileVariable) (0) file variable - ::: + + Note + ---- + This function does not copy the data itself. + + Parameters + ---------- + var: + variable to copy (cdms2.tvariable.TransientVariable or cdms2.fvariable.FileVariable) + attributes: + A dictionary of attributes. Default is var.attributes. + axes: + The list of axis objects. Default is var.getAxisList() + extbounds: + Bounds of the (portion of) the extended dimension being written. + id or newname: + String identifier of the new variable. + extend: + * 1 define the first dimension as the unlimited dimension. + * 0 do not define an unlimited dimension. The default is the define + the first dimension as unlimited only if it is a time dimension. + fill_value: + The missing value flag. + index: + The extended dimension index for writting. The default index is determined + by lookup relative to the existing extended dimension. + grid: + The variable grid. `none` the value of var.getGrid() will used. + + Returns + ------- + file variable (cdms2.fvariable.FileVariable) """ if newname is None: newname = var.id @@ -1920,46 +2096,41 @@ def createVariableCopy(self, var, id=None, attributes=None, axes=None, extbounds def write(self, var, attributes=None, axes=None, extbounds=None, id=None, extend=None, fill_value=None, index=None, typecode=None, dtype=None, pack=False): - """Write var to the file. If the variable is not yet defined in the file, - a definition is created. By default, the time dimension of the variable is defined as the - 'extended dimension' of the file. The function returns the corresponding file variable. - - Keywords: - - attributes is the attribute dictionary for the variable. The default is var.attributes. - - axes is the list of file axes comprising the domain of the variable. The default is to - copy var.getAxisList(). - - extbounds is the extended dimension bounds. Defaults to var.getAxis(0).getBounds() - - id is the variable name in the file. Default is var.id. - - extend=1 causes the first dimension to be 'extensible': iteratively writeable. - The default is None, in which case the first dimension is extensible if it is time. - Set to 0 to turn off this behaviour. - - fill_value is the missing value flag. - - index is the extended dimension index to write to. The default index is determined - by lookup relative to the existing extended dimension. - - dtype is the numpy dtype - - typecode is deprecated, for backward compatibility only - ::: - Input::: - var :: (cdms2.tvariable.TransientVariable/cdms2.fvariable.FileVariable) (0) variable to copy - ::: - Options::: - attributes :: (None/dict) (None) use these attributes instead of the original var ones - axes :: (None/[cdms2.axis.AbstractAxis]) (None) list of axes to use for the copied variable - extbounds :: (None/numpy.ndarray) (None) Bounds of the (portion of) the extended dimension being written - id :: (str/None) (None) id of copied variable - extend :: (int) (0) If 1, define the first dimension as the unlimited dimension. - If 0, do not define an unlimited dimension. - The default is the define the first dimension as unlimited only if it is a time dimension. - fill_value :: (None/float) (None) the missing value flag - index :: (None/int) the extended dimension index to write to. - The default index is determined by lookup relative to the existing extended dimension - typecode :: (None/str) (None) typdecode to write the variable as - dtype :: (None/numpy.dtype) type to write the variable as; overwrites typecode - pack :: (False/True/numpy/numpy.int8/numpy.int16/numpy.int32/numpy.int64) pack the data to save up space - ::: - Output::: - variable :: (cdms2.fvariable.FileVariable) (0) file variable - ::: + """Write var to the file. + + Note + ---- + If the variable is not yet defined in the file, a definition is created. + By default, the time dimension of the variable is defined as the + `extended dimension` of the file. The function returns the corresponding file variable. + + Parameters + ---------- + var: + variable to copy. + attributes: + The attribute dictionary for the variable. The default is var.attributes. + axes: + The list of file axes comprising the domain of the variable. The default is to copy var.getAxisList(). + extbounds: + The extended dimension bounds. Defaults to var.getAxis(0).getBounds(). + id: + The variable name in the file. Default is var.id. + extend: + * 1 causes the first dimension to be `extensible` iteratively writeable. The default is None, + in which case the first dimension is extensible if it is time. + * 0 to turn off this behaviour. + fill_value: is the missing value flag. + index: + The extended dimension index to write to. The default index is determined b + lookup relative to the existing extended dimension. + dtype: + The numpy dtype. + typecode: + Deprecated, for backward compatibility only + Returns + ------- + File variable """ if _showCompressWarnings: if (Cdunif.CdunifGetNCFLAGS("shuffle") != 0) or (Cdunif.CdunifGetNCFLAGS( @@ -2101,10 +2272,21 @@ def write(self, var, attributes=None, axes=None, extbounds=None, id=None, def write_it_yourself(self, obj): """Tell obj to write itself to self (already open for writing), using its - writeg method (AbstractCurveGrid has such a method, for example). If no - such method be available, writeToFile will be used. If that is not - available, then self.write(obj) will be called to try to write obj as - a variable.""" + writeg method (AbstractCurveGrid has such a method, for example). + + Note + ---- + If `writeg` is not available, writeToFile will be used. + If `writeToFile` is also not available, then `self.write(obj)` will be called to try to write obj as + a variable. + + Parameters + ---------- + obj: + object containing `writeg`, `writeToFile` or `write` method. + Returns + ------- + Nothig is returned. """ # This method was formerly called writeg and just wrote an # AbstractCurveGrid. if (hasattr(obj, 'writeg') and callable(getattr(obj, 'writeg'))): @@ -2117,27 +2299,31 @@ def write_it_yourself(self, obj): def getVariable(self, id): """ Get the variable object with the given id. Returns None if not found. - ::: - Input::: - id :: (str) (0) id of the variable to get - ::: - Output::: - variable :: (cdms2.fvariable.FileVariable/None) (0) file variable - ::: + + Parameters + ---------- + id: str + id of the variable to get + + Returns + ------- + variable (cdms2.fvariable.FileVariable/None) + file variable + """ return self.variables.get(id) def getVariables(self, spatial=0): - """Get a list of variable objects. If spatial=1, only return those - axes defined on latitude or longitude, excluding weights and bounds. - ::: - Options::: - spatial :: (int/True/False) (0) If spatial=1, only return those axes defined on latitude or - longitude, excluding weights and bounds - ::: - Output::: - variables :: ([cdms2.fvariable.FileVariable]) (0) file variables - ::: + """Get a list of variable objects. + Parameters + ---------- + spatial: + If spatial=1 or True, only return those axes defined on latitude + or longitude, excluding weights and bounds + + Returns + ------- + file variable. """ retval = list(self.variables.values()) if spatial: @@ -2151,38 +2337,43 @@ def getVariables(self, spatial=0): def getAxis(self, id): """Get the axis object with the given id. Returns None if not found. - ::: - Input::: - id :: (str) (0) id of the axis to get - ::: - Output::: - axis :: (cdms2.axis.FileAxis/None) (0) file axis - ::: + + Parameters + ---------- + id: + id of the axis to get + Returns + -------- + file axis """ return self.axes.get(id) def getGrid(self, id): """ Get the grid object with the given id. Returns None if not found. - ::: - Input::: - id :: (str) (0) id of the grid to get - ::: - Output::: - grid :: (cdms2.hgrid.FileCurveGrid/cdms2.gengrid.FileGenericGrid/cdms2.grid.FileRectGrid/None) (0) file axis - ::: + + Parameters + ---------- + id: + id of the grid to get + + Returns + ------- + file axis """ return self.grids.get(id) def getBoundsAxis(self, n, boundid=None): """Get a bounds axis of length n. Create the bounds axis if necessary. - ::: - Input::: - n :: (int) (0) ? - ::: - Output::: - axis :: (cdms2.axis.FileAxis/cdms2.axis.FileVirtualAxis) (0) bound axis - ::: + + Parameters + ---------- + n: + bound id (bound_%d) + + Returns + ------- + bounds axis """ if boundid is None: if n == 2: diff --git a/Lib/fvariable.py b/Lib/fvariable.py index dfa2f539..c9b7024b 100644 --- a/Lib/fvariable.py +++ b/Lib/fvariable.py @@ -37,7 +37,7 @@ def __init__(self, parent, varname, cdunifobj=None): # Initialize the domain def initDomain(self, axisdict): - "Called by whoever made me." + "Initialized the domain" self.domain = [] for dimname in self._obj_.dimensions: axis = axisdict.get(dimname) @@ -47,7 +47,7 @@ def initDomain(self, axisdict): self.domain.append((axis, start, length, truelen)) def typecode(self): - # Compatibility: convert to new typecode + """convert to new typecode.""" tc = self._obj_.typecode() # tc = typeconv.convtypecode2(tc).char return tc @@ -184,7 +184,7 @@ def getValue(self, squeeze=1): return self._obj_.getValue() def __len__(self): - " Length of first dimension. " + "Length of first dimension. " if self.parent is None: raise CDMSError(FileClosed + self.id) return len(self._obj_) diff --git a/Lib/gengrid.py b/Lib/gengrid.py index f73396b2..d932203f 100644 --- a/Lib/gengrid.py +++ b/Lib/gengrid.py @@ -274,7 +274,8 @@ def reconcile(self, axes): result = self.clone() for i in missing: for item in axes: - if (len(selfaxes[i]) == len(item)) and allclose(selfaxes[i], item): + if (len(selfaxes[i]) == len(item)) and \ + allclose(selfaxes[i], item): result._lataxis_.setAxis(i, item) result._lonaxis_.setAxis(i, item) break diff --git a/Lib/grid.py b/Lib/grid.py index 5646859e..3e1715b8 100644 --- a/Lib/grid.py +++ b/Lib/grid.py @@ -11,7 +11,7 @@ from .axis import TransientAxis, createAxis, createUniformLatitudeAxis from .axis import createUniformLongitudeAxis, getAutoBounds from .axis import createGaussianAxis, isSubsetVector -from .axis import lookupArray # noqa +from .axis import lookupArray # noqa MethodNotImplemented = "Method not yet implemented" diff --git a/Lib/gsTimeVariable.py b/Lib/gsTimeVariable.py index 8376b8ba..011b2aad 100644 --- a/Lib/gsTimeVariable.py +++ b/Lib/gsTimeVariable.py @@ -382,7 +382,7 @@ def __getitem__(self, gridIndex): return self.vars[gridIndex] # ############################################################################## -# ############# DEPRECIATED - Testing required to fully remove ################# +# ############# DEPRECIATED - Testing required to fully remove ########### # ############################################################################## diff --git a/Lib/selectors.py b/Lib/selectors.py index 6b16f28b..d4403135 100644 --- a/Lib/selectors.py +++ b/Lib/selectors.py @@ -203,8 +203,8 @@ def unmodified_select(self, variable, raw=0, raw != 0 or \ result is variable: # result is variable when there are no components, for example. - return result.subRegion(squeeze=squeeze, order=order, - grid=grid, raw=raw) + return result.subRegion(squeeze=squeeze, order=order, + grid=grid, raw=raw) else: return result diff --git a/Lib/tvariable.py b/Lib/tvariable.py index 0cb718e7..69c1cdd4 100644 --- a/Lib/tvariable.py +++ b/Lib/tvariable.py @@ -223,7 +223,7 @@ def __init__(self, data, typecode=None, copy=1, savespace=0, if id is not None: # convert unicode to string if sys.version_info < (3, 0, 0): - if isinstance(id, unicode): # noqa + if isinstance(id, unicode): # noqa id = str(id) if not isinstance(id, string_types): raise CDMSError('id must be a string') @@ -512,7 +512,7 @@ def setdimattribute(self, dim, field, value): d = self.getAxis(dim) if field == "name": if sys.version_info < (3, 0, 0): - if isinstance(value, unicode): # noqa + if isinstance(value, unicode): # noqa value = str(value) if not isinstance(value, string_types): raise CDMSError("setdimattribute: name not a string") @@ -528,7 +528,7 @@ def setdimattribute(self, dim, field, value): elif field == "units": if sys.version_info < (3, 0, 0): - if isinstance(value, unicode): # noqa + if isinstance(value, unicode): # noqa value = str(value) if not isinstance(value, string_types): raise CDMSError("setdimattribute: units not a string") diff --git a/docs/source/conf.py b/docs/source/conf.py index 74d19e1a..1421ad32 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -28,6 +28,7 @@ sys.path.insert(0,"/software/anaconda2/envs/dev/lib/python2.7/site-packages") print os.path.join(sys.prefix,"lib","python2.7","site-packages") + # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. @@ -57,6 +58,15 @@ 'sphinx.ext.napoleon' ] +jscopybutton_path = "copybutton.js" + +try: + from easydev.copybutton import get_copybutton_path + from easydev.copybutton import copy_javascript_into_static_path + copy_javascript_into_static_path("_static", get_copybutton_path()) +except Exception: + print("could not copy the copybutton javascript") + napoleon_google_docstring = True napoleon_numpy_docstring = True napoleon_include_private_with_doc = False @@ -92,9 +102,9 @@ # built documents. # # The short X.Y version. -version = '' +version = '3.0' # The full version, including alpha/beta/rc tags. -release = '' +release = '3.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -148,10 +158,11 @@ #html_theme = 'alabaster' #html_theme = 'sphinxdoc' #html_theme = 'nature' -#html_theme = 'agogo' +html_theme = 'agogo' #html_theme = 'pyramid' #html_theme = 'epub' -html_theme = 'haiku' +#html_theme = 'haiku' +#html_theme = "sphinx_rtd_theme" #html_theme = 'classic' # Theme options are theme-specific and customize the look and feel of a theme @@ -171,7 +182,7 @@ # The name of an image file (relative to this directory) to place at the top # of the sidebar. -html_logo = 'manual/images/uvcdat.png' +html_logo = 'manual/images/cdms_logo2_nocube.png' # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 diff --git a/docs/source/index.rst b/docs/source/index.rst index 860cd577..3cbec1f9 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,12 +3,17 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to cdms2's documentation! -================================= +CDMS documentation +================== + -Contents: +**Version :** |release| + +**Table of content:** .. toctree:: + :numbered: 4 + manual/cdms_1 manual/cdms_2 manual/cdms_3 @@ -17,6 +22,7 @@ Contents: manual/cdms_6 manual/cdms_7 manual/cdms_appendix + manual/sample_data # AbstractAxis # AbstractVariable diff --git a/docs/source/manual/cdms_1.rst b/docs/source/manual/cdms_1.rst index 4b73df67..33a2d191 100644 --- a/docs/source/manual/cdms_1.rst +++ b/docs/source/manual/cdms_1.rst @@ -1,37 +1,42 @@ -CHAPTER 1 ---------- +Introduction +------------ -CHAPTER 1 Introduction +Overview +^^^^^^^^ -1.1 Overview -^^^^^^^^^^^^ - -The Climate Data Management System is an object-oriented data management +The Community Data Management System is an object-oriented data management system, specialized for organizing multidimensional, gridded data used in climate analysis and simulation. -CDMS is implemented as part of the Ultrascale Visualization Climate Data -Analysis Tool (UV-CDAT), which uses the Python language. The examples in +CDMS is implemented as part of the Climate Data +Analysis Tool (CDAT), which uses the Python language. The examples in this chapter assume some familiarity with the language and the Python -Numeric module (http://www.numpy.org). A number of excellent tutorials +Numpy module (http://www.numpy.org). A number of excellent tutorials on Python are available in books or on the Internet. For example, see the `Python Foundation's homepage `__. -1.2 Variables -^^^^^^^^^^^^^ +Variables +^^^^^^^^^ The basic unit of computation in CDMS is the variable. A variable is essentially a multidimensional data array, augmented with a domain, a set of attributes, and optionally a spatial and/or temporal coordinate -system (see `Coordinate Axes <#1.4>`__). As a data array, a variable can +system (see `Coordinate Axes <#coordinate-axes>`__). As a data array, a variable can be sliced to obtain a portion of the data, and can be used in arithmetic computations. For example, if ``u`` and ``v`` are variables representing the eastward and northward components of wind speed, respectively, and both variables are functions of time, latitude, and longitude, then the -velocity for time 0 (first index) can be calculated as +velocity for time 0 (first index) can be calculated as: + + +.. highlight:: python .. doctest:: + >>> # wget "http://cdat.llnl.gov/cdat/sample_data/clt.nc" + >>> f1=cdms2.open("clt.nc") + >>> u = f1('u') + >>> v = f1('v') >>> from cdms2 import MV >>> vel = MV.sqrt(u[0]**2 + v[0]**2) @@ -40,26 +45,26 @@ This illustrates several points: - Square brackets represent the slice operator. Indexing starts at 0, so ``u[0]`` selects from variable ``u`` for the first timepoint. The result of this slice operation is another variable. The slice - operator can be multidimensional, and follows the syntax of Numeric + operator can be multidimensional, and follows the syntax of Numpy Python arrays. In this example, ``u[0:10,:,1]`` would retrieve data for the first ten timepoints, at all latitudes, for the second longitude. - Variables can be used in computation. ``**`` is the Python exponentiation operator. -- Arithmetic functions are defined in the ``cdms.MV`` module. +- Arithmetic functions are defined in the ``cdms2.MV2`` module. - Operations on variables carry along the corresponding metadata where applicable. In the above example, ``vel`` has the same latitude and longitude coordinates as ``u`` and ``v``, and the time coordinate is the first time of ``u`` and ``v``. -1.3 File I/O -^^^^^^^^^^^^ +File I/O +^^^^^^^^ A variable can be obtained from a file or collection of files, or can be generated as the result of a computation. Files can be in any of the self- describing formats netCDF, HDF, GrADS/GRIB (GRIB with a GrADS control file), or PCMDI DRS. (HDF and DRS support is optional, and is -configured at the time UV-CDAT is installed.) For instance, to read data +configured at the time CDAT is installed.) For instance, to read data from file sample.nc into variable u: .. testsetup:: * @@ -76,7 +81,7 @@ from file sample.nc into variable u: largevar=MV2.reshape(MV2.arange(400),(20,20),id="large variable").astype(MV2.float32) fnames = [ 'clt.nc', 'geos-sample', 'xieArkin-T42.nc', 'remap_grid_POP43.nc', 'remap_grid_T42.nc', 'rmp_POP43_to_T42_conserv.n', 'rmp_T42_to_POP43_conserv.nc', 'ta_ncep_87-6-88-4.nc', 'rmp_T42_to_C02562_conserv.nc' ] for file in fnames: - url = 'http://uvcdat.llnl.gov/cdat/sample_data/'+file + url = 'http://cdat.llnl.gov/cdat/sample_data/'+file r = requests.get(url) open(file, 'wb').write(r.content) @@ -90,6 +95,7 @@ from file sample.nc into variable u: .. doctest:: + >>> # wget "http://cdat.llnl.gov/cdat/sample_data/clt.nc" >>> f = cdms2.open('clt.nc') >>> u = f('u') @@ -106,7 +112,7 @@ To read ``u`` at time 1.: .. doctest:: - >>> u1 = f('u',time=1.) + >>> u1 = f('u',time=1.) A variable can be written to a file with the write function: @@ -117,8 +123,8 @@ A variable can be written to a file with the write function: >> g.close() -1.4 Coordinate Axes -^^^^^^^^^^^^^^^^^^^ +Coordinate Axes +^^^^^^^^^^^^^^^ A coordinate axis is a variable that represents coordinate information. Typically an axis is associated with one or more variables in a file or @@ -127,15 +133,15 @@ system(s) of the variable(s). Often in climate applications an axis is a one-dimensional variable whose values are floating-point and strictly monotonic. In some cases an -axis can be multidimensional (see `Grids <#1.9>`__). If an axis is +axis can be multidimensional (see `Grids <#grids>`__). If an axis is associated with one of the canonical types latitude, longitude, level, -or time, then the axis is called tep emporal . +or time, then the axis is called temporal . The shape and physical ordering of a variable is represented by the variables domain , an ordered tuple of one-dimensional axes. In the previous example, the domain of the variable u is the tuple (time, latitude, longitude). This indicates the order of the dimensions, with -the slowest- varying dimension listed first (time). The domain may be +the slowest-varying dimension listed first (time). The domain may be accessed with the ``getAxisList()`` method: .. doctest:: @@ -195,7 +201,7 @@ a domain is spatiotemporal: system. - The latitude and/or longitude coordinate axes associated with a variable need not be elements of the domain. In particular this will - be true if the variable is defined on a non-rectangular grid (see `Grids <#1.9>`__). + be true if the variable is defined on a non-rectangular grid (see `Grids <#grids>`__). As previously noted, a spatial and/or temporal coordinate system may be associated with a variable. The methods getLatitude, getLongitude, @@ -210,8 +216,8 @@ example: >>> print t.units months since 1978-12 -1.5 Attributes -^^^^^^^^^^^^^^ +Attributes +^^^^^^^^^^ As mentioned above, variables can have associated attributes , name-value pairs. In fact, nearly all CDMS objects can have associated @@ -223,7 +229,7 @@ attributes, which are accessed using the Python dot notation: >>> print u.units m/s -Attribute values can be strings, scalars, or 1-D Numeric arrays. +Attribute values can be strings, scalars, or 1-D Numpy arrays. When a variable is written to a file, not all the attributes are written. Some attributes, called internal attributes, are used for @@ -249,8 +255,8 @@ In general internal attributes should not be modified directly. One exception is the id attribute, the name of the variable. It is used in plotting and I/O, and can be set directly. -1.6 Masked values -^^^^^^^^^^^^^^^^^ +Masked values +^^^^^^^^^^^^^ Optionally, variables have a mask that represents where data are missing. If present, the mask is an array of ones and zeros having the @@ -258,7 +264,7 @@ shape of the data array. A mask value of one indicates that the corresponding data array element is missing or invalid. Arithmetic operations in CDMS take missing data into account. The same -is true of the functions defined in the cdms.MV module. For example: +is true of the functions defined in the cdms2.MV2 module. For example: .. doctest:: @@ -292,14 +298,14 @@ with a corresponding mask value of one are set to the value of the variables ``missing_value`` attribute. The data and ``missing_value`` attribute are then written to the file. -Masking is covered in `Section 2.9 `__. See also the -documentation of the Python Numeric and MA modules, on which ``cdms.MV`` +Masking is covered in `Section 2.9 `__. See also the +documentation of the Python Numpy and MA modules, on which ``cdms.MV`` is based, at `http://www.numpy.org/ `__. -1.7 File Variables -^^^^^^^^^^^^^^^^^^ +File Variables +^^^^^^^^^^^^^^ A variable can be obtained either from a file, a collection of files, or as the result of computation. Correspondingly there are three types of @@ -396,8 +402,8 @@ The datatype of the variable is determined with the typecode function: >>> u.typecode() 'f' -1.8 Dataset Variables -^^^^^^^^^^^^^^^^^^^^^ +Dataset Variables +^^^^^^^^^^^^^^^^^ The third type of variable, a *dataset variable*, is associated with a *dataset*, a collection of files that is treated as a single file. A @@ -432,8 +438,8 @@ The metafile **cdsample.xml** is then used like an ordinary data file: >>> u.shape (3, 16, 32) -1.9 Grids -^^^^^^^^^ +Grids +^^^^^^^^ A latitude-longitude grid represents the coordinate information associated with a variable. A grid encapsulates: @@ -463,8 +469,8 @@ CDMS supports two types of nonrectangular grid: However, it is more difficult to determine adjacency relationships between grid points. -1.9.1 Example: a curvilinear grid -''''''''''''''''''''''''''''''''' +Example: A Curvilinear Grid +''''''''''''''''''''''''''' In this example, variable sample is defined on a 128x192 curvilinear grid. Note that: @@ -535,13 +541,15 @@ grid. Note that: .. figure:: images/curvilinear_grid.jpg :alt: curvilinear grid - Figure1: Curvilinear Grid + Figure 1: Curvilinear Grid + -1.9.2 Example: a generic grid -''''''''''''''''''''''''''''' + +Example: A Generic Grid +''''''''''''''''''''''' In this example variable zs is defined on a generic grid. Figure 2 -illustrates the grid, in this case a geodesic grid. +illustrates the grid, in this case a geodesic grid: .. doctest:: @@ -600,8 +608,8 @@ grid to curvilinear representation: >>> genericgrid -1.10 Regridding -^^^^^^^^^^^^^^^ +Regridding +^^^^^^^^^^ Regridding is the process of mapping variables from one grid to another. CDMS supports two forms of regridding. Which one you use depends on the @@ -614,8 +622,8 @@ class of grids being transformed: - To interpolate from any lat-lon grid, rectangular or non-rectangular, use the SCRIP regridder. -1.10.1 CDMS Regridder -''''''''''''''''''''' +CDMS Regridder +'''''''''''''' The built-in CDMS regridder is used to transform data from one rectangular grid to another. For example, to regrid variable ``u`` (from @@ -648,14 +656,14 @@ To regrid a variable ``uold`` to the same grid as variable ``vnew``: >>> u63.shape (1, 2, 181, 360) -1.10.2 SCRIP Regridder -'''''''''''''''''''''' +SCRIP Regridder +''''''''''''''' To interpolate between any lat-lon grid types, the SCRIP regridder may be used. The SCRIP package was developed at [Los Alamos National -Laboratory](http://oceans11.lanl.gov/drupal/Models/OtherSoftware). +Laboratory] (http://oceans11.lanl.gov/drupal/Models/OtherSoftware). SCRIP is written in Fortran 90, and must be built and installed -separately from the UV-CDAT/CDMS installation. +separately from the CDAT/CDMS installation. The steps to regrid a variable are: @@ -673,32 +681,32 @@ The steps to regrid a variable are: Steps 1 and 2 need only be done once. The regridder can be used as often as necessary. -#For example, suppose the source data on a T42 grid is to be mapped to a -#POP curvilinear grid. Assume that SCRIP generated a remapping file named -#rmp_T42_to_POP43_conserv.nc: -# -#.. doctest:: -# -# >>> # Import regrid package for regridder functions -# >>> import regrid2, cdms2 -# -# >>> # Get the source variable -# >>> f = cdms2.open('sampleT42Grid.nc') -# >>> dat = f('src_array') -# >>> f.close() -# -# >>> # Read the regridder from the remapper file -# >>> remapf = cdms2.open('rmp_T42_to_POP43_conserv.nc') -# >>> regridf = regrid2.readRegridder(remapf) -# >>> remapf.close() -# -# >>> # Regrid the source variable -# >>> popdat = regridf(dat) +For example, suppose the source data on a T42 grid is to be mapped to a +POP curvilinear grid. Assume that SCRIP generated a remapping file named +rmp_T42_to_POP43_conserv.nc: + +.. doctest:: + + >>> # Import regrid package for regridder functions + >>> import regrid2, cdms2 + + >>> # Get the source variable + >>> f = cdms2.open('sampleT42Grid.nc') + >>> dat = f('src_array') + >>> f.close() + + >>> # Read the regridder from the remapper file + >>> remapf = cdms2.open('rmp_T42_to_POP43_conserv.nc') + >>> regridf = regrid2.readRegridder(remapf) + >>> remapf.close() + + >>> # Regrid the source variable + >>> popdat = regridf(dat) Regridding is discussed in `Chapter 4 `__. -1.11 Time types -^^^^^^^^^^^^^^^ +Time types +^^^^^^^^^^ CDMS provides extensive support for time values in the cdtime module. cdtime also defines a set of calendars , specifying the number of days @@ -777,12 +785,11 @@ or string representations can be used: Time types are described in Chapter 3. -1.12 Plotting data -^^^^^^^^^^^^^^^^^^ +Plotting data +^^^^^^^^^^^^^ Data read via the CDMS Python interface can be plotted using the vcs -module. This module, part of the Ultrascale Visualization Climate Data -Analysis Tool (UV-CDAT) is documented in the VCS reference manual. The +module. This module, part of the Climate Data Analysis Tool (CDAT) is documented in the VCS reference manual. The vcs module provides access to the functionality of the VCS visualization program. @@ -818,8 +825,8 @@ The plot routine has a number of options for producing different types of plots, such as isofill and x-y plots. See `Chapter 5 `__ for details. -1.13 Databases -^^^^^^^^^^^^^^ +Databases +^^^^^^^^^ Datasets can be aggregated together into hierarchical collections, called databases . In typical usage, a program: @@ -842,4 +849,5 @@ Protocol (LDAP). .. >>> f.variables.keys() # List the variables in the dataset. .. ['ua', 'evs', 'cvvta', 'tauv', 'wap', 'cvwhusa', 'rss', 'rls', ... 'prc', 'ts', 'va'] -Databases are discussed further in `Section 2.7 `__. + +Databases are discussed further in `Section 2.7 `__. diff --git a/docs/source/manual/cdms_2.rst b/docs/source/manual/cdms_2.rst index 253c8098..a6e1fb21 100644 --- a/docs/source/manual/cdms_2.rst +++ b/docs/source/manual/cdms_2.rst @@ -1,8 +1,13 @@ -CHAPTER 2 CDMS Python Application Programming Interface -------------------------------------------------------- +=============================================== + CDMS Python Application Programming Interface +=============================================== -2.1 Overview -^^^^^^^^^^^^ +Overview +^^^^^^^^ + + +.. highlight:: python + :linenothreshold: 3 .. testsetup:: * @@ -35,38 +40,31 @@ an application. This chapter documents the cdms, cdtime, and regrid modules. The chapter sections correspond to the CDMS classes. Each section -contains tables base. If no parent, the datapath is absolute.describing +contains table +s base. If no parent, the datapath is absolute.describing the class internal (non-persistent) attributes, constructors (functions for creating an object), and class methods (functions). A method can return an instance of a CDMS class, or one of the Python types: - -Table 2.1 Python types used in CDMS - -+--------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Type | Description | -+==============+=======================================================================================================================================================================================================+ -| Array | Numeric or masked multidimensional data array. All elements of the array are of the same type. Defined in the Numeric and MA modules. | -+--------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Comptime | Absolute time value, a time with representation (year, month, day, hour, minute, second). Defined in the cdtime module. cf. reltime | -+--------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Dictionary | An unordered 2,3collection of objects, indexed by key. All dictionaries in CDMS are indexed by strings, e.g.: ``axes['time']`` | -+--------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Float | Floating-point value. | -+--------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Integer | Integer value. | -+--------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| List | An ordered sequence of objects, which need not be of the same type. New members can be inserted or appended. Lists are denoted with square brackets, e.g., ``[1, 2.0, 'x', 'y']`` | -+--------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| None | No value returned. | -+--------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Reltime | Relative time value, a time with representation (value, units since basetime). Defined in the cdtime module. cf. comptime | -+--------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Tuple | An ordered sequence of objects, which need not be of the same type. Unlike lists, tuples elements cannot be inserted or appended. Tuples are denoted with parentheses, e.g., ``(1, 2.0, 'x', 'y')`` | -+--------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -2.2 A first example -^^^^^^^^^^^^^^^^^^^ +Table PythonTypes used in CDMS +------------------------------- +.. csv-table:: + :header: "Type", "Description" + :widths: 10, 80 + :align: left + + "Array", "Numpy or masked multidimensional data array. All elements of the array are of the same type. Defined in the Numpy and MV2 modules." + "Comptime", "Absolute time value, a time with representation (year, month, day, hour, minute, second). Defined in the cdtime module. cf. reltime" + "Dictionary","An unordered 2,3collection of objects, indexed by key. All dictionaries in CDMS are indexed by strings, e.g.: ``axes['time']``" + "Float", "Floating-point value." + "Integer", "Integer value." + "List", "An ordered sequence of objects, which need not be of the same type. New members can be inserted or appended. Lists are denoted with square brackets, e.g., ``[1, 2.0, 'x', 'y']``" + "None", "No value returned." + "Reltime", "Relative time value, a time with representation (value, units since basetime). Defined in the cdtime module. cf. comptime" + "Tuple", "An ordered sequence of objects, which need not be of the same type. Unlike lists, tuples elements cannot be inserted or appended. Tuples are denoted with parentheses, e.g., ``(1, 2.0, 'x', 'y')``" + +A First Example +^^^^^^^^^^^^^^^ The following Python script reads January and July monthly temperature data from an input dataset, averages over time, and writes the results @@ -97,371 +95,150 @@ latitude, longitude). >>> out.close() -+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Line | Notes | -+========+=====================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+ -| 2,3 | Makes the CDMS and MV modules available. MV defines arithmetic functions. | -+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 4 | Opens a netCDF file read-only. The result jones is a dataset object. | -+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 5 | Gets the surface air temperature variable. ‘tas’ is the name of the variable in the input dataset. This does not actually read the data. | -+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 6 | Read all January monthly mean data into a variable jans. Variables can be sliced like arrays. The slice operator [0::12] means take every 12th slice from dimension 0, starting at index 0 and ending at the last index. If the stride 12 were omitted, it would default to 1. Note that the variable is actually 3-dimensional. Since no slice is specified for the second or third dimensions, all values of those 2,3 dimensions are retrieved. The slice operation could also have been written [0::12, : , :]. Also note that the same script works for multi-file datasets. CDMS opens the needed data files, extracts the appropriate slices, and concatenates them into the result array. | -+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 7 | Reads all July data into a masked array julys. | -+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 8 | Calculate the average January value for each grid zone. Any missing data is handled automatically. | -+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 9,10 | Set the variable id and long\_name attributes. The id is used as the name of the variable when plotted or written to a file. | -+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 14 | Create a new netCDF output file named ‘janjuly.nc’ to hold the results. | -+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 15 | Write the January average values to the output file. The variable will have id “tas\_jan” in the file. ``write`` is a utility function which creates the variable in the file, then writes data to the variable. A more general method of data output is first to create a variable, then set a slice of the variable. Note that janavg and julavg have the same latitude and longitude information as tasvar. It is carried along with the computations. | -+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 17 | Set the global attribute ‘comment’. | -+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 18 | Close the output file. | -+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - - -2.3 cdms module +.. csv-table:: + :header: "Line", "Notes" + :widths: 10, 80 -The cdms module is the Python interface to CDMS. The objects and methods -in this chapter are made accessible with the command: + "2,3", "Makes the CDMS and MV modules available. MV defines arithmetic functions." + "4", "Opens a netCDF file read-only. The result jones is a dataset object." + "5", "Gets the surface air temperature variable. ‘tas’ is the name of the variable in the input dataset. This does not actually read the data." + "6", "Read all January monthly mean data into a variable jans. Variables can be sliced like arrays. The slice operator [0::12] means take every 12th slice from dimension 0, starting at index 0 and ending at the last index. If the stride 12 were omitted, it would default to 1. Note that the variable is actually 3-dimensional. Since no slice is specified for the second or third dimensions, all values of those 2,3 dimensions are retrieved. The slice operation could also have been written [0::12, : , :]. Also note that the same script works for multi-file datasets. CDMS opens the needed data files, extracts the appropriate slices, and concatenates them into the result array." + "7", "Reads all July data into a masked array julys." + "8", "Calculate the average January value for each grid zone. Any missing data is handled automatically." + "9,10", "Set the variable id and long\_name attributes. The id is used as the name of the variable when plotted or written to a file." + "14", "Create a new netCDF output file named ‘janjuly.nc’ to hold the results." + "15", "Write the January average values to the output file. The variable will have id “tas\_jan” in the file. ``write`` is a utility function which creates the variable in the file, then writes data to the variable. A more general method of data output is first to create a variable, then set a slice of the variable. Note that janavg and julavg have the same latitude and longitude information as tasvar. It is carried along with the computations." + "17", "Set the global attribute ‘comment’." + "18", "Close the output file." -.. raw:: html -
-:: - import cdms2 +Cdms Module +^^^^^^^^^^^ -.. raw:: html +The cdms module is the Python interface to CDMS. The objects and methods +in this chapter are made accessible with the command: + +.. doctest:: + + import cdms2 -
The functions described in this section are not associated with a class. Rather, they are called as module functions, e.g., -.. raw:: html +.. doctest:: -
+ file = cdms2.open('sample.nc') -:: - file = cdms2.open('sample.nc') -.. raw:: html - -
- - -Table 2.2 cdms module functions - -+-------------+-------------------------------------------------------------------------+ -| Type | Definition | -+=============+=========================================================================+ -| ``Variable``| ``asVariable(s)``: Transform ``s`` | -| | into a transient variable. ``s`` is | -| | a masked array, Numeric array, or | -| | Variable. If ``s`` is already a | -| | transient variable, ``s`` is | -| | returned. See also: ``isVariable``. | -+-------------+-------------------------------------------------------------------------+ -| ``Axis`` | ``createAxis(data, bounds=None)``: | -| | Create a one-dimensional coordinate | -| | Axis, which is not associated with a | -| | file or dataset. This is useful for | -| | creating a grid which is not | -| | contained in a file or dataset. | -| | ``data`` is a one-dimensional, | -| | monotonic Numeric array. ``bounds`` | -| | is an array of shape | -| | ``(len(data),2)``, such that for all | -| | ``i``, ``data[i]`` is in the range | -| | ``[bounds[i,0],bounds[i,1] ]``. If | -| | ``bounds`` is not specified, the | -| | default boundaries are generated at | -| | the midpoints between the | -| | consecutive data values, provided | -| | that the autobounds mode is 'on' | -| | (the default). See | -| | ``setAutoBounds``. Also see: | -| | ``CdmsFile.createAxis`` | -+-------------+-------------------------------------------------------------------------+ -| ``Axis`` | ``createEqualAreaAxis(nlat)``: | -| | Create an equal-area latitude axis. | -| | The latitude values range from north | -| | to south, and for all axis values | -| | ``x[i]``, ``sin(x[i])sin(x[i+1])`` | -| | is constant. ``nlat`` is the axis | -| | length. The axis is not associated | -| | with a file or dataset. | -+-------------+-------------------------------------------------------------------------+ -| ``Axis`` | ``createGaussianAxis(nlat)``: Create | -| | a Gaussian latitude axis. Axis | -| | values range from north to south. | -| | ``nlat`` is the axis length. The | -| | axis is not associated with a file | -| | or dataset. | -+-------------+-------------------------------------------------------------------------+ -| ``RectGrid``| ``createGaussianGrid(nlats, xorigin= | -| | 0.0, order="yx")``: | -| | Create a Gaussian grid, with shape | -| | ``(nlats, 2*nlats)``. ``nlats`` is | -| | the number of latitudes. ``xorigin`` | -| | is the origin of the longitude axis. | -| | ``order`` is either "yx" (lat-lon, | -| | default) or "xy" (lon-lat) | -+-------------+-------------------------------------------------------------------------+ -| ``RectGrid``| ``createGenericGrid(latArray, lonArray, latBounds=None, lonBounds=None, | -| | order="yx", mask=None)``: | -| | Create a generic grid, that is, a | -| | grid which is not typed as Gaussian, | -| | uniform, or equal-area. The grid is | -| | not associated with a file or | -| | dataset. ``latArray`` is a NumPy | -| | array of latitude values. | -| | ``lonArray`` is a NumPy array of | -| | longitude values. ``latBounds`` is a | -| | NumPy array having shape | -| | ``(len(latArray),2)``, of latitude | -| | boundaries. ``lonBounds`` is a NumPy | -| | array having shape | -| | ``(len(lonArray),2)``, of longitude | -| | boundaries. ``order`` is a | -| | ``string`` specifying the order of | -| | the axes, either "yx" for (latitude, | -| | longitude), or "xy" for the reverse. | -| | ``mask`` (optional) is an | -| | ``integer``-valued NumPy mask array, | -| | having the same shape and ordering | -| | as the grid. | -+-------------+-------------------------------------------------------------------------+ -| ``RectGrid``| ``createGlobalMeanGrid(grid)``: | -| | Generate a grid for calculating the | -| | global mean via a regridding | -| | operation. The return grid is a | -| | single zone covering the range of | -| | the input grid. ``grid`` is a | -| | RectGrid. | -+-------------+-------------------------------------------------------------------------+ -| ``RectGrid``| ``createRectGrid(lat, lon, order, ty | -| | pe="generic", mask=None)``: | -| | Create a rectilinear grid, not | -| | associated with a file or dataset. | -| | This might be used as the target | -| | grid for a regridding operation. | -| | ``lat`` is a latitude axis, created | -| | by ``cdms.createAxis``. ``lon`` is a | -| | longitude axis, created by | -| | ``cdms.createAxis``. ``order`` is a | -| | string with value "yx" (the first | -| | grid dimension is latitude) or "xy" | -| | (the first grid dimension is | -| | longitude). ``type`` is one of | -| | 'gaussian','uniform','equalarea',or | -| | 'generic'. If specified, ``mask`` is | -| | a two-dimensional, logical Numeric | -| | array (all values are zero or one) | -| | with the same shape as the grid. | -+-------------+-------------------------------------------------------------------------+ -| ``RectGrid``| ``createUniformGrid(startLat, nlat, | -| | deltaLat, start-Lon, nlon, deltaLon, | -| | order="yx", mask=None)``: | -| | Create a uniform rectilinear grid. | -| | The grid is not associated with a | -| | file or dataset. The grid boundaries | -| | are at the midpoints of the axis | -| | values. ``startLat`` is the starting | -| | latitude value. ``nlat`` is the | -| | number of latitudes. If ``nlat`` is | -| | 1, the grid latitude boundaries will | -| | be ``startLat`` +/- ``deltaLat/2``. | -| | ``deltaLat`` is the increment | -| | between latitudes. ``startLon`` is | -| | the starting longitude value. | -| | ``nlon`` is the number of | -| | longitudes. If ``nlon`` is 1, the | -| | grid longitude boundaries will be | -| | ``startLon`` +/- ``deltaLon/2``. | -| | ``deltaLon`` is the increment | -| | between longitudes. ``order`` is a | -| | string with value "yx" (the first | -| | grid dimension is latitude) or "xy" | -| | (the first grid dimension is | -| | longitude). If specified, ``mask`` | -| | is a two-dimensional, logical | -| | Numeric array (all values are zero | -| | or one) with the same shape as the | -| | grid. | -+-------------+-------------------------------------------------------------------------+ -| ``Axis`` | ``createUniformLatitudeAxis(startLat | -| | , nlat, deltaLat)``: | -| | Create a uniform latitude axis. The | -| | axis boundaries are at the midpoints | -| | of the axis values. The axis is | -| | designated as a circular latitude | -| | axis. ``startLat`` is the starting | -| | latitude value. ``nlat`` is the | -| | number of latitudes. ``deltaLat`` is | -| | the increment between latitudes. | -+-------------+-------------------------------------------------------------------------+ -| ``RectGrid``| ``createZonalGrid(grid)``: Create a | -| | zonal grid. The output grid has the | -| | same latitude as the input grid, and | -| | a single longitude. This may be used | -| | to calculate zonal averages via a | -| | regridding operation. ``grid`` is a | -| | RectGrid. | -+-------------+-------------------------------------------------------------------------+ -| ``Axis`` | ``createUniformLongitudeAxis(startLo | -| | n, nlon, delta-Lon)``: | -| | Create a uniform longitude axis. The | -| | axis boundaries are at the midpoints | -| | of the axis values. The axis is | -| | designated as a circular longitude | -| | axis. ``startLon`` is the starting | -| | longitude value. ``nlon`` is the | -| | number of longitudes. ``deltaLon`` | -| | is the increment between longitudes. | -+-------------+-------------------------------------------------------------------------+ -| ``Variable``| ``createVariable(array, typecode=Non | -| | e, copy=0, savespace=0, mask=None, f | -| | ill_value=None, grid=None, axes=None | -| | , attributes=None, id=None)``: | -| | This function is documented in Table | -| | 2.34 on page 90. | -+-------------+-------------------------------------------------------------------------+ -| ``Integer`` | ``getAutoBounds()``: Get the current | -| | autobounds mode. Returns 0, 1, or 2. | -| | See ``setAutoBounds``. | -+-------------+-------------------------------------------------------------------------+ -| ``Integer`` | ``isVariable(s)``: Return ``1`` if | -| | ``s`` is a variable, ``0`` | -| | otherwise. See also: ``asVariable``. | -+-------------+-------------------------------------------------------------------------+ -| ``Dataset`` | ``open(url,mode='r')``: Open or | -| | create a ``Dataset`` or | -| | ``CdmsFile``. ``url`` is a Uniform | -| | Resource Locator, referring to a | -| | cdunif or XML file. If the URL has | -| | the extension '.xml' or '.cdml', a | -| | ``Dataset`` is returned, otherwise a | -| | ``CdmsFile`` is returned. If the URL | -| | protocol is 'http', the file must be | -| | a '.xml' or '.cdml' file, and the | -| | mode must be 'r'. If the protocol is | -| | 'file' or is omitted, a local file | -| | or dataset is opened. ``mode`` is | -| | the open mode. See Table 2.24 on | -| | page 70. | -| | **Example**: Open an existing | -| | dataset: | -| | ``f = cdms.open("sampleset.xml")`` | -| | | -| | **Example**: Create a netCDF file: | -| | ``f = cdms.open("newfile.nc",'w')`` | -+-------------+-------------------------------------------------------------------------+ -| ``List`` | ``order2index (axes, orderstring)``: | -| | Find the index permutation of axes | -| | to match order. Return a list of | -| | indices. ``axes`` is a list of axis | -| | objects. ``orderstring`` is defined | -| | as in ``orderparse``. | -+-------------+-------------------------------------------------------------------------+ -| ``List`` | ``orderparse(orderstring)``: Parse | -| | an order string. Returns a list of | -| | axes specifiers. ``orderstring`` | -| | consists of: | -| | | -| | - Letters t, x, y, z meaning time, | -| | longitude, latitude, level | -| | - Numbers 0-9 representing position | -| | in axes | -| | - Dash (-) meaning insert the next | -| | available axis here. | -| | - The ellipsis ... meaning fill | -| | these positions with any | -| | remaining axes. | -| | - (name) meaning an axis whose id | -| | is name | -+-------------+-------------------------------------------------------------------------+ -| ``None`` | ``setAutoBounds(mode)``: Set | -| | autobounds mode. In some | -| | circumstances CDMS can generate | -| | boundaries for 1-D axes and | -| | rectilinear grids, when the bounds | -| | are not explicitly defined. The | -| | autobounds mode determines how this | -| | is done: If ``mode`` is ``'grid'`` | -| | or ``2`` (the default), the | -| | ``getBounds`` method will | -| | automatically generate boundary | -| | information for an axis or grid if | -| | the axis is designated as a latitude | -| | or longitude axis, and the | -| | boundaries are not explicitly | -| | defined. If ``mode`` is ``'on'`` or | -| | ``1``, the ``getBounds`` method will | -| | automatically generate boundary | -| | information for an axis or grid, if | -| | the boundaries are not explicitly | -| | defined. If ``mode`` is ``'off'`` or | -| | ``0``, and no boundary data is | -| | explicitly defined, the bounds will | -| | NOT be generated; the ``getBounds`` | -| | method will return ``None`` for the | -| | boundaries. Note: In versions of | -| | CDMS prior to V4.0, the default | -| | ``mode`` was ``'on'``. | -+-------------+-------------------------------------------------------------------------+ -| ``None`` | ``setClassifyGrids(mode)``: Set the | -| | grid classification mode. This | -| | affects how grid type is determined, | -| | for the purpose of generating grid | -| | boundaries. If ``mode`` is ``'on'`` | -| | (the default), grid type is | -| | determined by a grid classification | -| | method, regardless of the value of | -| | ``grid.get-Type()``. If ``mode`` is | -| | ``'off'``, the value of | -| | ``grid.getType()`` determines the | -| | grid type | -+-------------+-------------------------------------------------------------------------+ -| ``None`` | ``writeScripGrid(path, grid, gridTit | -| | le=None)``: | -| | Write a grid to a SCRIP grid file. | -| | ``path`` is a string, the path of | -| | the SCRIP file to be created. | -| | ``grid`` is a CDMS grid object. It | -| | may be rectangular. ``gridTitle`` is | -| | a string ID for the grid. | -+-------------+-------------------------------------------------------------------------+ - - -Table 2.3 Class Tags - -+--------------+---------------------+ -| Tag | Class | -+==============+=====================+ -| ‘axis’ | Axis | -+--------------+---------------------+ -| ‘database’ | Database | -+--------------+---------------------+ -| ‘dataset’ | Dataset, CdmsFile | -+--------------+---------------------+ -| ‘grid’ | RectGrid | -+--------------+---------------------+ -| ‘variable’ | Variable | -+--------------+---------------------+ -| ‘xlink’ | Xlink | -+--------------+---------------------+ - - -2.4 CdmsObj -^^^^^^^^^^^ +Table Cdms Module Functions +--------------------------- + +.. csv-table:: + :header: "Type", "Definition" + :widths: 10, 80 + :align: left + + + "``Variable``", "``asVariable(s)``: Transform ``s`` into a transient variable. ``s`` is a masked array, Numpy array, or Variable. If ``s`` is already a transient variable, ``s`` is returned. See also: ``isVariable``." + "``Axis``", "``createAxis(data, bounds=None)``:" + , "Create a one-dimensional coordinate Axis, which is not associated with a file or dataset. This is useful for creating a grid which is not contained in a file or dataset." + , " * ``data`` is a one-dimensional, monotonic Numpy array. ``bounds`` is an array of shape ``(len(data),2)``, such that for all ``i``, ``data[i]`` is in the range ``[bounds[i,0],bounds[i,1] ]``. If ``bounds`` is not specified, the default boundaries are generated at the midpoints between the consecutive data values, provided that the autobounds mode is 'on' (the default)." + , " * See ``setAutoBounds``." + , " * Also see: ``CdmsFile.createAxis``" + "``Axis``", "``createEqualAreaAxis(nlat)``:" + , "Create an equal-area latitude axis. The latitude values range from north to south, and for all axis values ``x[i]``, ``sin(x[i])sin(x[i+1])`` is constant. ``nlat`` is the axis length. The axis is not associated with a file or dataset." + "``Axis``", "``createGaussianAxis(nlat)``:" + , "Create a Gaussian latitude axis. Axis values range from north to south. ``nlat`` is the axis length. The axis is not associated with a file or dataset." + "``RectGrid``", "``createGaussianGrid(nlats, xorigin=0.0, order='yx')``:" + , "Create a Gaussian grid, with shape ``(nlats, 2*nlats)``. ``nlats`` is the number of latitudes. ``xorigin`` is the origin of the longitude axis. ``order`` is either 'yx' (lat-lon, default) or 'xy' (lon-lat)" + "``RectGrid``", "``createGenericGrid(latArray, lonArray, latBounds=None, lonBounds=None, order='yx', mask=None)``:" + , "Create a generic grid, that is, a grid which is not typed as Gaussian, uniform, or equal-area. The grid is not associated with a file or dataset. ``latArray`` is a NumPy array of latitude values." + , " * ``lonArray`` is a NumPy array of longitude values. " + , " * ``latBounds`` is a NumPy array having shape ``(len(latArray),2)``, of latitude boundaries. " + , " * ``lonBounds`` is a NumPy array having shape ``(len(lonArray),2)``, of longitude boundaries. " + , " * ``order`` is a ``string`` specifying the order of the axes, either 'yx' for (latitude, longitude), or 'xy' for the reverse." + , " * ``mask`` (optional) is an ``integer``-valued NumPy mask array, having the same shape and ordering as the grid." + + "``RectGrid``", "``createGlobalMeanGrid(grid)``:" + , "Generate a grid for calculating the global mean via a regridding operation. The return grid is a single zone covering the range of he input grid. ``grid`` is a RectGrid." + + "``RectGrid``", "``createRectGrid(lat, lon, order, type='generic', mask=None)``:" + , "Create a rectilinear grid, not associated with a file or dataset. This might be used as the target grid for a regridding operation." + , " * ``lat`` is a latitude axis, created by ``cdms.createAxis``." + , " * ``lon`` is a longitude axis, created by ``cdms.createAxis``." + , " * ``order`` is a string with value 'yx' (the first grid dimension is latitude) or 'xy' (the first grid dimension is longitude)." + , " * ``type`` is one of 'gaussian','uniform','equalarea',or 'generic'." + , " * If specified, ``mask`` is a two-dimensional, logical Numpy array (all values are zero or one) with the same shape as the grid." + + "``RectGrid``", "``createUniformGrid(startLat, nlat, deltaLat, start-Lon, nlon, deltaLon, order='yx', mask=None)``:" + , "Create a uniform rectilinear grid. The grid is not associated with a file or dataset. The grid boundaries are at the midpoints of the axis values." + , " * ``startLat`` is the starting latitude value." + , " * ``nlat`` is the number of latitudes. If ``nlat`` is 1, the grid latitude boundaries will be ``startLat`` +/- ``deltaLat/2``." + , " * ``deltaLat`` is the increment between latitudes. ``startLon`` is the starting longitude value." + , " * ``nlon`` is the number of longitudes. If ``nlon`` is 1, the grid longitude boundaries will be ``startLon`` +/- ``deltaLon/2``." + , " * ``deltaLon`` is the increment between longitudes. ``order`` is a string with value 'yx. (the first grid dimension is latitude) or .xy. (the first grid dimension is longitude)." + , " * If specified, ``mask`` is a two-dimensional, logical Numpy array (all values are zero or one) with the same shape as the grid." + "``Axis``", "``createUniformLatitudeAxis(startLat , nlat, deltaLat)``:" + , "Create a uniform latitude axis. The axis boundaries are at the midpoints of the axis values. The axis is designated as a circular latitude axis." + , " * ``startLat`` is the starting latitude value." + , " * ``nlat`` is the number of latitudes." + , " * ``deltaLat`` is the increment between latitudes." + "``RectGrid``"," ``createZonalGrid(grid)``: Create a zonal grid. The output grid has the same latitude as the input grid, and a single longitude. This may be used to calculate zonal averages via a regridding operation. ``grid`` is a RectGrid." + "``Axis``", "``createUniformLongitudeAxis(startLon, nlon, delta-Lon)``:" + , "Create a uniform longitude axis. The axis boundaries are at the midpoints of the axis values. The axis is designated as a circular longitude axis." + , " * ``startLon`` is the starting longitude value." + , " * ``nlon`` is the number of longitudes." + , " * ``deltaLon`` is the increment between longitudes." + "``Variable``", "``createVariable(array, typecode=None, copy=0, savespace=0, mask=None, fill_value=None, grid=None, axes=None , attributes=None, id=None)``:" + "``Integer``", "``getAutoBounds()``: Get the current autobounds mode. Returns 0, 1, or 2." + , " * See ``setAutoBounds``." + "``Integer``", "``isVariable(s)``: " + , " * Return ``1`` if ``s`` is a variable, ``0`` otherwise. See also: ``asVariable``." + "``Dataset``", "``open(url,mode='r')``: Open or create a ``Dataset`` or ``CdmsFile``." + , " * ``url`` is a Uniform Resource Locator, referring to a cdunif or XML file. If the URL has the extension '.xml' or '.cdml', a ``Dataset`` is returned, otherwise a ``CdmsFile`` is returned." + , " * If the URL protocol is 'http', the file must be a '.xml' or '.cdml' file, and the mode must be 'r'. If the protocol is 'file' or is omitted, a local file or dataset is opened. ``mode`` is the open mode. See `Open Modes <#table-open-modes>`__" + , " * **Example**: Open an existing dataset: ``f = cdms.open('sampleset.xml')``" + , " * **Example**: Create a netCDF file: ``f = cdms.open('newfile.nc','w')``" + "``List``", "``order2index (axes, orderstring)``:" + , "Find the index permutation of axes to match order. Return a list of indices. ``axes`` is a list of axis objects. ``orderstring`` is defined as in ``orderparse``." + "``List``", "``orderparse(orderstring)``:" + , "Parse an order string. Returns a list of axes specifiers. ``orderstring`` consists of:" + + , " * Letters t, x, y, z meaning time, longitude, latitude, level" + , " * Numbers 0-9 representing position in axes" + , " * Dash (-) meaning insert the next available axis here." + , " * The ellipsis ... meaning fill these positions with any remaining axes." + , " * (name) meaning an axis whose id is name" + "``None``", "``setAutoBounds(mode)``:" + , "Set autobounds mode. In some circumstances CDMS can generate boundaries for 1-D axes and rectilinear grids, when the bounds are not explicitly defined. The autobounds mode determines how this is done: If ``mode`` is ``'grid'`` or ``2`` (the default), the ``getBounds`` method will automatically generate boundary information for an axis or grid if the axis is designated as a latitude or longitude axis, and the boundaries are not explicitly defined. If ``mode`` is ``'on'`` or ``1``, the ``getBounds`` method will automatically generate boundary information for an axis or grid, if the boundaries are not explicitly defined. If ``mode`` is ``'off'`` or ``0``, and no boundary data is explicitly defined, the bounds will NOT be generated; the ``getBounds`` method will return ``None`` for the boundaries. Note: In versions of CDMS prior to V4.0, the default ``mode`` was ``'on'``." + "``None``", "``setClassifyGrids(mode)``:" + , "Set the grid classification mode. This affects how grid type is determined, for the purpose of generating grid boundaries. If ``mode`` is ``'on'`` (the default), grid type is determined by a grid classification method, regardless of the value of ``grid.get-Type()``. If ``mode`` is ``'off'``, the value of ``grid.getType()`` determines the grid type." + "``None``", "``writeScripGrid(path, grid, gridTitle=None)``:" + , "Write a grid to a SCRIP grid file. ``path`` is a string, the path of the SCRIP file to be created. ``grid`` is a CDMS grid object. It may be rectangular. ``gridTitle`` is a string ID for the grid." + + + + +Table Class Tags +-------------------- +.. csv-table:: + :header: "Tag", "Class" + :widths: 20, 20 + + "‘axis’", "Axis" + "‘database’", "Database" + "‘dataset’", "Dataset, CdmsFile " + "‘grid’", "RectGrid" + "‘variable’", "Variable" + "‘xlink’", "Xlink" + + +CdmsObj +^^^^^^^ A CdmsObj is the base class for all CDMS database objects. At the application level, CdmsObj objects are never created and used directly. @@ -477,53 +254,36 @@ external attributes are written, but not the internal attributes. **Example**: get a list of all external attributes of obj. -.. raw:: html - -
- -:: +.. doctest:: extatts = obj.attributes.keys() -.. raw:: html +Table Attributes Common to All CDMS Objects +------------------------------------------- -
+.. csv-table:: Attributes common to all CDMS objects + :header: "Type", "Name", "Definition" + :widths: 20, 20, 50 + "Dictionary", "attributes", "External attribute dictionary for this object." -Table 2.4 Attributes common to all CDMS objects -+--------------+--------------+--------------------------------------------------+ -| Type | Name | Definition | -+==============+==============+==================================================+ -| Dictionary | attributes | External attribute dictionary for this object. | -+--------------+--------------+--------------------------------------------------+ +Table Getting and Setting Attributes +------------------------------------ +.. csv-table:: + :header: "Type", "Definition" + :widths: 20, 80 + "various", "``value = obj.attname``" + , "Get an internal or external attribute value. If the attribute is external, it is read from the database. If the attribute is not already in the database, it is created as an external attribute. Internal attributes cannot be created, only referenced." + "various", "``obj.attname = value``" + , "Set an internal or external attribute value. If the attribute is external, it is written to the database." -Table 2.5 Getting and setting attributes -+--------------------------------------+--------------------------------------+ -| Type | Definition | -+======================================+======================================+ -| various | ``value = obj.attname`` | -| | Get an internal or external | -| | attribute value. If the attribute is | -| | external, it is read from the | -| | database. If the attribute is not | -| | already in the database, it is | -| | created as an external attribute. | -| | Internal attributes cannot be | -| | created, only referenced. | -+--------------------------------------+--------------------------------------+ -| various | ``obj.attname = value`` | -| | Set an internal or external | -| | attribute value. If the attribute is | -| | external, it is written to the | -| | database. | -+--------------------------------------+--------------------------------------+ -2.5 CoordinateAxis -^^^^^^^^^^^^^^^^^^ +CoordinateAxis +^^^^^^^^^^^^^^ A CoordinateAxis is a variable that represents coordinate information. It may be contained in a file or dataset, or may be transient @@ -531,561 +291,267 @@ It may be contained in a file or dataset, or may be transient file, and referencing a file CoordinateAxis slice reads data from the file. Axis objects are also used to define the domain of a Variable. -CDMS defines several different types of CoordinateAxis objects. Table -2.9 on page 45 documents methods that are common to all CoordinateAxis -types. Table 2.10 on page 48 specifies methods that are unique to 1D +CDMS defines several different types of CoordinateAxis objects. See `MV module <#id3>`_ +documents methods that are common to all CoordinateAxis +types. See `HorizontalGrid <#id4>`_ specifies methods that are unique to 1D Axis objects. - -Table 2.6 CoordinateAxis types - -+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Type | Definition | -+======================+=====================================================================================================================================================================================================================================================================================================================================================================================================================================================+ -| ``CoordinateAxis`` | A variable that represents coordinate information. Has subtypes ``Axis2D`` and ``AuxAxis1D``. | -+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``Axis`` | A one-dimensional coordinate axis whose values are strictly monotonic. Has subtypes ``DatasetAxis``, ``FileAxis``, and ``TransientAxis``. May be an index axis, mapping a range of integers to the equivalent floating point value. If a latitude or longitude axis, may be associated with a ``RectGrid``. | -+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``Axis2D`` | A two-dimensional coordinate axis, typically a latitude or longitude axis related to a ``CurvilinearGrid``. Has subtypes ``DatasetAxis2D``, ``FileAxis2D``, and ``TransientAxis2D``. | -+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``AuxAxis1D`` | A one-dimensional coordinate axis whose values need not be monotonic. Typically a latitude or longitude axis associated with a ``GenericGrid``. Has subtypes ``DatasetAuxAxis1D``, ``FileAuxAxis1D``, and ``TransientAuxAxis1D``. An axis in a ``CdmsFile`` may be designated the unlimited axis, meaning that it can be extended in length after the initial definition. There can be at most one unlimited axis associated with a ``CdmsFile``. | -+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - - -Table 2.7 CoordinateAxis Internal Attributes - -+------------------+------------------+--------------------------------------------+ -| Type | Name | Definition | -+==================+==================+============================================+ -| ``Dictionary`` | ``attributes`` | External attribute dictionary. | -+------------------+------------------+--------------------------------------------+ -| ``String`` | ``id`` | CoordinateAxis identifer. | -+------------------+------------------+--------------------------------------------+ -| ``Dataset`` | ``parent`` | The dataset which contains the variable. | -+------------------+------------------+--------------------------------------------+ -| ``Tuple`` | ``shape`` | The length of each axis. | -+------------------+------------------+--------------------------------------------+ - - -Table 2.8 Axis Constructors - -+-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Constructor | Description | -+=================================================================+==========================================================================================================================================================================================================================================================================================================================================================================================+ -| ``cdms.createAxis(data, bounds=None)`` | Create an axis which is not associated with a dataset or file. See Table 2.2 on page 33. | -+-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``Dataset.createAxis(name,ar)`` | Create an ``Axis`` in a ``Dataset``. (This function is not yet implemented. ) | -+-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``CdmsFile.createAxis(name,ar,unlimited=0)`` | Create an Axis in a ``CdmsFile``. ``name`` is the string ``name`` of the ``Axis``. ``ar`` is a 1-D data array which defines the ``Axis`` values. It may have the value ``None`` if an unlimited axis is being defined. At most one ``Axis`` in a ``CdmsFile`` may be designated as being unlimited, meaning that it may be extended in length. To define an axis as unlimited, either: | -+-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -|   | A) set ``ar`` to ``None``, and leave ``unlimited`` undefined, or | -+-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -|   | B) set ``ar`` to the initial 1-D array, and set ``unlimited`` to ``cdms.Unlimited`` | -+-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``cdms.createEqualAreaAxis(nlat)`` | See Table 2.2 on page 33. | -+-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``cdms.createGaussianAxis(nlat)`` | See Table 2.2 on page 18. | -+-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``cdms.createUniformLatitudeAxis(startlat, nlat, deltalat)`` | See Table 2.2 on page 18. | -+-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``cdms.createUniformLongitudeAxis(startlon, nlon, deltalon)`` | See Table 2.2 on page 18. | -+-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - - -Table 2.9 CoordinateAxis Methods - -+---------------+--------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Type | Method | Definition | -+===============+====================================================================+================================================================================================================================================================================================================================================================================+ -| ``Array`` | ``array = axis[i:j]`` | Read a slice of data from the external file or dataset. Data is returned in the physical ordering defined in the dataset. See Table 2.11 on page 51 for a description of slice operators. | -+---------------+--------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``None`` | ``axis[i:j] = array`` | Write a slice of data to the external file. Dataset axes are read-only. | -+---------------+--------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``None`` | ``assignValue(array)`` | Set the entire value of the axis. ``array`` is a Numeric array, of the same dimensionality as the axis. | -+---------------+--------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``Axis`` | ``clone(copyData=1)`` | Return a copy of the axis, as a transient axis. If copyData is 1 (the default) the data itself is copied. | -+---------------+--------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``None`` | ``designateLatitude(persistent=0)`` | Designate the axis to be a latitude axis. If persistent is true, the external file or dataset (if any) is modified. By default, the designation is temporary. | -+---------------+--------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``None`` | ``designateLevel(persistent=0)`` | Designate the axis to be a vertical level axis. If persistent is true, the external file or dataset (if any) is modified. By default, the designation is temporary. | -+---------------+--------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``None`` | ``designateLongitude(persistent=0, modulo=360.0)`` | Designate the axis to be a longitude axis. ``modulo`` is the modulus value. Any given axis value ``x`` is treated as equivalent to ``x + modulus``. If ``persistent`` is true, the external file or dataset (if any) is modified. By default, the designation is temporary. | -+---------------+--------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``None`` | ``designateTime(persistent=0, calendar = cdtime.MixedCalendar)`` | Designate the axis to be a time axis. If ``persistent`` is true, the external file or dataset (if any) is modified. By default, the designation is temporary. ``calendar`` is defined as in ``getCalendar()``. | -+---------------+--------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``Array`` | ``getBounds()`` | Get the associated boundary array. The shape of the return array depends on the type of axis: | -|   |   | * ``Axis``: ``(n,2)`` | -|   |   | * ``Axis2D``: ``(i,j,4)`` | -|   |   | * ``AuxAxis1D``: ``(ncell, nvert)`` where nvert is the maximum number of vertices of a cell. | -|   |   | If the boundary array of a latitude or longitude ``Axis`` is not explicitly defined, and ``autoBounds`` mode is on, a default array is generated by calling ``genGenericBounds``. Otherwise if auto-Bounds mode is off, the return value is ``None``. See ``setAutoBounds``. | -+---------------+--------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``Integer`` | ``getCalendar()`` | Returns the calendar associated with the ``(time)``\ axis. Possible return values, as defined in the ``cdtime`` module, are: | -|   |   | * ``cdtime.GregorianCalendar``: the standard Gregorian calendar | -|   |   | * ``cdtime.MixedCalendar``: mixed Julian/Gregorian calendar | -|   |   | * ``cdtime.JulianCalendar``: years divisible by 4 are leap years | -|   |   | * ``cdtime.NoLeapCalendar``: a year is 365 days | -|   |   | * ``cdtime.Calendar360``: a year is 360 days | -|   |   | * ``None``: no calendar can be identified | -|   |   | Note: If the axis is not a time axis, the global, file-related calendar is returned. | -+---------------+--------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``Array`` | ``getValue()`` | Get the entire axis vector. | -+---------------+--------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``Integer`` | ``isLatitude()`` | Returns true iff the axis is a latitude axis. | -+---------------+--------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``Integer`` | ``isLevel()`` | Returns true iff the axis is a level axis. | -+---------------+--------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``Integer`` | ``isLongitude()`` | Returns true iff the axis is a longitude axis. | -+---------------+--------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``Integer`` | ``isTime()`` | Returns true iff the axis is a time axis. | -+---------------+--------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``Integer`` | ``len(axis)`` | The length of the axis if one-dimensional. If multidimensional, the length of the first dimension. | -+---------------+--------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``Integer`` | ``size()`` | The number of elements in the axis. | -+---------------+--------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``String`` | ``typecode()`` | The ``Numeric`` datatype identifier. | -+---------------+--------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - - -Table 2.10 Axis Methods, additional to CoordinateAxis - -+-------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Type | Method | Definition | -+===============================+===============================================+==========================================================================================================================================================================================================================================================================================================================+ -| ``List`` of component times | ``asComponentTime(calendar=None)`` | ``Array`` version of ``cdtime tocomp``. Returns a ``List`` of component times. | -+-------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``List`` of relative times | ``asRelativeTime()`` | ``Array`` version of ``cdtime torel``. Returns a ``List`` of relative times. | -+-------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``None`` | ``designateCircular(modulo, persistent=0)`` | Designate the axis to be circular. ``modulo`` is the modulus value. Any given axis value ``x`` is treated as equivalent to ``x + modulus``. If ``persistent`` is ``True``, the external file or dataset (if any) is modified. By default, the designation is temporary. | -+-------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``Integer`` | ``isCircular()`` | Returns ``True`` if the axis has circular topology. An axis is defined as circular if: | -|   |   | * ``axis.topology == 'circular'``, or | -|   |   | * ``axis.topology`` is undefined, and the axis is a longitude. The default cycle for circular axes is 360.0 | -+-------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``Integer`` | ``isLinear()`` | Returns ``True`` if the axis has a linear representation. | -+-------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``Tuple`` | ``mapInterval(interval)`` | Same as ``mapIntervalExt``, but returns only the tuple ``(i,j)``, and ``wraparound`` is restricted to one cycle. | -+-------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``(i,j,k)`` | ``mapIntervalExt(interval)`` | Map a coordinate interval to an index ``interval``. ``interval`` is a tuple having one of the forms: | -|   |   | * ``(x,y)`` | -|   |   | * ``(x,y,indicator)`` | -|   |   | * ``(x,y,indicator,cycle)`` | -|   |   | * ``None or ':'`` | -|   |   | * where ``x`` and ``y`` are coordinates indicating the interval ``[x,y)``, and: | -|   |   | * ``indicator`` is a two or three-character string, where the first character is ``'c'`` if the interval is closed on the left, ``'o'`` if open, and the second character has the same meaning for the right-hand point. If present, the third character specifies how the interval should be intersected with the axis| -|   |   | * ``'n'`` - select node values which are contained in the interval | -|   |   | * ``'b'`` -select axis elements for which the corresponding cell boundary intersects the interval | -|   |   | * ``'e'`` - same as n, but include an extra node on either side | -|   |   | * ``'s'`` - select axis elements for which the cell boundary is a subset of the interval | -|   |   | * The default indicator is ‘ccn’, that is, the interval is closed, and nodes in the interval are selected. | -|   |   | * If ``cycle`` is specified, the axis is treated as circular with the given cycle value. By default, if ``axis.isCircular()`` is true, the axis is treated as circular with a default modulus of ``360.0``. | -|   |   | * An interval of ``None`` or ``':'`` returns the full index interval of the axis. | -|   |   | * The method returns the corresponding index interval as a 3tuple ``(i,j,k)``, where ``k`` is the integer stride, and ``[i.j)`` is the half-open index interval ``i <= k < j`` ``(i >= k > j if k < 0)``, or ``none`` if the intersection is empty. | -|   |   | * for an axis which is circular (``axis.topology == 'circular'``), ``[i,j)`` is interpreted as follows, where ``n = len(axis)`` | -|   |   | * if ``0 <= i < n`` and ``0 <= j <= n``, the interval does not wrap around the axis endpoint. | -|   |   | * otherwise the interval wraps around the axis endpoint. | -|   |   | * see also: ``mapinterval``, ``variable.subregion()`` | -+-------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``transientaxis`` | ``subaxis(i,j,k=1)`` | create an axis associated with the integer range ``[i:j:k]``. the stride ``k`` can be positive or negative. wraparound is supported for longitude dimensions or those with a modulus attribute. | -+-------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - - -table 2.11 axis slice operators - -+---------------+-----------------------------------------------------------------------------+ -| slice | definition | -+===============+=============================================================================+ -| ``[i]`` | the ``ith`` element, starting with index ``0`` | -+---------------+-----------------------------------------------------------------------------+ -| ``[i:j]`` | the ``ith`` element through, but not including, element ``j`` | -+---------------+-----------------------------------------------------------------------------+ -| ``[i:]`` | the ``ith`` element through and including the end | -+---------------+-----------------------------------------------------------------------------+ -| ``[:j]`` | the beginning element through, but not including, element ``j`` | -+---------------+-----------------------------------------------------------------------------+ -| ``[:]`` | the entire array | -+---------------+-----------------------------------------------------------------------------+ -| ``[i:j:k]`` | every ``kth`` element, starting at ``i``, through but not including ``j`` | -+---------------+-----------------------------------------------------------------------------+ -| ``[-i]`` | the ``ith`` element from the end. ``-1`` is the last element. | -+---------------+-----------------------------------------------------------------------------+ - -**example:** - -a longitude axis has value ``[0.0, 2.0, ..., 358.0]``, of length -``180``. map the coordinate interval ``-5.0 <= x < 5.0`` to index -interval(s), with wraparound. the result index interval ``-2 <= n < 3`` -wraps around, since ``-2 < 0``, and has a stride of ``1``. this is -equivalent to the two contiguous index intervals ``2 <= n < 0`` and -``0 <= n < 3`` - -.. raw:: html - -
- -:: +Table CoordinateAxis Types +-------------------------- + +.. csv-table:: + :header: "Type", "Definition" + :widths: 20, 80 + + "``CoordinateAxis``", "A variable that represents coordinate information. Has subtypes ``Axis2D`` and ``AuxAxis1D``." + "``Axis``", "A one-dimensional coordinate axis whose values are strictly monotonic. Has subtypes ``DatasetAxis``, ``FileAxis``, and ``TransientAxis``. May be an index axis, mapping a range of integers to the equivalent floating point value. If a latitude or longitude axis, may be associated with a ``RectGrid``." + "``Axis2D``", "A two-dimensional coordinate axis, typically a latitude or longitude axis related to a ``CurvilinearGrid``. Has subtypes ``DatasetAxis2D``, ``FileAxis2D``, and ``TransientAxis2D``." + "``AuxAxis1D``", "A one-dimensional coordinate axis whose values need not be monotonic. Typically a latitude or longitude axis associated with a ``GenericGrid``. Has subtypes ``DatasetAuxAxis1D``, ``FileAuxAxis1D``, and ``TransientAuxAxis1D``. An axis in a ``CdmsFile`` may be designated the unlimited axis, meaning that it can be extended in length after the initial definition. There can be at most one unlimited axis associated with a ``CdmsFile``." + +Table CoordinateAxis Internal Attributes +---------------------------------------- + +.. csv-table:: + :header: "Type", "Name", "Definition" + :widths: 20, 20, 80 + + "``Dictionary``", "``attributes``", "External attribute dictionary." + "``String``", "``id``", "CoordinateAxis identifier." + "``Dataset``", "``parent``", "The dataset which contains the variable." + "``Tuple``", "``shape``", "The length of each axis." + +Table Axis Constructors +----------------------- + +.. csv-table:: + :header: "Constructor", "Description" + :widths: 20, 80 + + "``cdms.createAxis(data, bounds=None)``", "Create an axis which is not associated with a dataset or file. See `A First Example <#a-first-example>`_." + "``Dataset.createAxis(name,ar)``", "Create an ``Axis`` in a ``Dataset``. (This function is not yet implemented.)" + "``CdmsFile.createAxis(name,ar,unlimited=0)``", "Create an Axis in a ``CdmsFile``. ``name`` is the string ``name`` of the ``Axis``. ``ar`` is a 1-D data array which defines the ``Axis`` values. It may have the value ``None`` if an unlimited axis is being defined. At most one ``Axis`` in a ``CdmsFile`` may be designated as being unlimited, meaning that it may be extended in length. To define an axis as unlimited, either:" + , "* A) set ``ar`` to ``None``, and leave ``unlimited`` undefined, or" + , "* B) set ``ar`` to the initial 1-D array, and set ``unlimited`` to ``cdms.Unlitmited``" + , "``cdms.createEqualAreaAxis(nlat)``" + , "* See `A First Example`_." + , "``cdms.createGaussianAxis(nlat)``" + , "* See `A First Example`_." + , "``cdms.createUniformLatitudeAxis(startlat, nlat, deltalat)``" + , "* See `A First Example`_." + , "``cdms.createUniformLongitudeAxis(startlon, nlon, deltalon)``" + , "* See `A First Example`_ ." + + +Table CoordinateAxis Methods +---------------------------- + +.. csv-table:: + :header: "Type", "Method", "Definition" + :widths: 20, 20, 80 + :align: left + + + "``Array``", "``array = axis[i:j]``", "Read a slice of data from the external file or dataset. Data is returned in the physical ordering defined in the dataset. See `Variable Slice Operators <#table-variable-slice-operators>`_ for a description of slice operators." + "``None``", "``axis[i:j] = array``", "Write a slice of data to the external file. Dataset axes are read-only." + "``None``", "``assignValue(array)``", "Set the entire value of the axis. ``array`` is a Numpy array, of the same dimensionality as the axis." + "``Axis``", "``clone(copyData=1)``", "Return a copy of the axis, as a transient axis. If copyData is 1 (the default) the data itself is copied." + "``None``", "``designateLatitude(persistent=0)``", "Designate the axis to be a latitude axis. If persistent is true, the external file or dataset (if any) is modified. By default, the designation is temporary." + "``None``", "``designateLevel(persistent=0)``", "Designate the axis to be a vertical level axis. If persistent is true, the external file or dataset (if any) is modified. By default, the designation is temporary." + "``None``", "``designateLongitude(persistent=0, modulo=360.0)``", "Designate the axis to be a longitude axis. ``modulo`` is the modulus value. Any given axis value ``x`` is treated as equivalent to ``x + modulus``. If ``persistent`` is true, the external file or dataset (if any) is modified. By default, the designation is temporary." + "``None``", "``designateTime(persistent=0, calendar = cdtime.MixedCalendar)``", "Designate the axis to be a time axis. If ``persistent`` is true, the external file or dataset (if any) is modified. By default, the designation is temporary. ``calendar`` is defined as in ``getCalendar()``." + "``Array``", "``getBounds()``", "Get the associated boundary array. The shape of the return array depends on the type of axis:" + ,,"* ``Axis``: ``(n,2)``" + ,,"* ``Axis2D``: ``(i,j,4)``" + ,,"* ``AuxAxis1D``: ``(ncell, nvert)`` where nvert is the maximum number of vertices of a cell." + ,,"If the boundary array of a latitude or longitude ``Axis`` is not explicitly defined, and ``autoBounds`` mode is on, a default array is generated by calling ``genGenericBounds``. Otherwise if auto-Bounds mode is off, the return value is ``None``. See ``setAutoBounds``." + "``Integer``", "``getCalendar()``", "Returns the calendar associated with the ``(time)``\ axis. Possible return values, as defined in the ``cdtime`` module, are:" + ,,"* ``cdtime.GregorianCalendar``: the standard Gregorian calendar" + ,,"* ``cdtime.MixedCalendar``: mixed Julian/Gregorian calendar" + ,,"* ``cdtime.JulianCalendar``: years divisible by 4 are leap years" + ,,"* ``cdtime.NoLeapCalendar``: a year is 365 days" + ,,"* ``cdtime.Calendar360``: a year is 360 days" + ,,"* ``None``: no calendar can be identified" + ,," **Note** If the axis is not a time axis, the global, file-related calendar is returned." + "``Array``", "``getValue()``", "Get the entire axis vector." + "``Integer``", "``isLatitude()``", "Returns true iff the axis is a latitude axis." + "``Integer``", "``isLevel()``", "Returns true iff the axis is a level axis." + "``Integer``", "``isLongitude()``", "Returns true iff the axis is a longitude axis." + "``Integer``", "``isTime()``", "Returns true iff the axis is a time axis." + "``Integer``", "``len(axis)``", "The length of the axis if one-dimensional. If multidimensional, the length of the first dimension." + "``Integer``", "``size()``", "The number of elements in the axis." + "``String``", "``typecode()``", "The ``Numpy`` datatype identifier." + +Table Axis Methods, Additional to CoordinateAxis +------------------------------------------------ + +.. csv-table:: + :header: "Type", "Method", "Definition" + :widths: 20, 20, 80 + :align: left + + + "``List`` of component times", "``asComponentTime(calendar=None)``", "``Array`` version of ``cdtime tocomp``. Returns a ``List`` of component times." + "``List`` of relative times", "``asRelativeTime()``", "``Array`` version of ``cdtime torel``. Returns a ``List`` of relative times." + "``None``", "``designateCircular(modulo, persistent=0)``", "Designate the axis to be circular. ``modulo`` is the modulus value. Any given axis value ``x`` is treated as equivalent to ``x + modulus``. If ``persistent`` is ``True``, the external file or dataset (if any) is modified. By default, the designation is temporary." + "``Integer``", "``isCircular()``", "Returns ``True`` if the axis has circular topology. An axis is defined as circular if:" + ,," * ``axis.topology == 'circular'``, or" + ,," * ``axis.topology`` is undefined, and the axis is a longitude. The default cycle for circular axes is 360.0" + "``Integer``", "``isLinear()``", "Returns ``True`` if the axis has a linear representation." + "``Tuple``", "``mapInterval(interval)``", "Same as ``mapIntervalExt``, but returns only the tuple ``(i,j)``, and ``wraparound`` is restricted to one cycle." + "``(i,j,k)``", "``mapIntervalExt(interval)``", "Map a coordinate interval to an index ``interval``. ``interval`` is a tuple having one of the forms:" + ,,"* ``(x,y)``" + ,,"* ``(x,y,indicator)``" + ,,"* ``(x,y,indicator,cycle)``" + ,,"* ``None or ':'``" + ,,"* where ``x`` and ``y`` are coordinates indicating the interval ``[x,y]``, and:" + ,,"* ``indicator`` is a two or three-character string, where the first character is ``'c'`` if the interval is closed on the left, ``'o'`` if open, and the second character has the same meaning for the right-hand point. If present, the third character specifies how the interval should be intersected with the axis" + ,,"* ``'n'`` - select node values which are contained in the interval" + ,,"* ``'b'`` -select axis elements for which the corresponding cell boundary intersects the interval" + ,,"* ``'e'`` - same as n, but include an extra node on either side" + ,,"* ``'s'`` - select axis elements for which the cell boundary is a subset of the interval" + ,,"* The default indicator is ‘ccn’, that is, the interval is closed, and nodes in the interval are selected." + ,,"* If ``cycle`` is specified, the axis is treated as circular with the given cycle value. By default, if ``axis.isCircular()`` is true, the axis is treated as circular with a default modulus of ``360.0``." + ,,"* An interval of ``None`` or ``':'`` returns the full index interval of the axis." + ,,"* The method returns the corresponding index interval as a 3tuple ``(i,j,k)``, where ``k`` is the integer stride, and ``[i.j)`` is the half-open index interval ``i <= k < j`` ``(i >= k > j if k < 0)``, or ``none`` if the intersection is empty." + ,,"* for an axis which is circular (``axis.topology == 'circular'``), ``[i,j)`` is interpreted as follows, where ``n = len(axis)``" + ,,"* if ``0 <= i < n`` and ``0 <= j <= n``, the interval does not wrap around the axis endpoint." + ,,"* otherwise the interval wraps around the axis endpoint." + ,,"* see also: ``mapinterval``, ``variable.subregion()``" + "``transientaxis``", "``subaxis(i,j,k=1)``", "create an axis associated with the integer range ``[i:j:k]``. the stride ``k`` can be positive or negative. wraparound is supported for longitude dimensions or those with a modulus attribute." + +Table Axis Slice Operators +-------------------------- + +.. csv-table:: + :header: "Slice", "Definition" + :widths: 50, 110 + + "``[i]``", "the ``ith`` element, starting with index ``0``" + "``[i:j]``", "the ``ith`` element through, but not including, element ``j``" + "``[i:]``", "the ``ith`` element through and including the end" + "``[:j]``", "the beginning element through, but not including, element ``j``" + "``[:]``", "the entire array" + "``[i:j:k]``", "every ``kth`` element, starting at ``i``, through but not including ``j``" + "``[-i]``", "the ``ith`` element from the end. ``-1`` is the last element." + , " **Example:** a longitude axis has value" + , " * ``[0.0, 2.0, ..., 358.0]``" + , " * of length ``180``" + , " * map the coordinate interval:" + , " * ``-5.0 <= x < 5.0`` to index interval(s), with wraparound. the result index interval" + , " * ``-2 <= n < 3`` wraps around, since" + , " * ``-2 < 0``, and has a stride of ``1``" + , " * this is equivalent to the two contiguous index intervals" + , " * ``2 <= n < 0`` and ``0 <= n < 3``" + +Example 1 +''''''''''' +.. doctest:: >>> axis.isCircular() 1 >>> axis.mapIntervalExt((-5.0,5.0,'co')) (-2,3,1) -.. raw:: html - -
-2.6 CdmsFile -^^^^^^^^^^^^ +CdmsFile +^^^^^^^^ A ``CdmsFile`` is a physical file, accessible via the ``cdunif`` interface. netCDF files are accessible in read-write mode. All other formats (DRS, HDF, GrADS/GRIB, POP, QL) are accessible read-only. As of CDMS V3, the legacy cuDataset interface is also supported by -Cdms-Files. See “cu Module” on page 180. - - -Table 2.12 CdmsFile Internal Attributes - -+------------------+------------------+---------------------------------------+ -| Type | Name | Definition | -+==================+==================+=======================================+ -| ``Dictionary`` | ``attributes`` | Global, external file attributes | -+------------------+------------------+---------------------------------------+ -| ``Dictionary`` | ``axes`` | Axis objects contained in the file. | -+------------------+------------------+---------------------------------------+ -| ``Dictionary`` | ``grids`` | Grids contained in the file. | -+------------------+------------------+---------------------------------------+ -| ``String`` | ``id`` | File pathname. | -+------------------+------------------+---------------------------------------+ -| ``Dictionary`` | ``variables`` | Variables contained in the file. | -+------------------+------------------+---------------------------------------+ - - -Table 2.13 CdmsFile Constructors - -+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Constructor | Description | -+==========================================+==================================================================================================================================================================================+ -| ``fileobj = cdms.open(path, mode)`` | Open the file specified by path returning a CdmsFile object. ``path`` is the file pathname, a string. ``mode`` is the open mode indicator, as listed in Table 2.24 on page 70. | -+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``fileobj = cdms.createDataset(path)`` | Create the file specified by path, a string. | -+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - - -Table 2.14 CdmsFile Methods - -+--------------------------+--------------------------+--------------------------+ -| Type | Method | Definition | -+==========================+==========================+==========================+ -| ``Transient-Variable`` | ``fileobj(varname, selec | Calling a ``CdmsFile`` | -| | tor)`` | object as a function | -| | | reads the region of data | -| | | specified by the | -| | | ``selector``. The result | -| | | is a transient variable, | -| | | unless ``raw = 1`` is | -| | | specified. See | -| | | "Selectors" on page 103. | -| | | | -| | | **Example:** The | -| | | following reads data for | -| | | variable 'prc', year | -| | | 1980: | -| | | | -| | | :: | -| | | | -| | | f = cdms.open('test. | -| | | nc') | -| | | x = f('prc', time=(' | -| | | 1980-1','1981-1')) | -+--------------------------+--------------------------+--------------------------+ -| ``Variable``, ``Axis``, | ``fileobj['id']`` | Get the persistent | -| or ``Grid`` | | variable, axis or grid | -| | | object having the string | -| | | identifier. This does | -| | | not read the data for a | -| | | variable. | -| | | | -| | | **Example:** The | -| | | following gets the | -| | | persistent variable | -| | | ``v``, equivalent to | -| | | ``v = f.variables['prc'] | -| | | ``. | -| | | | -| | | :: | -| | | | -| | | f = cdms.open('sampl | -| | | e.nc') | -| | | v = f['prc'] | -| | | | -| | | **Example:** The | -| | | following gets the axis | -| | | named time, equivalent | -| | | to | -| | | ``t = f.axes['time']``. | -| | | | -| | | ``t = f['time']`` | -+--------------------------+--------------------------+--------------------------+ -| ``None`` | ``close()`` | Close the file. | -+--------------------------+--------------------------+--------------------------+ -| ``Axis`` | ``copyAxis(axis, newname | Copy ``axis`` values and | -| | =None)`` | attributes to a new axis | -| | | in the file. The | -| | | returned object is | -| | | persistent: it can be | -| | | used to write axis data | -| | | to or read axis data | -| | | from the file. If an | -| | | axis already exists in | -| | | the file, having the | -| | | same name and coordinate | -| | | values, it is returned. | -| | | It is an error if an | -| | | axis of the same name | -| | | exists, but with | -| | | different coordinate | -| | | values. ``axis`` is the | -| | | axis object to be | -| | | copied. ``newname``, if | -| | | specified, is the string | -| | | identifier of the new | -| | | axis object. If not | -| | | specified, the | -| | | identifier of the input | -| | | axis is used. | -+--------------------------+--------------------------+--------------------------+ -| ``Grid`` | ``copyGrid(grid, newname | Copy grid values and | -| | =None)`` | attributes to a new grid | -| | | in the file. The | -| | | returned grid is | -| | | persistent. If a grid | -| | | already exists in the | -| | | file, having the same | -| | | name and axes, it is | -| | | returned. An error is | -| | | raised if a grid of the | -| | | same name exists, having | -| | | different axes. ``grid`` | -| | | is the grid object to be | -| | | copied. ``newname``, if | -| | | specified is the string | -| | | identifier of the new | -| | | grid object. If | -| | | unspecified, the | -| | | identifier of the input | -| | | grid is used. | -+--------------------------+--------------------------+--------------------------+ -| ``Axis`` | ``createAxis(id, ar, unl | Create a new ``Axis``. | -| | imited=0)`` | This is a persistent | -| | | object which can be used | -| | | to read or write axis | -| | | data to the file. ``id`` | -| | | is an alphanumeric | -| | | string identifier, | -| | | containing no blanks. | -| | | ``ar`` is the | -| | | one-dimensional axis | -| | | array. Set ``unlimited`` | -| | | to ``cdms.Unlimited`` to | -| | | indicate that the axis | -| | | is extensible. | -+--------------------------+--------------------------+--------------------------+ -| ``RectGrid`` | ``createRectGrid(id, lat | Create a ``RectGrid`` in | -| | , lon, order, type="gene | the file. This is not a | -| | ric", mask=None)`` | persistent object: the | -| | | order, type, and mask | -| | | are not written to the | -| | | file. However, the grid | -| | | may be used for | -| | | regridding operations. | -| | | ``lat`` is a latitude | -| | | axis in the file. | -| | | ``lon`` is a longitude | -| | | axis in the file. | -| | | ``order`` is a string | -| | | with value ``"yx"`` (the | -| | | first grid dimension is | -| | | latitude) or ``"xy"`` | -| | | (the first grid | -| | | dimension is longitude). | -| | | ``type`` is one of | -| | | ``'gaussian'``,\ ``'unif | -| | | orm'``,\ ``'equalarea'`` | -| | | , | -| | | or ``'generic'``. If | -| | | specified, ``mask`` is a | -| | | two-dimensional, logical | -| | | Numeric array (all | -| | | values are zero or one) | -| | | with the same shape as | -| | | the grid. | -+--------------------------+--------------------------+--------------------------+ -| ``Variable`` | ``createVariable(String | Create a new Variable. | -| | id, String datatype,List | This is a persistent | -| | axes, fill_value=None)`` | object which can be used | -| | | to read or write | -| | | variable data to the | -| | | file. ``id`` is a String | -| | | name which is unique | -| | | with respect to all | -| | | other objects in the | -| | | file. ``datatype`` is an | -| | | ``MA`` typecode, e.g., | -| | | ``MA.Float``, | -| | | ``MA.Int``. ``axes`` is | -| | | a list of Axis and/or | -| | | Grid objects. | -| | | ``fill_value`` is the | -| | | missing value | -| | | (optional). | -+--------------------------+--------------------------+--------------------------+ -| ``Variable`` | ``createVariableCopy(var | Create a new | -| | , newname=None)`` | ``Variable``, with the | -| | | same name, axes, and | -| | | attributes as the input | -| | | variable. An error is | -| | | raised if a variable of | -| | | the same name exists in | -| | | the file. ``var`` is the | -| | | ``Variable`` to be | -| | | copied. ``newname``, if | -| | | specified is the name of | -| | | the new variable. If | -| | | unspecified, the | -| | | returned variable has | -| | | the same name as | -| | | ``var``. | -| | | | -| | | **Note:** Unlike | -| | | copyAxis, the actual | -| | | data is not copied to | -| | | the new variable. | -+--------------------------+--------------------------+--------------------------+ -| ``CurveGrid`` or | ``readScripGrid(self, wh | Read a curvilinear or | -| ``Generic-Grid`` | ichGrid='destination', c | generic grid from a | -| | heck-Grid=1)`` | SCRIP netCDF file. The | -| | | file can be a SCRIP grid | -| | | file or remapping file. | -| | | If a mapping file, | -| | | ``whichGrid`` chooses | -| | | the grid to read, either | -| | | ``"source"`` or | -| | | ``"destination"``. If | -| | | ``checkGrid`` is ``1`` | -| | | (default), the grid | -| | | cells are checked for | -| | | convexity, and | -| | | 'repaired' if necessary. | -| | | Grid cells may appear to | -| | | be nonconvex if they | -| | | cross a ``0 / 2pi`` | -| | | boundary. The repair | -| | | consists of shifting the | -| | | cell vertices to the | -| | | same side modulo 360 | -| | | degrees. | -+--------------------------+--------------------------+--------------------------+ -| ``None`` | ``sync()`` | Writes any pending | -| | | changes to the file. | -+--------------------------+--------------------------+--------------------------+ -| ``Variable`` | :: | Write a variable or | -| | | array to the file. The | -| | write(var, attribute | return value is the | -| | s=None, axes=None, extbo | associated file | -| | unds=None, id=None, exte | variable. | -| | nd=None, fill_value=None | | -| | , index=None, typecode=N | If the variable does not | -| | one) | exist in the file, it is | -| | | first defined and all | -| | | attributes written, then | -| | | the data is written. By | -| | | default, the time | -| | | dimension of the | -| | | variable is defined as | -| | | the unlimited dimension | -| | | of the file. If the data | -| | | is already defined, then | -| | | data is extended or | -| | | overwritten depending on | -| | | the value of keywords | -| | | ``extend`` and | -| | | ``index``, and the | -| | | unlimited dimension | -| | | values associated with | -| | | ``var``. | -| | | | -| | | ``var`` is a Variable, | -| | | masked array, or Numeric | -| | | array. ``attributes`` is | -| | | the attribute dictionary | -| | | for the variable. The | -| | | default is | -| | | ``var.attributes``. | -| | | ``axes`` is the list of | -| | | file axes comprising the | -| | | domain of the variable. | -| | | The default is to copy | -| | | ``var.getAxisList()``. | -| | | ``extbounds`` is the | -| | | unlimited dimension | -| | | bounds. Defaults to | -| | | ``var.getAxis(0).getBoun | -| | | ds()``. | -| | | ``id`` is the variable | -| | | name in the file. | -| | | Default is ``var.id``. | -| | | ``extend = 1`` causes | -| | | the first dimension to | -| | | be unlimited: | -| | | iteratively writeable. | -| | | The default is ``None``, | -| | | in which case the first | -| | | dimension is extensible | -| | | if it is ``time.Set`` to | -| | | ``0`` to turn off this | -| | | behaviour. | -| | | ``fill_value`` is the | -| | | missing value flag. | -| | | ``index`` is the | -| | | extended dimension index | -| | | to write to. The default | -| | | index is determined by | -| | | lookup relative to the | -| | | existing extended | -| | | dimension. | -| | | | -| | | **Note:** data can also | -| | | be written by setting a | -| | | slice of a file | -| | | variable, and attributes | -| | | can be written by | -| | | setting an attribute of | -| | | a file variable. | -+--------------------------+--------------------------+--------------------------+ - - -Table 2.15 CDMS Datatypes - -+-----------------+-----------------------------------+ -| CDMS Datatype | Definition | -+=================+===================================+ -| ``CdChar`` | character | -+-----------------+-----------------------------------+ -| ``CdDouble`` | double-precision floating-point | -+-----------------+-----------------------------------+ -| ``CdFloat`` | floating-point | -+-----------------+-----------------------------------+ -| ``CdInt`` | integer | -+-----------------+-----------------------------------+ -| ``CdLong`` | long integer | -+-----------------+-----------------------------------+ -| ``CdShort`` | short integer | -+-----------------+-----------------------------------+ - - -2.7 Database -^^^^^^^^^^^^ +Cdms-Files. See “cu Module”. + + +Table CdmsFile Internal Attributes +---------------------------------- + +.. csv-table:: + :header: "Type", "Name", "Definition" + :widths: 20, 20, 80 + + "``Dictionary``", "``attributes``", "Global, external file attributes" + "``Dictionary``", "``axes``", "Axis objects contained in the file." + "``Dictionary``", "``grids``", "Grids contained in the file." + "``String``", "``id``", "File pathname." + "``Dictionary``", "``variables``", "Variables contained in the file." + +Table CdmsFile Constructors +--------------------------- + +.. csv-table:: + :header: "Constructor", "Description" + :widths: 50, 80 + :align: left + + "Constructor", "Description" + "``fileobj = cdms.open(path, mode)``", "Open the file specified by path returning a CdmsFile object. ``path`` is the file pathname, a string. ``mode`` is the open mode indicator, as listed in See `Open Modes <#table-open-modes>`_." + "``fileobj = cdms.createDataset(path)``", "Create the file specified by path, a string." + +Table CdmsFile Methods +---------------------- + +.. csv-table:: + :header: "Type", "Method", "Definition" + :widths: 10, 30, 80 + :align: left + + + "``Transient-Variable``", "``fileobj(varname, selector)``", "Calling a ``CdmsFile``" + ,, "object as a function reads the region of data specified by the ``selector``. The result is a transient variable, unless ``raw = 1`` is specified. See 'Selectors'." + ,, " **Example:** The following reads data for variable 'prc', year 1980:" + ,, " * >>> f = cdms.open('test.nc')" + ,, " * >>> x = f('prc', time=('1980-1','1981-1'))" + "``Variable``, ``Axis``, or ``Grid``", "``fileobj['id']``", "Get the persistent variable, axis or grid object having the string identifier. This does not read the data for a variable." + ,, " **Example:** The following gets the persistent variable" + ,, " * ``v``, equivalent to" + ,, " * ``v = f.variables['prc']``." + ,, " * f = cdms.open('sample.nc')" + ,, " * v = f['prc']" + ,, " **Example:** The following gets the axis named time, equivalent to" + ,, " * ``t = f.axes['time']``." + ,, " * ``t = f['time']``" + "``None``", "``close()``", "Close the file." + "``Axis``", "``copyAxis(axis, newname=None)``", "Copy ``axis`` values and attributes to a new axis in the file. The returned object is persistent: it can be used to write axis data to or read axis data from the file. If an axis already exists in the file, having the same name and coordinate values, it is returned. It is an error if an axis of the same name exists, but with different coordinate values. ``axis`` is the axis object to be copied. ``newname``, if specified, is the string identifier of the new axis object. If not specified, the identifier of the input axis is used." + "``Grid``", "``copyGrid(grid, newname=None)``", "Copy grid values and attributes to a new grid in the file. The returned grid is persistent. If a grid already exists in the file, having the same name and axes, it is returned. An error is raised if a grid of the same name exists, having different axes. ``grid`` is the grid object to be copied. ``newname``, if specified is the string identifier of the new grid object. If unspecified, the identifier of the input grid is used." + "``Axis``", "``createAxis(id,ar, unlimited=0)``", "Create a new ``Axis``. This is a persistent object which can be used to read or write axis data to the file. ``id`` is an alphanumeric string identifier, containing no blanks. ``ar`` is the one-dimensional axis array. Set ``unlimited`` to ``cdms.Unlimited`` to indicate that the axis is extensible." + "``RectGrid``", "``createRectGrid(id,lat, lon,order,type='generic', mask=None)``", "Create a ``RectGrid`` in the file. This is not a persistent object: the order, type, and mask are not written to the file. However, the grid may be used for regridding operations. ``lat`` is a latitude axis in the file. ``lon`` is a longitude axis in the file. ``order`` is a string with value ``'yx'`` (the latitude) or ``'xy'`` (the first grid dimension is longitude). ``type`` is one of ``'gaussian'``,\ ``'unif orm'``,\ ``'equalarea'`` , or ``'generic'``. If specified, ``mask`` is a two-dimensional, logical Numpy array (all values are zero or one) with the same shape as the grid." + "``Variable``", "``createVariable(Stringid,String datatype,Listaxes,fill_value=None)``", "Create a new Variable. This is a persistent object which can be used to read or write variable data to the file. ``id`` is a String name which is unique with respect to all other objects in the file. ``datatype`` is an ``MV2`` typecode, e.g., ``MV2.Float``, ``MV2.Int``. ``axes`` is a list of Axis and/or Grid objects. ``fill_value`` is the missing value (optional)." + "``Variable``", "``createVariableCopy(var, newname=None)``", "Create a new ``Variable``, with the same name, axes, and attributes as the input variable. An error is raised if a variable of the same name exists in the file. ``var`` is the ``Variable`` to be copied. ``newname``, if specified is the name of the new variable. If unspecified, the returned variable has the same name as ``var``." + ,," **Note:** Unlike copyAxis, the actual data is not copied to the new variable." + "``CurveGrid`` or ``Generic-Grid``", "``readScripGrid(self,whichGrid='destination',check-Grid=1)``", "Read a curvilinear or generic grid from a SCRIP netCDF file. The file can be a SCRIP grid file or remapping file. If a mapping file, ``whichGrid`` chooses the grid to read, either ``'source'`` or ``'destination'``. If ``checkGrid`` is ``1`` (default), the grid cells are checked for convexity, and 'repaired' if necessary. Grid cells may appear to be nonconvex if they cross a ``0 / 2pi`` boundary. The repair consists of shifting the cell vertices to the same side modulo 360 degrees." + "``None``", "``sync()``", "Writes any pending changes to the file." + "``Variable``", "``write(var,attributes=None,axes=None, extbounds=None,id=None,extend=None, fill_value=None, index=None, typecode=None)``","Write a variable or array to the file. The return value is the associated file variable." + ,,"If the variable does not exist in the file, it is first defined and all attributes written, then the data is written. By default, the time dimension of the variable is defined as the unlimited dimension of the file. If the data is already defined, then data is extended or overwritten depending on the value of keywords ``extend`` and ``index``, and the unlimited dimension values associated with ``var``." + ,,"* ``var`` is a Variable, masked array, or Numpy array." + ,,"* ``attributes`` is the attribute dictionary for the variable. The default is ``var.attributes``." + ,,"* ``axes`` is the list of file axes comprising the domain of the variable. The default is to copy ``var.getAxisList()``." + ,,"* ``extbounds`` is the unlimited dimension bounds. Defaults to ``var.getAxis(0).getBounds()``." + ,,"* ``id`` is the variable name in the file. Default is ``var.id``." + ,,"* ``extend = 1`` causes the first dimension to be unlimited: iteratively writeable." + ,," * The default is ``None``, in which case the first dimension is extensible if it is ``time.Set`` to ``0`` to turn off this behaviour." + ,,"* ``fill_value`` is the missing value flag." + ,,"* ``index`` is the extended dimension index to write to. The default index is determined by lookup relative to the existing extended dimension." + ,," **Note:** data can also be written by setting a slice of a file variable, and attributes can be written by setting an attribute of a file variable." + +Table CDMS Datatypes +-------------------- + +.. csv-table:: + :header: "CDMS Datatype", "Definition" + :widths: 20, 30 + + "``CdChar``", "character" + "``CdDouble``", "double-precision floating-point" + "``CdFloat``", "floating-point" + "``CdInt``", "integer" + "``CdLong``", "long integer" + "``CdShort``", "short integer" + + +Database +^^^^^^^^ A Database is a collection of datasets and other CDMS objects. It consists of a hierarchical collection of objects, with the database being at the root, or top of the hierarchy. A database is used to: @@ -1114,13 +580,14 @@ The figure below illustrates several important points: Figure 1 -2.7.1 Overview +Overview +-------------- To access a database: -#. Open a connection. The connect method opens a database connection. - connect takes a database URI and returns a database object: - ``db = cdms.connect("ldap://dbhost.llnl.gov/database=CDMS,ou=PCMDI,o=LLNL,c=US")`` +#. Open a connection. The connect method opens a database connection. Connect takes a database URI and returns a database object: + ``db=cdms.connect("ldap://dbhost.llnl.gov/database=CDMS,ou=PCMDI,o=LLNL,c=US")`` + #. Search the database, locating one or more datasets, variables, and/or other objects. @@ -1160,158 +627,79 @@ To access a database: ``db.close()`` - -Table 2.16 Database Internal Attributes - -+------------------+------------------+----------------------------------------+ -| Type | Name | Summary | -+==================+==================+========================================+ -| ``Dictionary`` | ``attributes`` | Database attribute dictionary | -+------------------+------------------+----------------------------------------+ -| ``LDAP`` | ``db`` | (LDAP only) LDAP database object | -+------------------+------------------+----------------------------------------+ -| ``String`` | ``netloc`` | Hostname, for server-based databases | -+------------------+------------------+----------------------------------------+ -| ``String`` | ``path`` | path name | -+------------------+------------------+----------------------------------------+ -| ``String`` | ``uri`` | Uniform Resource Identifier | -+------------------+------------------+----------------------------------------+ - - -Table 2.17 Database Constructors - -+---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Constructor | Description | -+=========================================================+==============================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+ -| ``db = cdms.connect(uri=None, user="", password="")`` | Connect to the database. ``uri`` is the Universal Resource Indentifier of the database. The form of the URI depends on the implementation of the database. For a Lightweight Directory Access Protocol (LDAP) database, the form is: ``ldap://host[:port]/dbname``. For example, if the database is located on host dbhost.llnl.gov, and is named ``'database=CDMS,ou=PCMDI,o=LLNL,c=US'``, the URI is: ``ldap://dbhost.llnl.gov/database=CDMS,ou=PCMDI,o=LLNL,c=US``. If unspecified, the URI defaults to the value of environment variable CDMSROOT. ``user`` is the user ID. If unspecified, an anonymous connection is made. ``password`` is the user password. A password is not required for an anonymous connection | -+---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - - -Table 2.18 Database Methods - -+--------------------------+--------------------------+--------------------------+ -| Type | Method | Definition | -+==========================+==========================+==========================+ -| None | ``close()`` | Close a database | -| | | connection. | -+--------------------------+--------------------------+--------------------------+ -| List | ``listDatasets()`` | Return a list of the | -| | | dataset IDs in this | -| | | database. A dataset ID | -| | | can be passed to the | -| | | ``open`` command. | -+--------------------------+--------------------------+--------------------------+ -| Dataset | ``open(dsetid, mode='r') | Open a dataset. | -| | `` | | -| | | ``dsetid`` is the string | -| | | dataset identifier | -| | | | -| | | ``mode`` is the open | -| | | mode, 'r' - read-only, | -| | | 'r+' - read-write, 'w' - | -| | | create. | -| | | | -| | | ``openDataset`` is a | -| | | synonym for ``open``. | -+--------------------------+--------------------------+--------------------------+ -| SearchResult | :: | Search a CDMS database. | -| | | | -| | searchFilter(filter= | ``filter`` is the string | -| | None, tag=None, relbase= | search filter. Simple | -| | None, scope=Subtree, att | filters have the form | -| | names=None, timeout=None | "tag = value". Simple | -| | ) | filters can be combined | -| | | using logical operators | -| | | '&', '\|', '!' in prefix | -| | | notation. | -| | | | -| | | **Example:** | -| | | | -| | | The filter | -| | | ``'(&(objec)(id=cli))'`` | -| | | finds all variables | -| | | named "cli". | -| | | | -| | | A formal definition of | -| | | search filters is | -| | | provided in the | -| | | following section. | -| | | | -| | | ``tag`` restricts the | -| | | search to objects with | -| | | that tag ("dataset" \| | -| | | "variable" \| "database" | -| | | \| "axis" \| "grid"). | -| | | | -| | | ``relbase`` is the | -| | | relative name of the | -| | | base object of the | -| | | search. The search is | -| | | restricted to the base | -| | | object and all objects | -| | | below it in the | -| | | hierarchy. | -| | | | -| | | **Example:** | -| | | | -| | | To search only dataset | -| | | 'ncep\_reanalysis\_mo', | -| | | specify: | -| | | | -| | | ``relbase="dataset=ncep_ | -| | | reanalysis_mo" `` | -| | | | -| | | To search only variable | -| | | 'ua' in | -| | | 'ncep\_reanalysis\_mo', | -| | | use: | -| | | | -| | | ``relbase="variable=ua,d | -| | | ataset=ncep_reanalysis_m | -| | | o"`` | -| | | | -| | | If no base is specified, | -| | | the entire database is | -| | | searched. See the | -| | | ``scope`` argument also. | -| | | | -| | | ``scope`` is the search | -| | | scope (**Subtree** \| | -| | | **Onelevel** \| | -| | | **Base**). | -| | | | -| | | - **Subtree** searches | -| | | the base object and | -| | | its descendants. | -| | | - **Onelevel** searches | -| | | the base object and | -| | | its immediate | -| | | descendants. | -| | | - **Base**\ searches | -| | | the base object | -| | | alone. | -| | | | -| | | The default is | -| | | **Subtree**. | -| | | | -| | | ``attnames``: list of | -| | | attribute names. | -| | | Restricts the attributes | -| | | returned. If ``None``, | -| | | all attributes are | -| | | returned. Attributes | -| | | 'id' and 'objectclass' | -| | | are always included in | -| | | the list. | -| | | | -| | | ``timeout``: integer | -| | | number of seconds before | -| | | timeout. The default is | -| | | no timeout. | -+--------------------------+--------------------------+--------------------------+ - - -2.7.2 Searching a database +Table Database Internal Attributes +---------------------------------- + + +.. csv-table:: + :header: "Type", "Name", "Summary" + :widths: 20, 20, 80 + + "``Dictionary``", "``attributes``", "Database attribute dictionary" + "``LDAP``", "``db``", "(LDAP only) LDAP database object" + "``String``", "``netloc``", "Hostname, for server-based databases" + "``String``", "``path``", "path name" + "``String``", "``uri``", "Uniform Resource Identifier" + + +Table Database Constructors +--------------------------- + +.. csv-table:: + :header: "Constructor", "Description" + :widths: 30, 80 + :align: left + + + "``db = cdms.connect(uri=None, user='', password='')``", "Connect to the database. ``uri`` is the Universal Resource Indentifier of the database. The form of the URI depends on the implementation of the database." + ,"For a Lightweight Directory Access Protocol (LDAP) database, the form is: ``ldap://host[:port]/dbname``." + ,"For example, if the database is located on host dbhost.llnl.gov, and is named ``'database=CDMS,ou=PCMDI,o=LLNL,c=US'``, the URI is: ``ldap://dbhost.llnl.gov/database=CDMS,ou=PCMDI,o=LLNL,c=US``. If unspecified, the URI defaults to the value of environment variable CDMSROOT. ``user`` is the user ID. If unspecified, an anonymous connection is made. ``password`` is the user password. A password is not required for an anonymous connection" + +Table Database Methods +---------------------- + +.. csv-table:: + :header: "Type", "Method", "Definition" + :widths: 20, 30, 80 + + "None", "``close()``", "Close a database" + "List", "``listDatasets()``", "Return a list of the dataset IDs in this database. A dataset ID can be passed to the ``open`` command." + "Dataset", "``open(dsetid, mode='r')``", "Open a dataset." + , "* ``dsetid``","is the string dataset identifier" + , "* ``mode``","is the open mode, 'r' - read-only, 'r+' - read-write, 'w' - create." + , "* ``openDataset``", "is a synonym for ``open``." + "SearchResult","``searchFilter(filter=None, tag=None, relbase=None, scope=Subtree, attnames=None, timeout=None)``","Search a CDMS database." + ,, "``filter`` is the string search filter. Simple filters have the form 'tag = value'. Simple filters can be combined using logical operators '&', '\|', '!' in prefix notation." + ,, + ,," **Example:**" + ,," * The filter ``'(&(objec)(id=cli))'`` finds all variables named 'cli'." + ,," - A formal definition of search filters is provided in the following section." + ,," - ``tag`` restricts the search to objects with that tag ('dataset' | 'variable' | 'database' | 'axis' | 'grid')." + ,," - ``relbase`` is the relative name of the base object of the search. The search is restricted to the base object and all objects below it in the hierarchy." + ,, + ,," **Example:**" + ,," * To search only dataset 'ncep_reanalysis_mo', specify:" + ,," - ``relbase='dataset=ncep_reanalysis_mo'``" + ,," * To search only variable 'ua' in 'ncep_reanalysis_mo', use:" + ,," - ``relbase='variable=ua, dataset=ncep_reanalysis_mo'``" + ,, + ,,"If no base is specified, the entire database is searched. See the ``scope`` argument also." + ,,"``scope`` is the search scope (**Subtree** | **Onelevel** | **Base**)." + ,," * **Subtree** searches the base object and its descendants." + ,," * **Onelevel** searches the base object and its immediate descendants." + ,," * **Base**\ searches the base object alone." + ,," * The default is **Subtree**." + ,,"``attnames``: list of attribute names. Restricts the attributes returned. If ``None``, all attributes are returned. Attributes 'id' and 'objectclass' are always included in the list." + ,,"``timeout``: integer number of seconds before timeout. The default is no timeout." + + +------------ + +.. highlight:: python + :linenothreshold: 0 + +Searching a Database +-------------------------- The ``searchFilter`` method is used to search a database. The result is called a search result, and consists of a sequence of result entries. @@ -1322,44 +710,23 @@ to those objects having an attribute which matches the filter. Simple filters have the form (tag = value), where value can contain wildcards. For example: -.. raw:: html - -
- -:: - - (id = ncep*) - (project = AMIP2) - -.. raw:: html - -
+:: -+--------------------------------------------------------------------+------------------------+ -| Simple filters can be combined with the logical operators ‘&’, ‘ | ’, ‘!’. For example, | -+--------------------------------------------------------------------+------------------------+ + (id = ncep*) + (project = AMIP2) -.. raw:: html - -
+**Note** Simple filters can be combined with the logical operators '&', '|', '!'. For example, :: - (&(id = bmrc*)(project = AMIP2)) - -.. raw:: html + (&(id = bmrc*)(project = AMIP2)) -
matches all objects with id starting with bmrc, and a project attribute with value ‘AMIP2’. Formally, search filters are strings defined as follows: -.. raw:: html - -
- :: filter ::= "(" filtercomp ")" @@ -1380,12 +747,9 @@ Formally, search filters are strings defined as follows: tag ::= string attribute name value ::= string attribute value, may include '*' as a wild card -.. raw:: html - -
Attribute names are defined in the chapter on “Climate Data Markup -Language (CDML)” on page 149. In addition, some special attributes are +Language (CDML)”. In addition, some special attributes are defined for convenience: - ``category`` is either “experimental” or “observed” @@ -1410,28 +774,16 @@ several ways: - The search can be restricted to the result of a previous search. - A search result is accessed sequentially within a for loop: -.. raw:: html - -
- :: result = db.searchFilter('(&(category=obs*)(id=ncep*))') for entry in result: print entry.name -.. raw:: html - -
- Search results can be narrowed using ``searchPredicate``. In the following example, the result of one search is itself searched for all variables defined on a 94x192 grid: -.. raw:: html - -
- :: >>> result = db.searchFilter('parentid=ncep*',tag="variable") @@ -1453,22 +805,19 @@ variables defined on a 94x192 grid: o=LLNL, c=US -.. raw:: html -
+Table SearchResult Methods +-------------------------- -Table 2.19 SearchResult Methods +.. csv-table:: + :header: "Type", "Method", "Definition" + :widths: 20, 30, 80 -+----------------+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Type | Method | Definition | -+================+============================================+==================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+ -| ResultEntry | ``[i]`` | Return the i-th search result. Results can also be returned in a for loop: ``for entry in db.searchResult(tag="dataset"):`` | -+----------------+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Integer | ``len()`` | Number of entries in the result. | -+----------------+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| SearchResult | ``searchPredicate(predicate, tag=None)`` | Refine a search result, with a predicate search. ``predicate`` is a function which takes a single CDMS object and returns true (1) if the object satisfies the predicate, 0 if not. ``tag`` restricts the search to objects of the class denoted by the tag. **Note**: In the current implementation, ``searchPredicate``\ is much less efficient than ``searchFilter``. For best performance, use ``searchFilter`` to narrow the scope of the search, then use ``searchPredicate`` for more general searches. | -+----------------+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + "ResultEntry", "``[i]``", "Return the i-th search result. Results can also be returned in a for loop: ``for entry in db.searchResult(tag='dataset'):``" + "Integer", "``len()``", "Number of entries in the result." + "SearchResult", "``searchPredicate(predicate, tag=None)``", "Refine a search result, with a predicate search. ``predicate`` is a function which takes a single CDMS object and returns true (1) if the object satisfies the predicate, 0 if not. ``tag`` restricts the search to objects of the class denoted by the tag." + ,,"**Note**: In the current implementation, ``searchPredicate`` is much less efficient than ``searchFilter``. For best performance, use ``searchFilter`` to narrow the scope of the search, then use ``searchPredicate`` for more general searches." A search result is a sequence of result entries. Each entry has a string name, the name of the object in the database hierarchy, and an attribute @@ -1479,27 +828,30 @@ information defined for the associated CDMS object, which is retrieved with the ``getObject`` method. -Table 2.20 ResultEntry Attributes +Table ResultEntry Attributes +---------------------------- + +.. csv-table:: + :header: "Type", "Method", "Definition" + :widths: 20, 30, 80 + + "String", "``name``", "The name of this entry in the database." + "Dictionary", "``attributes``", "The attributes returned from the search. ``attributes[key]`` is a list of all string values associated with the key" -+--------------+------------------+-----------------------------------------------------------------------------------------------------------------------+ -| Type | Name | Description | -+==============+==================+=======================================================================================================================+ -| String | ``name`` | The name of this entry in the database. | -+--------------+------------------+-----------------------------------------------------------------------------------------------------------------------+ -| Dictionary | ``attributes`` | The attributes returned from the search. ``attributes[key]`` is a list of all string values associated with the key | -+--------------+------------------+-----------------------------------------------------------------------------------------------------------------------+ +Table ResultEntry Methods +------------------------- -Table 2.21 ResultEntry Methods +.. csv-table:: + :header: "Type", "Method", "Definition" + :widths: 20, 30, 80 -+---------------+-------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Type | Method | Definition | -+===============+===================+======================================================================================================================================================================================================================================================================================+ -| ``CdmsObj`` | ``getObject()`` | Return the CDMS object associated with this entry. **Note:** For many search applications it is unnecessary to access the associated CDMS object. For best performance this function should be used only when necessary, for example, to retrieve data associated with a variable. | -+---------------+-------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + "``CdmsObj``", "``getObject()``", "Return the CDMS object associated with this entry." + ,, "**Note:** For many search applications it is unnecessary to access the associated CDMS object. For best performance this function should be used only when necessary, for example, to retrieve data associated with a variable." -2.7.3 Accessing data +Accessing data +-------------------- To access data via CDMS: @@ -1508,11 +860,7 @@ To access data via CDMS: #. Reference the portion of the variable to be read. In the next example, a portion of variable ‘ua’ is read from dataset -‘ncep\_reanalysis\_mo’: - -.. raw:: html - -
+‘ncep_reanalysis_mo’: :: @@ -1520,83 +868,43 @@ In the next example, a portion of variable ‘ua’ is read from dataset ua = dset.variables['ua'] data = ua[0,0] -.. raw:: html - -
- - -2.7.4 Examples of database searches -In the following examples, db is the database opened with +Examples of Database Searches +----------------------------------- -.. raw:: html - -
+In the following examples, db is the database opened with: :: db = cdms.connect() -.. raw:: html - -
- This defaults to the database defined in environment variable ``CDMSROOT``. **Example:** List all variables in dataset ‘ncep\_reanalysis\_mo’: -.. raw:: html - -
- :: - for entry in db.searchFilter(filter = "parentid=ncep_reanalysis_mo", - tag = "variable"): + for entry in db.searchFilter(filter = "parentid=ncep_reanalysis_mo", tag = "variable"): print entry.name -.. raw:: html - -
**Example:** Find all axes with bounds defined: -.. raw:: html - -
- :: for entry in db.searchFilter(filter="bounds=*",tag="axis"): print entry.name -.. raw:: html - -
**Example:** Locate all GDT datasets: -.. raw:: html - -
- :: - for entry in - db.searchFilter(filter="Conventions=GDT*",tag="dataset"): + for entry in db.searchFilter(filter="Conventions=GDT*",tag="dataset"): print entry.name -.. raw:: html - -
- -**Example:** Find all variables with missing time values, in observed -datasets: - -.. raw:: html - -
+**Example:** Find all variables with missing time values, in observed datasets: :: @@ -1608,63 +916,30 @@ datasets: for entry in result.searchPredicate(missingTime): print entry.name -.. raw:: html - -
- **Example:** Find all CMIP2 datasets having a variable with id “hfss”: -.. raw:: html - -
- :: for entry in db.searchFilter(filter = "(&(project=CMIP2)(id=hfss))", tag = "variable"): print entry.getObject().parent.id -.. raw:: html - -
- **Example:** Find all observed variables on 73x144 grids: -.. raw:: html - -
- :: result = db.searchFilter(category='obs*') for entry in result.searchPredicate(lambda x: x.getGrid().shape==(73,144),tag="variable"): print entry.name -.. raw:: html - -
- **Example:** Find all observed variables with more than 1000 timepoints: -.. raw:: html - -
- :: result = db.searchFilter(category='obs*') for entry in result.searchPredicate(lambda x: len(x.getTime())>1000, tag = "variable"): print entry.name, len(entry.getObject().getTime()) -.. raw:: html - -
- -**Example:** Find the total number of each type of object in the -database - -.. raw:: html - -
+**Example:** Find the total number of each type of object in the database: :: @@ -1673,269 +948,129 @@ database print len(db.searchFilter(tag="variable")),"variables" print len(db.searchFilter(tag="axis")),"axes" -.. raw:: html - -
- -2.8 Dataset -^^^^^^^^^^^ +Dataset +^^^^^^^ A Dataset is a virtual file. It consists of a metafile, in CDML/XML representation, and one or more data files. As of CDMS V3, the legacy cuDataset interface is supported by Datasets. -See “cu Module” on page 180. - - -Table 2.22 Dataset Internal Attributes - -+--------------+------------------+----------------------------------------------------------------------------------------------------------+ -| Type | Name | Description | -+==============+==================+==========================================================================================================+ -| Dictionary | ``attributes`` | Dataset external attributes. | -+--------------+------------------+----------------------------------------------------------------------------------------------------------+ -| Dictionary | ``axes`` | Axes contained in the dataset. | -+--------------+------------------+----------------------------------------------------------------------------------------------------------+ -| String | ``datapath`` | Path of data files, relative to the parent database. If no parent, the datapath is absolute. | -+--------------+------------------+----------------------------------------------------------------------------------------------------------+ -| Dictionary | ``grids`` | Grids contained in the dataset. | -+--------------+------------------+----------------------------------------------------------------------------------------------------------+ -| String | ``mode`` | Open mode. | -+--------------+------------------+----------------------------------------------------------------------------------------------------------+ -| Database | ``parent`` | Database which contains this dataset. If the dataset is not part of a database, the value is ``None``. | -+--------------+------------------+----------------------------------------------------------------------------------------------------------+ -| String | ``uri`` | Uniform Resource Identifier of this dataset. | -+--------------+------------------+----------------------------------------------------------------------------------------------------------+ -| Dictionary | ``variables`` | Variables contained in the dataset. | -+--------------+------------------+----------------------------------------------------------------------------------------------------------+ -| Dictionary | ``xlinks`` | External links contained in the dataset. | -+--------------+------------------+----------------------------------------------------------------------------------------------------------+ - - -Table 2.23 Dataset Constructors - -+-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Constructor | Description | -+===========================================================+===================================================================================================================================================================================================================+ -| ``datasetobj = cdms.open(String uri, String mode='r')`` | Open the dataset specified by the Universal Resource Indicator, a CDML file. Returns a Dataset object. mode is one of the indicators listed in Table 2.24 on page 70. ``openDataset`` is a synonym for ``open`` | -+-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - - -Table 2.24 Open Modes - -+--------+-----------------------------------------------------------------------+ -| Mode | Definition | -+========+=======================================================================+ -| ‘r’ | read-only | -+--------+-----------------------------------------------------------------------+ -| ‘r+’ | read-write | -+--------+-----------------------------------------------------------------------+ -| ‘a’ | read-write. Open the file if it exists, otherwise create a new file | -+--------+-----------------------------------------------------------------------+ -| ‘w’ | Create a new file, read-write | -+--------+-----------------------------------------------------------------------+ - - -Table 2.25 Dataset Methods - -+--------------------------+--------------------------+--------------------------+ -| Type | Method | Definition | -+==========================+==========================+==========================+ -| Transient-Variable | ``datasetobj(varname, se | Calling a Dataset object | -| | lector)`` | as a function reads the | -| | | region of data defined | -| | | by the selector. The | -| | | result is a transient | -| | | variable, unless | -| | | ``raw = 1`` is | -| | | specified. See | -| | | "Selectors" on page 103. | -| | | **Example:** The | -| | | following reads data for | -| | | variable 'prc', year | -| | | 1980: | -| | | | -| | | :: | -| | | | -| | | f = cdms.open('test. | -| | | xml') | -| | | x = f('prc', time=(' | -| | | 1980-1','1981-1')) | -+--------------------------+--------------------------+--------------------------+ -| Variable, Axis, or Grid | ``datasetobj['id']`` | The square bracket | -| | | operator applied to a | -| | | dataset gets the | -| | | persistent variable, | -| | | axis or grid object | -| | | having the string | -| | | identifier. This does | -| | | not read the data for a | -| | | variable. Returns | -| | | ``None`` if not found. | -| | | | -| | | **Example:** | -| | | | -| | | :: | -| | | | -| | | f = cdms.open('sampl | -| | | e.xml') | -| | | v = f['prc'] | -| | | | -| | | gets the persistent | -| | | variable v, equivalent | -| | | to | -| | | ``v = f.variab | -| | | les['prc']``. | -| | | | -| | | **Example:** | -| | | | -| | | | ``t = f['time']`` | -| | | | gets the axis named | -| | | 'time', equivalent to | -| | | ``t = f.axes['time']`` | -+--------------------------+--------------------------+--------------------------+ -| ``None`` | ``close()`` | Close the dataset. | -+--------------------------+--------------------------+--------------------------+ -| ``RectGrid`` | ``createRectGrid(id, lat | Create a RectGrid in the | -| | , lon, order, type="gene | dataset. This is not a | -| | ric", mask=Non | persistent object: the | -| | e)`` | order, type, and mask | -| | | are not written to the | -| | | dataset. However, the | -| | | grid may be used for | -| | | regridding operations. | -| | | | -| | | ``lat`` is a latitude | -| | | axis in the dataset. | -| | | | -| | | ``lon`` is a longitude | -| | | axis in the dataset. | -| | | | -| | | ``order`` is a string | -| | | with value "yx" (the | -| | | first grid dimension is | -| | | latitude) or "xy" (the | -| | | first grid dimension is | -| | | longitude). | -| | | | -| | | ``type`` is one of | -| | | 'gaussian','uniform','eq | -| | | ualarea',or | -| | | 'generic' | -| | | | -| | | If specified, ``mask`` | -| | | is a two-dimensional, | -| | | logical Numeric array | -| | | (all values are zero or | -| | | one) with the same shape | -| | | as the grid. | -+--------------------------+--------------------------+--------------------------+ -| Axis | ``getAxis(id)`` | Get an axis object from | -| | | the file or dataset. | -| | | | -| | | ``id`` is the string | -| | | axis identifier. | -+--------------------------+--------------------------+--------------------------+ -| Grid | ``getGrid(id)`` | Get a grid object from a | -| | | file or dataset. | -| | | | -| | | ``id`` is the string | -| | | grid identifier. | -+--------------------------+--------------------------+--------------------------+ -| List | ``getPaths()`` | Get a sorted list of | -| | | pathnames of datafiles | -| | | which comprise the | -| | | dataset. This does not | -| | | include the XML metafile | -| | | path, which is stored in | -| | | the .uri attribute. | -+--------------------------+--------------------------+--------------------------+ -| Variable | ``getVariable(id)`` | Get a variable object | -| | | from a file or dataset. | -| | | | -| | | ``id`` is the string | -| | | variable identifier. | -+--------------------------+--------------------------+--------------------------+ -| CurveGrid or GenericGrid | ``readScripGrid(self, wh | Read a curvilinear or | -| | ichGrid='destination', c | generic grid from a | -| | heck-or Generic-Grid=1)` | SCRIP dataset. The | -| | ` | dataset can be a SCRIP | -| | | grid file or remapping | -| | | file. | -| | | | -| | | If a mapping file, | -| | | ``whichGrid`` chooses | -| | | the grid to read, either | -| | | ``"source"`` or | -| | | ``"destination"``. | -| | | | -| | | If ``checkGrid`` is 1 | -| | | (default), the grid | -| | | cells are checked for | -| | | convexity, and | -| | | 'repaired' if necessary. | -| | | Grid cells may appear to | -| | | be nonconvex if they | -| | | cross a ``0 / 2pi`` | -| | | boundary. The repair | -| | | consists of shifting the | -| | | cell vertices to the | -| | | same side modulo 360 | -| | | degrees. | -+--------------------------+--------------------------+--------------------------+ -| None | ``sync()`` | Write any pending | -| | | changes to the dataset. | -+--------------------------+--------------------------+--------------------------+ - - -2.9 MV module -^^^^^^^^^^^^^ +See “cu Module". + + +Table Dataset Internal Attributes +--------------------------------- + +.. csv-table:: + :header: "Type", "Name", "Description" + :widths: 20, 30, 80 + + "Dictionary", "``attributes``", "Dataset external attributes." + "Dictionary", "``axes``", "Axes contained in the dataset." + "String", "``datapath``", "Path of data files, relative to the parent database. If no parent, the datapath is absolute." + "Dictionary", "``grids``", "Grids contained in the dataset." + "String", "``mode``", "Open mode." + "Database", "``parent``", "Database which contains this dataset. If the dataset is not part of a database, the value is ``None``." + "String", "``uri``", "Uniform Resource Identifier of this dataset." + "Dictionary", "``variables``", "Variables contained in the dataset." + "Dictionary", "``xlinks``", "External links contained in the dataset." + +Table Dataset Constructors +-------------------------- + +.. csv-table:: + :header: "Constructor", "Description" + :widths: 50, 80 + :align: left + + "``datasetobj = cdms.open(String uri, String mode='r')``", "Open the dataset specified by the Universal Resource Indicator, a CDML file. Returns a Dataset object. mode is one of the indicators listed in `Open Modes <#table-open-modes>`__ . ``openDataset`` is a synonym for ``open``" + + +Table Open Modes +---------------- + +.. csv-table:: + :header: "Mode", "Definition" + :widths: 50, 70 + :align: left + + "‘r’", "read-only" + "‘r+’", "read-write" + "‘a’", "read-write. Open the file if it exists, otherwise create a new file" + "‘w’", "Create a new file, read-write" + + +Table Dataset Methods +--------------------- + +.. csv-table:: + :header: "Type", "Definition", "Description" + :widths: 30, 30, 80 + + "Transient-Variable", "``datasetobj(varname, selector)``", "Calling a Dataset object as a function reads the region of data defined by the selector. The result is a transient variable, unless ``raw = 1`` is specified. See 'Selectors'." + ,, "**Example:** The following reads data for variable 'prc', year 1980:" + ,, " * f = cdms.open('test. xml')" + ,, " * x = f('prc', time=('1980-1','1981-1'))" + "Variable, Axis, or Grid", "``datasetobj['id']``", "The square bracket operator applied to a dataset gets the persistent variable, axis or grid object having the string identifier. This does not read the data for a variable. Returns ``None`` if not found." + ,, "**Example:**" + ,, " * f = cdms.open('sampl e.xml')" + ,, " * v = f['prc']" + ,, " * gets the persistent variable v, equivalent to ``v =f.variab les['prc']``." + ,, "**Example:**" + ,, "``t = f['time']`` gets the axis named 'time', equivalent to ``t = f.axes['time']``" + "``None``", "``close()``", "Close the dataset." + "``RectGrid``", "``createRectGrid(id, lat, lon,order, type='generic', mask=None)``", "Create a RectGrid in the dataset. This is not a persistent object: the order, type, and mask are not written to the dataset. However, the grid may be used for regridding operations." + ,,"``lat`` is a latitude axis in the dataset." + ,,"``lon`` is a longitude axis in the dataset." + ,,"``order`` is a string with value 'yx' (the first grid dimension is latitude) or 'xy' (the first grid dimension is longitude)." + ,,"``type`` is one of 'gaussian','uniform','eq ualarea',or 'generic'" + ,,"If specified, ``mask`` is a two-dimensional, logical Numpy array (all values are zero or one) with the same shape as the grid." + "Axis", "``getAxis(id)``", "Get an axis object from the file or dataset." + ,,"``id`` is the string axis identifier." + "Grid", "``getGrid(id)``", "Get a grid object from a file or dataset." + ,,"``id`` is the string grid identifier." + "List", "``getPaths()``", "Get a sorted list of pathnames of datafiles which comprise the dataset. This does not include the XML metafile path, which is stored in the .uri attribute." + "Variable", "``getVariable(id)``", "Get a variable object from a file or dataset." + ,,"``id`` is the string variable identifier." + "CurveGrid or GenericGrid", "``readScripGrid(self, whichGrid='destination', check-orGeneric-Grid=1)``", "Read a curvilinear orgeneric grid from a SCRIP dataset. The dataset can be a SCRIP grid file or remappingfile." + ,, "If a mapping file, ``whichGrid`` chooses the grid to read, either ``'source'`` or ``'destination'``." + ,, " If ``checkGrid`` is 1 (default), the grid cells are checked for convexity, and 'repaired' if necessary. Grid cells may appear to be nonconvex if they cross a ``0 / 2pi`` boundary. The repair consists of shifting the cell vertices to the same side modulo 360 degrees." + "None", "``sync()``", "Write any pending changes to the dataset." + + +MV Module +^^^^^^^^^ The fundamental CDMS data object is the variable. A variable is comprised of: -- a masked data array, as defined in the NumPy MA module. +- a masked data array, as defined in the NumPy MV2 module. - a domain: an ordered list of axes and/or grids. - an attribute dictionary. -The MV module is a work-alike replacement for the MA module, that +The MV module is a work-alike replacement for the MV2 module, that carries along the domain and attribute information where appropriate. MV -provides the same set of functions as MA. However, MV functions generate +provides the same set of functions as MV2. However, MV functions generate transient variables as results. Often this simplifies scripts that -perform computation. MA is part of the Python Numeric package, +perform computation. MV2 is part of the Python Numpy package, documented at http://www.numpy.org. MV can be imported with the command: -.. raw:: html - -
- :: import MV -.. raw:: html - -
- The command -.. raw:: html - -
- :: from MV import * -.. raw:: html - -
allows use of MV commands without any prefix. -Table 2.26 on page 75 lists the constructors in MV. All functions return +Table `Variable Constructors in module MV <#table-variable-constructors-in-module-mv>`_, lists the constructors in MV. All functions return a transient variable. In most cases the keywords axes, attributes, and id are available. axes is a list of axis objects which specifies the domain of the variable. attributes is a dictionary. id is a special @@ -1944,120 +1079,88 @@ should not contain blanks or non-printing characters. It is used when the variable is plotted or written to a file. Since the id is just an attribute, it can also be set like any attribute: -.. raw:: html - -
- :: var.id = 'temperature' -.. raw:: html - -
- -For completeness MV provides access to all the MA functions. The +For completeness MV provides access to all the MV2 functions. The functions not listed in the following tables are identical to the -corresponding MA function: ``allclose``, ``allequal``, +corresponding MV2 function: ``allclose``, ``allequal``, ``common_fill_value``, ``compress``, ``create_mask``, ``dot``, ``e``, ``fill_value``, ``filled``, ``get_print_limit``, ``getmask``, -``getmaskarray``, ``identity``, ``indices``, ``innerproduct``, ``isMA``, +``getmaskarray``, ``identity``, ``indices``, ``innerproduct``, ``isMV2``, ``isMaskedArray``, ``is_mask``, ``isarray``, ``make_mask``, ``make_mask_none``, ``mask_or``, ``masked``, ``pi``, ``put``, ``putmask``, ``rank``, ``ravel``, ``set_fill_value``, ``set_print_limit``, ``shape``, ``size``. See the documentation at http://numpy.sourceforge.net for a description of these functions. + + +Table Variable Constructors in Module MV +----------------------------------------- + +.. tabularcolumns:: |l|r| + + +.. csv-table:: + :header: "Constructor", "Description" + :widths: 50, 80 + :align: left + + "``arrayrange(start, stop=None, step=1, typecode=None, axis=None, attributes=None, id=None)``", "Just like ``MV2.arange()`` except it returns a variable whose type can be specfied by the keyword argument typecode. The axis, attribute dictionary, and string identifier of the result variable may be specified. **Synonym:** ``arange``" + "``masked_array(a, mask=None, fill_value=None, axes=None, attributes=None, id=None)``", "Same as MV2.masked_array but creates a variable instead. If no axes are specified, the result has default axes, otherwise axes is a list of axis objects matching a.shape." + "``masked_object(data,value, copy=1,savespace=0,axes=None, attributes=None, id=None)``", "Create variable masked where exactly data equal to value. Create the variable with the given list of axis objects, attribute dictionary, and string id." + "``masked_values(data,value, rtol=1e-05, atol=1e-08, copy=1, savespace=0, axes=None, attributes=None, id=None)``", "Constructs a variable with the given list of axes and attribute dictionary, whose mask is set at those places where ``abs(data - value) > atol + rtol * abs(data)``. This is a careful way of saying that those elements of the data that have value = value (to within a tolerance) are to be treated as invalid. If data is not of a floating point type, calls masked_object instead." + "``ones(shape, typecode='l',savespace=0,axes=none, attributes=none, id=none)``", "return an array of all ones of the given length or shape." + "``reshape(a,newshape, axes=none, attributes=none, id=none)``", "copy of a with a new shape." + "``resize(a,newshape, axes=none, attributes=none, id=none)``", "return a new array with the specified shape. the original arrays total size can be any size." + "``zeros(shape,typecode='l',savespace=0, axes=none, attributes=none, id=none)``", "an array of all zeros of the given length or shape" + -Table 2.26 Variable Constructors in module MV - -+--------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Constructor | Description | -+====================================================================================================================+================================================================================================================================================================================================================================================================================================================================================================================================+ -| ``arrayrange(start, stop=None, step=1, typecode=None, axis=None, attributes=None, id=None)`` | Just like ``MA.arange()`` except it returns a variable whose type can be specfied by the keyword argument typecode. The axis, attribute dictionary, and string identifier of the result variable may be specified. *Synonym:* ``arange`` | -+--------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``masked_array(a, mask=None, fill_value=None, axes=None, attributes=None, id=None)`` | Same as MA.masked\_array but creates a variable instead. If no axes are specified, the result has default axes, otherwise axes is a list of axis objects matching a.shape. | -+--------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``masked_object(data, value, copy=1, savespace=0, axes=None, attributes=None, id=None)`` | Create variable masked where exactly data equal to value. Create the variable with the given list of axis objects, attribute dictionary, and string id. | -+--------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``masked_values(data, value, rtol=1e-05, atol=1e-08, copy=1, savespace=0, axes=None, attributes=None, id=None)`` | Constructs a variable with the given list of axes and attribute dictionary, whose mask is set at those places where ``abs(data - value) < atol + rtol * abs(data)``. This is a careful way of saying that those elements of the data that have value = value (to within a tolerance) are to be treated as invalid. If data is not of a floating point type, calls masked\_object instead. | -+--------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``ones(shape, typecode='l', savespace=0, axes=none, attributes=none, id=none)`` | return an array of all ones of the given length or shape. | -+--------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``reshape(a, newshape, axes=none, attributes=none, id=none)`` | copy of a with a new shape. | -+--------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``resize(a, new_shape, axes=none, attributes=none, id=none)`` | return a new array with the specified shape. the original arrays total size can be any size. | -+--------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``zeros(shape, typecode='l', savespace=0, axes=none, attributes=none, id=none)`` | an array of all zeros of the given length or shape | -+--------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ The following table describes the MV non-constructor functions. with the exception of argsort, all functions return a transient variable. -Table 2.27 MV functions - -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Function | Description | -+=====================================================================+======================================================================================================================================================================================================================================================================================================================================================================+ -| ``argsort(x, axis=-1, fill_value=None)`` | Return a Numeric array of indices for sorting along a given axis. | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``asarray(data, typecode=None)`` | Same as ``cdms.createVariable(data, typecode, copy=0)``. This is a short way of ensuring that something is an instance of a variable of a given type before proceeding, as in ``data = asarray(data)``. Also see the variable ``astype()`` function. | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``average(a, axis=0, weights=None)`` | Computes the average value of the non-masked elements of x along the selected axis. If weights is given, it must match the size and shape of x, and the value returned is: ``sum(a*weights)/sum(weights)`` In computing these sums, elements that correspond to those that are masked in x or weights are ignored. | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``choose(condition, t)`` | Has a result shaped like array condition. ``t`` must be a tuple of two arrays ``t1`` and ``t2``. Each element of the result is the corresponding element of ``t1``\ where ``condition`` is true, and the corresponding element of ``t2`` where ``condition`` is false. The result is masked where ``condition`` is masked or where the selected element is masked. | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``concatenate(arrays, axis=0, axisid=None, axisattributes=None)`` | Concatenate the arrays along the given axis. Give the extended axis the id and attributes provided - by default, those of the first array. | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``count(a, axis=None)`` | Count of the non-masked elements in ``a``, or along a certain axis. | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``isMaskedVariable(x)`` | Return true if ``x`` is an instance of a variable. | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``masked_equal(x, value)`` | ``x`` masked where ``x`` equals the scalar value. For floating point values consider ``masked_values(x, value)`` instead. | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``masked_greater(x, value)`` | ``x`` masked where ``x > value`` | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``masked_greater_equal(x, value)`` | ``x`` masked where ``x >= value`` | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``masked_less(x, value)`` | ``x`` masked where ``x < value`` | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``masked_less_equal(x, value)`` | ``x`` masked where ``x ≤ value`` | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``masked_not_equal(x, value)`` | ``x`` masked where ``x != value`` | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``masked_outside(x, v1, v2)`` | ``x`` with mask of all values of ``x`` that are outside ``[v1,v2]`` | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``masked_where(condition, x, copy=1)`` | Return ``x`` as a variable masked where condition is true. Also masked where ``x`` or ``condition`` masked. ``condition`` is a masked array having the same shape as ``x``. | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``maximum(a, b=None)`` | Compute the maximum valid values of ``x`` if ``y`` is ``None``; with two arguments, return the element-wise larger of valid values, and mask the result where either ``x`` or ``y`` is masked. | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``minimum(a, b=None)`` | Compute the minimum valid values of ``x`` if ``y`` is None; with two arguments, return the element-wise smaller of valid values, and mask the result where either ``x`` or ``y`` is masked. | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``outerproduct(a, b)`` | Return a variable such that ``result[i, j] = a[i] * b[j]``. The result will be masked where ``a[i]`` or ``b[j]`` is masked. | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``power(a, b)`` | ``a**b`` | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``product(a, axis=0, fill_value=1)`` | Product of elements along axis using ``fill_value`` for missing elements. | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``repeat(ar, repeats, axis=0)`` | Return ``ar`` repeated ``repeats`` times along ``axis``. ``repeats`` is a sequence of length ``ar.shape[axis]`` telling how many times to repeat each element. | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``set_default_fill_value(value_type, value)`` | Set the default fill value for ``value_type`` to ``value``. ``value_type`` is a string: ‘real’,’complex’,’character’,’integer’,or ‘object’. ``value`` should be a scalar or single-element array. | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``sort(ar, axis=-1)`` | Sort array ``ar`` elementwise along the specified axis. The corresponding axis in the result has dummy values. | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``sum(a, axis=0, fill_value=0)`` | Sum of elements along a certain axis using ``fill_value`` for missing. | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``take(a, indices, axis=0)`` | Return a selection of items from ``a``. See the documentation in the Numeric manual. | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``transpose(ar, axes=None)`` | Perform a reordering of the axes of array ar depending on the tuple of indices axes; the default is to reverse the order of the axes. | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``where(condition, x, y)`` | ``x`` where ``condition`` is true, ``y`` otherwise | -+---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - - -2.10 HorizontalGrid -^^^^^^^^^^^^^^^^^^^ +Table MV Functions +------------------ +.. csv-table:: + :header: "Function", "Description" + :widths: 50, 80 + :align: left + + "``argsort(x, axis=-1, fill_value=None)``", "Return a Numpy array of indices for sorting along a given axis." + "``asarray(data, typecode=None)``", "Same as ``cdms.createVariable(data, typecode, copy=0)``. This is a short way of ensuring that something is an instance of a variable of a given type before proceeding, as in ``data = asarray(data)``. Also see the variable ``astype()`` function." + "``average(a, axis=0, weights=None)``", "Computes the average value of the non-masked elements of x along the selected axis. If weights is given, it must match the size and shape of x, and the value returned is: ``sum(a*weights)/sum(weights)`` In computing these sums, elements that correspond to those that are masked in x or weights are ignored." + "``choose(condition, t)``", "Has a result shaped like array condition. ``t`` must be a tuple of two arrays ``t1`` and ``t2``. Each element of the result is the corresponding element of ``t1``\ where ``condition`` is true, and the corresponding element of ``t2`` where ``condition`` is false. The result is masked where ``condition`` is masked or where the selected element is masked." + "``concatenate(arrays, axis=0, axisid=None, axisattributes=None)``", "Concatenate the arrays along the given axis. Give the extended axis the id and attributes provided - by default, those of the first array." + "``count(a, axis=None)``", "Count of the non-masked elements in ``a``, or along a certain axis." + "``isMaskedVariable(x)``", "Return true if ``x`` is an instance of a variable." + "``masked_equal(x, value)``", "``x`` masked where ``x`` equals the scalar value. For floating point values consider ``masked_values(x, value)`` instead." + "``masked_greater(x, value)``", "``x`` masked where ``x > value``" + "``masked_greater_equal(x, value)``", "``x`` masked where ``x >= value``" + "``masked_less(x, value)``", "``x`` masked where ``x < value``" + "``masked_less_equal(x, value)``", "``x`` masked where ``x ≤ value``" + "``masked_not_equal(x, value)``", "``x`` masked where ``x != value``" + "``masked_outside(x, v1, v2)``", "``x`` with mask of all values of ``x`` that are outside ``[v1,v2]``" + "``masked_where(condition, x, copy=1)``", "Return ``x`` as a variable masked where condition is true. Also masked where ``x`` or ``condition`` masked. ``condition`` is a masked array having the same shape as ``x``." + "``maximum(a, b=None)``", "Compute the maximum valid values of ``x`` if ``y`` is ``None``; with two arguments, return the element-wise larger of valid values, and mask the result where either ``x`` or ``y`` is masked." + "``minimum(a, b=None)``", "Compute the minimum valid values of ``x`` if ``y`` is None; with two arguments, return the element-wise smaller of valid values, and mask the result where either ``x`` or ``y`` is masked." + "``outerproduct(a, b)``", "Return a variable such that ``result[i, j] = a[i] * b[j]``. The result will be masked where ``a[i]`` or ``b[j]`` is masked." + "``power(a, b)``", "``a**b``" + "``product(a, axis=0, fill_value=1)``", "Product of elements along axis using ``fill_value`` for missing elements." + "``repeat(ar, repeats, axis=0)``", "Return ``ar`` repeated ``repeats`` times along ``axis``. ``repeats`` is a sequence of length ``ar.shape[axis]`` telling how many times to repeat each element." + "``set_default_fill_value(value_type, value)``", "Set the default fill value for ``value_type`` to ``value``. ``value_type`` is a string: ‘real’,’complex’,’character’,’integer’,or ‘object’. ``value`` should be a scalar or single-element array." + "``sort(ar, axis=-1)``", "Sort array ``ar`` elementwise along the specified axis. The corresponding axis in the result has dummy values." + "``sum(a, axis=0, fill_value=0)``", "Sum of elements along a certain axis using ``fill_value`` for missing." + "``take(a, indices, axis=0)``", "Return a selection of items from ``a``. See the documentation in the Numpy manual." + "``transpose(ar, axes=None)``", "Perform a reordering of the axes of array ar depending on the tuple of indices axes; the default is to reverse the order of the axes." + "``where(condition, x, y)``", "``x`` where ``condition`` is true, ``y`` otherwise" + + +HorizontalGrid +^^^^^^^^^^^^^^ A HorizontalGrid represents a latitude-longitude coordinate system. In addition, it optionally describes how lat-lon space is partitioned into @@ -2071,416 +1174,127 @@ cells. Specifically, a HorizontalGrid: CDMS supports several types of HorizontalGrids: -Table 2.28 - -+-------------------+----------------------------------------------------------------------------------+ -| Grid Type | Definition | -+===================+==================================================================================+ -| ``RectGrid`` | Associated latitude an longitude are 1-D axes, with strictly monotonic values. | -+-------------------+----------------------------------------------------------------------------------+ -| ``CurveGrid`` | Latitude and longitude are 2-D coordinate axes (Axis2D). | -+-------------------+----------------------------------------------------------------------------------+ -| ``GenericGrid`` | Latitude and longitude are 1-D auxiliary coordinate axis (AuxAxis1D) | -+-------------------+----------------------------------------------------------------------------------+ - - -Table 2.29 HorizontalGrid Internal Attribute - -+-----------------------+------------------+------------------------------------------------+ -| Type | Name | Definition | -+=======================+==================+================================================+ -| Dictionary | ``attributes`` | External attribute dictionary. | -+-----------------------+------------------+------------------------------------------------+ -| String | ``id`` | The grid identifier. | -+-----------------------+------------------+------------------------------------------------+ -| Dataset or CdmsFile | ``parent`` | The dataset or file which contains the grid. | -+-----------------------+------------------+------------------------------------------------+ -| Tuple | ``shape`` | The shape of the grid, a 2-tuple | -+-----------------------+------------------+------------------------------------------------+ - -Table 2.31 on page 82 describes the methods that apply to all types of -HorizontalGrids. Table 2.32 on page 86 describes the additional methods -that are unique to RectGrids. - - -Table 2.30 RectGrid Constructors - -+---------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+ -| Constructor | Description | -+=========================================================================================================+==================================================================================+ -| ``cdms.createRectGrid(lat, lon, order, type="generic", mask=None)`` | Create a grid not associated with a file or dataset. See Table 2.2 on page 33. | -+---------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+ -| ``CdmsFile.createRectGrid(id, lat, lon, order, type="generic", mask=None)`` | Create a grid associated with a file. See Table 2.14 on page 53. | -+---------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+ -| ``Dataset.createRectGrid(id, lat, lon, order, type="generic", mask=None)`` | Create a grid associated with a dataset. See Table 2.25 on page 71. | -+---------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+ -| ``cdms.createGaussianGrid(nlats, xorigin=0.0, order="yx")`` | See Table 2.2 on page 33. | -+---------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+ -| ``cdms.createGenericGrid(latArray, lonArray, latBounds=None, lonBounds=None, order="yx", mask=None)`` | See Table 2.2 on page 18. | -+---------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+ -| ``cdms.createGlobalMeanGrid(grid)`` | See Table 2.2 on page 18. | -+---------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+ -| ``cdms.createRectGrid(lat, lon, order, type="generic", mask=None)`` | See Table 2.2 on page 18. | -+---------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+ -| ``cdms.createUniformGrid(startLat, nlat, deltaLat, startLon, nlon, deltaLon, order="yx", mask=None)`` | See Table 2.2 on page 18. | -+---------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+ -| ``cdms.createZonalGrid(grid)`` | See Table 2.2 on page 18 | -+---------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+ - - -Table 2.31 HorizontalGrid Methods - -+--------------------------+--------------------------+--------------------------+ -| Type | Method | Description | -+==========================+==========================+==========================+ -| Horizontal-Grid | ``clone()`` | Return a transient copy | -| | | of the grid. | -+--------------------------+--------------------------+--------------------------+ -| Axis | ``getAxis(Integer n)`` | Get the n-th axis.n is | -| | | either 0 or 1. | -+--------------------------+--------------------------+--------------------------+ -| Tuple | ``getBounds()`` | Get the grid boundary | -| | | arrays. | -| | | | -| | | Returns a tuple | -| | | ``(latitudeArray, longit | -| | | udeArray)``, | -| | | where latitudeArray is a | -| | | Numeric array of | -| | | latitude bounds, and | -| | | similarly for | -| | | longitudeArray.The shape | -| | | of latitudeArray and | -| | | longitudeArray depend on | -| | | the type of grid: | -| | | | -| | | - for rectangular grids | -| | | with shape (nlat, | -| | | nlon), the boundary | -| | | arrays have shape | -| | | (nlat,2) and | -| | | (nlon,2). | -| | | - for curvilinear grids | -| | | with shape (nx, ny), | -| | | the boundary arrays | -| | | each have shape (nx, | -| | | ny, 4). | -| | | - for generic grids | -| | | with shape (ncell,), | -| | | the boundary arrays | -| | | each have shape | -| | | (ncell, nvert) where | -| | | nvert is the maximum | -| | | number of vertices | -| | | per cell. | -| | | | -| | | For rectilinear grids: | -| | | If no boundary arrays | -| | | are explicitly defined | -| | | (in the file or | -| | | dataset), the result | -| | | depends on the auto- | -| | | Bounds mode (see | -| | | ``cdms.setAutoBounds``) | -| | | and the grid | -| | | classification mode (see | -| | | ``cdms.setClassifyGrids` | -| | | `). | -| | | By default, autoBounds | -| | | mode is enabled, in | -| | | which case the boundary | -| | | arrays are generated | -| | | based on the type of | -| | | grid. If disabled, the | -| | | return value is | -| | | (None,None).For | -| | | rectilinear grids: The | -| | | grid classification mode | -| | | specifies how the grid | -| | | type is to be | -| | | determined. By default, | -| | | the grid type (Gaussian, | -| | | uniform, etc.) is | -| | | determined by calling | -| | | grid.classifyInFamily. | -| | | If the mode is 'off' | -| | | grid.getType is used | -| | | instead. | -+--------------------------+--------------------------+--------------------------+ -| Axis | ``getLatitude()`` | Get the latitude axis of | -| | | this grid. | -+--------------------------+--------------------------+--------------------------+ -| Axis | ``getLongitude()`` | Get the latitude axis of | -| | | this grid. | -+--------------------------+--------------------------+--------------------------+ -| Axis | ``getMask()`` | Get the mask array of | -| | | this grid, if | -| | | any.Returns a 2-D | -| | | Numeric array, having | -| | | the same shape as the | -| | | grid. If the mask is not | -| | | explicitly defined, the | -| | | return value is | -| | | ``None``. | -+--------------------------+--------------------------+--------------------------+ -| Axis | ``getMesh(self, transpos | Generate a mesh array | -| | e=None)`` | for the meshfill | -| | | graphics method.If | -| | | transpose is defined to | -| | | a tuple, say (1,0), | -| | | first transpose | -| | | latbounds and lonbounds | -| | | according to the tuple, | -| | | in this case (1,0,2). | -+--------------------------+--------------------------+--------------------------+ -| None | ``setBounds(latBounds, l | Set the grid | -| | onBounds, persistent=0)` | boundaries.\ ``latBounds | -| | ` | `` | -| | | is a NumPy array of | -| | | shape (n,2), such that | -| | | the boundaries of the | -| | | kth axis value are | -| | | ``[latBounds[k,0],latBou | -| | | nds[k,1] ]``. | -| | | ``lonBounds`` is defined | -| | | similarly for the | -| | | longitude array. | -| | | **Note:** By default, | -| | | the boundaries are not | -| | | written to the file or | -| | | dataset containing the | -| | | grid (if any). This | -| | | allows bounds to be set | -| | | on read-only files, for | -| | | regridding. If the | -| | | optional argument | -| | | ``persistent`` is set to | -| | | 1, the boundary array is | -| | | written to the file. | -+--------------------------+--------------------------+--------------------------+ -| None | ``setMask(mask, persiste | Set the grid mask. If | -| | nt=0)`` | ``persistent == 1``, the | -| | | mask values are written | -| | | to the associated file, | -| | | if any. Otherwise, the | -| | | mask is associated with | -| | | the grid, but no I/O is | -| | | generated. ``mask`` is a | -| | | two-dimensional, | -| | | Boolean-valued Numeric | -| | | array, having the same | -| | | shape as the grid. | -+--------------------------+--------------------------+--------------------------+ -| Horizontal-Grid | ``subGridRegion(latInter | Create a new grid | -| | val, lonInterval)`` | corresponding to the | -| | | coordinate region | -| | | defined by | -| | | ``latInterval, lonInterv | -| | | al.`` | -| | | | -| | | ``latInterval`` and | -| | | ``lonInterval`` are the | -| | | coordinate intervals for | -| | | latitude and longitude, | -| | | respectively. | -| | | | -| | | Each interval is a tuple | -| | | having one of the forms: | -| | | | -| | | - ``(x,y)`` | -| | | - ``(x,y,indicator)`` | -| | | - ``(x,y,indicator,cycl | -| | | e)`` | -| | | - ``None`` | -| | | | -| | | where ``x`` and ``y`` | -| | | are coordinates | -| | | indicating the interval | -| | | ``[x,y)``, and: | -| | | | -| | | ``indicator`` is a | -| | | two-character string, | -| | | where the first | -| | | character is 'c' if the | -| | | interval is closed on | -| | | the left, 'o' if open, | -| | | and the second character | -| | | has the same meaning for | -| | | the right-hand point. | -| | | (Default: 'co'). | -| | | | -| | | If ``cycle`` is | -| | | specified, the axis is | -| | | treated as circular with | -| | | the given cycle value. | -| | | By default, if | -| | | ``grid.isCircular()`` is | -| | | true, the axis is | -| | | treated as circular with | -| | | a default value of | -| | | 360.0. | -| | | | -| | | An interval of ``None`` | -| | | returns the full index | -| | | interval of the axis. | -| | | | -| | | If a mask is defined, | -| | | the subgrid also has a | -| | | mask corresponding to | -| | | the index ranges.Note: | -| | | The result grid is not | -| | | associated with any file | -| | | or dataset. | -+--------------------------+--------------------------+--------------------------+ -| Transient-CurveGrid | ``toCurveGrid(gridid=Non | Convert to a curvilinear | -| | e)`` | grid. If the grid is | -| | | already curvilinear, a | -| | | copy of the grid object | -| | | is returned. ``gridid`` | -| | | is the string identifier | -| | | of the resulting | -| | | curvilinear grid object. | -| | | If unspecified, the grid | -| | | ID is copied. **Note:** | -| | | This method does not | -| | | apply to generic grids. | -+--------------------------+--------------------------+--------------------------+ -| Transient-GenericGrid | ``toGenericGrid(gridid=N | Convert to a generic | -| | one)`` | grid. If the grid is | -| | | already generic, a copy | -| | | of the grid is returned. | -| | | ``gridid`` is the string | -| | | identifier of the | -| | | resulting curvilinear | -| | | grid object. If | -| | | unspecified, the grid ID | -| | | is copied. | -+--------------------------+--------------------------+--------------------------+ - - -Table 2.32 RectGrid Methods, additional to HorizontalGrid - Methods - -+--------------------------+--------------------------+--------------------------+ -| Type | Method | Description | -+==========================+==========================+==========================+ -| String | ``getOrder()`` | Get the grid ordering, | -| | | either "yx" if latitude | -| | | is the first axis, or | -| | | "xy" if longitude is the | -| | | first axis. | -+--------------------------+--------------------------+--------------------------+ -| String | ``getType()`` | Get the grid type, | -| | | either "gaussian", | -| | | "uniform", "equalarea", | -| | | or "generic". | -+--------------------------+--------------------------+--------------------------+ -| (Array,Array) | ``getWeights()`` | Get the normalized area | -| | | weight arrays, as a | -| | | tuple | -| | | ``(latWeights, lon | -| | | Weights)``. | -| | | It is assumed that the | -| | | latitude and longitude | -| | | axes are defined in | -| | | degrees. | -| | | | -| | | The latitude weights are | -| | | defined as: | -| | | | -| | | ``latWeights[i] = 0.5 * | -| | | abs(sin(latBounds[i+1]) | -| | | - sin(latBounds[i] | -| | | ))`` | -| | | | -| | | The longitude weights | -| | | are defined as: | -| | | | -| | | ``lonWeights[i] = abs(lo | -| | | nBounds[i+1] - lonBounds | -| | | [i])/360.0`` | -| | | | -| | | For a global grid, the | -| | | weight arrays are | -| | | normalized such that the | -| | | sum of the weights is | -| | | 1.0 | -| | | | -| | | **Example:** | -| | | | -| | | Generate the 2-D weights | -| | | array, such that | -| | | ``weights[i.j]`` is the | -| | | fractional area of grid | -| | | zone ``[i,j]``. | -| | | | -| | | :: | -| | | | -| | | from cdms import MV | -| | | latwts, lonwts = gri | -| | | d.getWeights() | -| | | weights = MV.outerpr | -| | | oduct(latwts, lonwts) | -| | | | -| | | Also see the function | -| | | ``area_weights`` in | -| | | module | -| | | ``pcmdi.weighting``. | -+--------------------------+--------------------------+--------------------------+ -| None | ``setType(gridtype)`` | Set the grid type. | -| | | ``gridtype`` is one of | -| | | "gaussian", "uniform", | -| | | "equalarea", or | -| | | "generic". | -+--------------------------+--------------------------+--------------------------+ -| RectGrid | ``subGrid((latStart,latS | Create a new grid, with | -| | top),(lonStart,lonStop)) | latitude index range | -| | `` | [latStart : latStop] and | -| | | longitude index range | -| | | [lonStart : lonStop]. | -| | | Either index range can | -| | | also be specified as | -| | | None, indicating that | -| | | the entire range of the | -| | | latitude or longitude is | -| | | used. | -| | | | -| | | **Example:** | -| | | | -| | | This creates newgrid | -| | | corresponding to all | -| | | latitudes and index | -| | | range [lonStart:lonStop] | -| | | of oldgrid. | -| | | | -| | | ``newgrid = oldgrid.subG | -| | | rid(None, (lonStart, lon | -| | | Stop))`` | -| | | | -| | | If a mask is defined, | -| | | the subgrid also has a | -| | | mask corresponding to | -| | | the index ranges. | -| | | | -| | | **Note:** The result | -| | | grid is not associated | -| | | with any file or | -| | | dataset. | -+--------------------------+--------------------------+--------------------------+ -| RectGrid | ``transpose()`` | Create a new grid, with | -| | | axis order reversed. The | -| | | grid mask is also | -| | | transposed. | -| | | | -| | | **Note:** The result | -| | | grid is not associated | -| | | with any file or | -| | | dataset. | -+--------------------------+--------------------------+--------------------------+ - - -2.11 Variable -^^^^^^^^^^^^^ +Table Grids +----------- + +.. csv-table:: + :header: "Grid Type", "Definition" + :widths: 50, 80 + :align: left + + "``RectGrid``", "Associated latitude an longitude are 1-D axes, with strictly monotonic values." + "``GenericGrid``", "Latitude and longitude are 1-D auxiliary coordinate axis (AuxAxis1D)" + + +Table HorizontalGrid Internal Attribute +--------------------------------------- + +.. csv-table:: + :header: "Type", "Name", "Definition" + :widths: 30, 30, 100 + :align: left + + "Dictionary","``attributes``", "External attribute dictionary." + "String", "``id``", "The grid identifier." + "Dataset or CdmsFile", "``parent``", "The dataset or file which contains the grid." + "Tuple", "``shape``", "The shape of the grid, a 2-tuple" + + + +Table RectGrid Constructors +--------------------------- + +.. csv-table:: + :header: "Constructor", "Description" + :widths: 30, 80 + :align: left + + + "``cdms.createRectGrid(lat, lon, order, type='generic', mask=None)``", "Create a grid not associated with a file or dataset. See `A First Example`_" + "``CdmsFile.createRectGrid(id, lat, lon, order, type='generic', mask=None)``", "Create a grid associated with a file. See `CdmsFile Constructors <#table-cdmsfile-constructors>`_" + "``Dataset.createRectGrid(id, lat, lon, order, type='generic', mask=None)``", "Create a grid associated with a dataset. See `Dataset Constructors <#table-dataset-constructors>`_ " + "``cdms.createGaussianGrid(nlats, xorigin=0.0, order='yx')``", "See `A First Example`_" + "``cdms.createGenericGrid(latArray, lonArray, latBounds=None, lonBounds=None, order='yx', mask=None)``", "See `A First Example`_" + "``cdms.createGlobalMeanGrid(grid)``", "See `A First Example`_" + "``cdms.createRectGrid(lat, lon, order, type='generic', mask=None)``", "See `A First Example`_" + "``cdms.createUniformGrid(startLat, nlat, deltaLat, startLon, nlon, deltaLon, order='yx', mask=None)``", "See `A First Example`_" + "``cdms.createZonalGrid(grid)``", "See `A First Example`_" + + + +Table HorizontalGrid Methods +---------------------------- + + +.. csv-table:: + :header: "Type", "Method", "Description" + :widths: 30, 30, 80 + + "Horizontal-Grid", "``clone()``", "Return a transient copy of the grid." + "Axis", "``getAxis(Integer n)``", "Get the n-th axis.n is either 0 or 1." + "Tuple", "``getBounds()``", "Get the grid boundary arrays." + ,,"Returns a tuple ``(latitudeArray, longitudeArray)``, where latitudeArray is a Numpy array of latitude bounds, and similarly for longitudeArray.The shape of latitudeArray and longitudeArray depend on the type of grid:" + ,,"* for rectangular grids with shape (nlat, nlon), the boundary arrays have shape (nlat,2) and (nlon,2)." + ,,"* for curvilinear grids with shape (nx, ny), the boundary arrays each have shape (nx, ny, 4)." + ,,"* for generic grids with shape (ncell,), the boundary arrays each have shape (ncell, nvert) where nvert is the maximum number of vertices per cell." + ,,"For rectilinear grids: If no boundary arrays are explicitly defined (in the file or dataset), the result depends on the auto- Bounds mode (see ``cdms.setAutoBounds``) and the grid classification mode (see ``cdms.setClassifyGrids``)." + ,,"By default, autoBounds mode is enabled, in which case the boundary arrays are generated based on the type of grid. If disabled, the return value is (None,None).For rectilinear grids: The grid classification mode specifies how the grid type is to be determined. By default, the grid type (Gaussian, uniform, etc.) is determined by calling grid.classifyInFamily. If the mode is 'off' grid.getType is used instead." + "Axis", "``getLatitude()``", "Get the latitude axis of this grid." + "Axis", "``getLongitude()``", " Get the latitude axis of this grid." + "Axis", "``getMask()``", "Get the mask array of this grid, if any.Returns a 2-D Numpy array, having the same shape as the grid. If the mask is not explicitly defined, the return value is ``None``." + "Axis", "``getMesh(self, transpose=None)``", "Generate a mesh array for the meshfill graphics method.If transpose is defined to a tuple, say (1,0), first transpose latbounds and lonbounds according to the tuple, in this case (1,0,2)." + "None", "``setBounds(latBounds, lonBounds, persistent=0)``", "Set the grid boundaries. ``latBounds`` is a NumPy array of shape (n,2), such that the boundaries of the kth axis value are ``[latBounds[k,0],latBou nds[k,1] ]``. ``lonBounds`` is defined similarly for the longitude array." + ,,"**Note:** By default, the boundaries are not written to the file or dataset containing the grid (if any). This allows bounds to be set on read-only files, for regridding. If the optional argument ``persistent`` is set to the boundary array is written to the file." + "None", "``setMask(mask, persistent=0)``", "Set the grid mask. If ``persistent == 1``, the mask values are written to the associated file, if any. Otherwise, the mask is associated with the grid, but no I/O is generated. ``mask`` is a two-dimensional, Boolean-valued Numpy array, having the same shape as the grid." + "Horizontal-Grid", "``subGridRegion(latInterval, lonInterval)``", "Create a new grid corresponding to the coordinate region defined by ``latInterval, lonInterv al.``" + ,,"``latInterval`` and ``lonInterval`` are the coordinate intervals for latitude and longitude, respectively." + ,,"Each interval is a tuple having one of the forms:" + ,,"* ``(x,y)``" + ,,"* ``(x,y,indicator)``" + ,,"* ``(x,y,indicator,cycle)``" + ,,"* ``None``" + ,,"where ``x`` and ``y`` are coordinates indicating the interval ``[x,y)``, and:" + ,,"``indicator`` is a two-character string, where the first character is 'c' if the interval is closed on the left, 'o' if open, and the second character has the same meaning for the right-hand point. (Default: 'co')." + ,,"If ``cycle`` is specified, the axis is treated as circular with the given cycle value. By default, if ``grid.isCircular()`` is true, the axis is treated as circular with a default value of 360.0." + ,,"An interval of ``None`` returns the full index interval of the axis." + ,,"If a mask is defined, the subgrid also has a mask corresponding to the index ranges.Note: The result grid is not associated with any file or dataset." + "Transient-CurveGrid", "``toCurveGrid(gridid=None)``", "Convert to a curvilinear grid. If the grid is already curvilinear, a copy of the grid object is returned. ``gridid`` is the string identifier of the resulting curvilinear grid object. If unspecified, the grid ID is copied." + ,,"**Note:** This method does not apply to generic grids. Transient-GenericGrid ``toGenericGrid(gridid=None)`` Convert to a generic grid. If the grid is already generic, a copy of the grid is returned. ``gridid`` is the string identifier of the resulting curvilinear grid object. If unspecified, the grid ID is copied." + + +Table RectGrid Methods, Additional to HorizontalGrid Methods +------------------------------------------------------------ + +.. csv-table:: + :header: "Type", "Method", "Description" + :widths: 30, 30, 80 + + "String", "``getOrder()``", "Get the grid ordering, either 'yx' if latitude is the first axis, or 'xy' if longitude is the first axis. String ``getType()`` Get the grid type, either 'gaussian', 'uniform', 'equalarea', or 'generic'. (Array,Array) ``getWeights()`` Get the normalized area weight arrays, as a tuple ``(latWeights, lonWeights)``. It is assumed that the latitude and longitude axes are defined in degrees." + ,,"The latitude weights are defined as:" + ,,"``latWeights[i] = 0.5 * abs(sin(latBounds[i+1]) - sin(latBounds[i]))``" + ,," The longitude weights are defined as:" + ,,"``lonWeights[i] = abs(lonBounds[i+1] - lonBounds [i])/360.0``" + ,,"For a global grid, the weight arrays are normalized such that the sum of the weights is 1.0" + ,,"**Example:**" + ,,"Generate the 2-D weights array, such that ``weights[i.j]`` is the fractional area of grid zone ``[i,j]``." + ,,"* from cdms import MV" + ,,"* latwts, lonwts = gri d.getWeights()" + ,,"* weights = MV.outerproduct(latwts, lonwts)" + ,,"Also see the function ``area_weights`` in module ``pcmdi.weighting``." + ,," " + "None", "``setType(gridtype)``", "Set the grid type. ``gridtype`` is one of 'gaussian', 'uniform', 'equalarea', or 'generic'." + "RectGrid", "``subGrid((latStart,latStop),(lonStart,lonStop))``", "Create a new grid, with latitude index range `` [latStart : latStop] and longitude index range [lonStart : lonStop]. Either index range can also be specified as None, indicating that the entire range of the latitude or longitude is used." + ,,"**Example:**" + ,,"This creates newgrid corresponding to all latitudes and index range [lonStart:lonStop] of oldgrid." + ,,"``newgrid = oldgrid.subGrid(None, (lonStart, lon Stop))``" + ,,"If a mask is defined, the subgrid also has a mask corresponding to the index ranges." + ,,"**Note:** The result grid is not associated with any file or dataset." + "RectGrid", "``transpose()``", "Create a new grid, with axis order reversed. The grid mask is also transposed." + ,,"**Note:** The result grid is not associated with any file or dataset." + + +Variable +^^^^^^^^ A Variable is a multidimensional data object, consisting of: @@ -2507,889 +1321,293 @@ advantage of the attribute, domain, and mask information in a transient variable. -Table 2.33 Variable Internal Attributes - -+-----------------------+----------------------+-----------------------------------------------------------------------------------------------------------------------------+ -| Type | Name | Definition | -+=======================+======================+=============================================================================================================================+ -| Dictionary | ``attributes`` | External attribute dictionary. | -+-----------------------+----------------------+-----------------------------------------------------------------------------------------------------------------------------+ -| String | ``id`` | Variable identifier. | -+-----------------------+----------------------+-----------------------------------------------------------------------------------------------------------------------------+ -| String | ``name\_in\_file`` | The name of the variable in the file or files which represent the dataset. If different from id, the variable is aliased. | -+-----------------------+----------------------+-----------------------------------------------------------------------------------------------------------------------------+ -| Dataset or CdmsFile | ``parent`` | The dataset or file which contains the variable. | -+-----------------------+----------------------+-----------------------------------------------------------------------------------------------------------------------------+ -| Tuple | ``shape`` | The length of each axis of the variable | -+-----------------------+----------------------+-----------------------------------------------------------------------------------------------------------------------------+ - - -Table 2.34 Variable Constructors - -+--------------------------------------+--------------------------------------+ -| Constructor | Description | -+======================================+======================================+ -| ``Dataset.createVariable(String id, | Create a Variable in a Dataset. This | -| String datatype, List axes)`` | function is not yet implemented. | -+--------------------------------------+--------------------------------------+ -| ``CdmsFile.createVariable(String id, | Create a Variable in a CdmsFile. | -| String datatype, List axesOr- | ``id`` is the name of the variable. | -| Grids)`` | ``datatype`` is the MA or Numeric | -| | typecode, for example, MA.Float. | -| | ``axesOrGrids`` is a list of Axis | -| | and/or Grid objects, on which the | -| | variable is defined. Specifying a | -| | rectilinear grid is equivalent to | -| | listing the grid latitude and | -| | longitude axes, in the order defined | -| | for the grid. \*\*Note:\*\* this | -| | argument can either be a list or a | -| | tuple. If the tuple form is used, | -| | and there is only one element, it | -| | must have a following comma, e.g.: | -| | ``(axisobj,)``. | -+--------------------------------------+--------------------------------------+ -| :: | Create a transient variable, not | -| | associated with a file or dataset. | -| cdms.createVariable(array, typec | ``array`` is the data values: a | -| ode=None, copy=0, savespace=0,mask=N | Variable, masked array, or Numeric | -| one, fill_value=None, grid=None, axe | array. ``typecode`` is the MA | -| s=None,attributes=None, id=None) | typecode of the array. Defaults to | -| | the typecode of array. ``copy`` is | -| | an integer flag: if 1, the variable | -| | is created with a copy of the array, | -| | if 0 the variable data is shared | -| | with array. ``savespace`` is an | -| | integer flag: if set to 1, internal | -| | Numeric operations will attempt to | -| | avoid silent upcasting. ``mask`` is | -| | an array of integers with value 0 or | -| | 1, having the same shape as array. | -| | array elements with a corresponding | -| | mask value of 1 are considered | -| | invalid, and are not used for | -| | subsequent Numeric operations. The | -| | default mask is obtained from array | -| | if present, otherwise is None. | -| | ``fill_value`` is the missing value | -| | flag. The default is obtained from | -| | array if possible, otherwise is set | -| | to 1.0e20 for floating point | -| | variables, 0 for integer-valued | -| | variables. ``grid`` is a rectilinear | -| | grid object. ``axes`` is a tuple of | -| | axis objects. By default the axes | -| | are obtained from array if present. | -| | Otherwise for a dimension of length | -| | n, the default axis has values [0., | -| | 1., ..., double(n)]. ``attributes`` | -| | is a dictionary of attribute values. | -| | The dictionary keys must be strings. | -| | By default the dictionary is | -| | obtained from array if present, | -| | otherwise is empty. ``id`` is the | -| | string identifier of the variable. | -| | By default the id is obtained from | -| | array if possible, otherwise is set | -| | to 'variable\_n' for some integer n. | -+--------------------------------------+--------------------------------------+ - - - -Table 2.35 Variable Methods - -+--------------------------+--------------------------+--------------------------+ -| Type | Method | Definition | -+==========================+==========================+==========================+ -| Variable | ``tvar = var[ i:j, m:n]` | Read a slice of data | -| | ` | from the file or | -| | | dataset, resulting in a | -| | | transient variable. | -| | | Singleton dimensions are | -| | | 'squeezed' out. Data is | -| | | returned in the physical | -| | | ordering defined in the | -| | | dataset. The forms of | -| | | the slice operator are | -| | | listed in Table 2.36 on | -| | | page 102. | -+--------------------------+--------------------------+--------------------------+ -| None | ``var[ i:j, m:n] = array | Write a slice of data to | -| | `` | the external dataset. | -| | | The forms of the slice | -| | | operator are listed in | -| | | Table 2.21 on page 32. | -| | | (Variables in CdmsFiles | -| | | only) | -+--------------------------+--------------------------+--------------------------+ -| Variable | ``tvar = var(selector)`` | Calling a variable as a | -| | | function reads the | -| | | region of data defined | -| | | by the selector. The | -| | | result is a transient | -| | | variable, unless raw=1 | -| | | keyword is specified. | -| | | See "Selectors" on page | -| | | 103. | -+--------------------------+--------------------------+--------------------------+ -| None | ``assignValue(Array ar)` | Write the entire data | -| | ` | array. Equivalent to | -| | | ``var[:] = ar``. | -| | | (Variables in CdmsFiles | -| | | only). | -+--------------------------+--------------------------+--------------------------+ -| Variable | ``astype(typecode)`` | Cast the variable to a | -| | | new datatype. Typecodes | -| | | are as for MV, MA, and | -| | | Numeric modules. | -+--------------------------+--------------------------+--------------------------+ -| Variable | ``clone(copyData=1)`` | Return a copy of a | -| | | transient variable. | -| | | | -| | | If copyData is 1 (the | -| | | default) the variable | -| | | data is copied as well. | -| | | If copyData is 0, the | -| | | result transient | -| | | variable shares the | -| | | original transient | -| | | variables data array. | -+--------------------------+--------------------------+--------------------------+ -| Transient Variable | :: | Return a lat/level | -| | | vertical cross-section | -| | crossSectionRegrid(n | regridded to a new set | -| | ewLevel, newLatitude, me | of latitudes newLatitude | -| | thod="log", missing=None | and levels newLevel. The | -| | , order=None) | variable should be a | -| | | function of latitude, | -| | | level, and (optionally) | -| | | time. | -| | | | -| | | ``newLevel`` is an axis | -| | | of the result pressure | -| | | levels. | -| | | | -| | | ``newLatitude`` is an | -| | | axis of the result | -| | | latitudes. | -| | | | -| | | ``method`` is optional, | -| | | either "log" to | -| | | interpolate in the log | -| | | of pressure (default), | -| | | or "linear" for linear | -| | | interpolation. | -| | | | -| | | ``missing`` is a missing | -| | | data value. The default | -| | | is ``var.getMissing()`` | -| | | | -| | | ``order`` is an order | -| | | string such as "tzy" or | -| | | "zy". The default is | -| | | ``var.getOrder()``. | -| | | | -| | | *See also:* ``regrid``, | -| | | ``pressureRegrid``. | -+--------------------------+--------------------------+--------------------------+ -| Axis | ``getAxis(n)`` | Get the n-th axis. | -| | | | -| | | ``n`` is an integer. | -+--------------------------+--------------------------+--------------------------+ -| List | ``getAxisIds()`` | Get a list of axis | -| | | identifiers. | -+--------------------------+--------------------------+--------------------------+ -| Integer | ``getAxisIndex(axis_spec | Return the index of the | -| | )`` | axis specificed by | -| | | axis\_spec. Return -1 if | -| | | no match. | -| | | | -| | | ``axis_spec`` is a | -| | | specification as defined | -| | | for getAxisList | -+--------------------------+--------------------------+--------------------------+ -| List | ``getAxisList(axes=None, | Get an ordered list of | -| | omit=None, order=None)` | axis objects in the | -| | ` | domain of the variable. | -| | | | -| | | If ``axes`` is not | -| | | ``None``, include only | -| | | certain axes. Otherwise | -| | | axes is a list of | -| | | specifications as | -| | | described below. Axes | -| | | are returned in the | -| | | order specified unless | -| | | the order keyword is | -| | | given. | -| | | | -| | | If ``omit`` is not | -| | | ``None``, omit those | -| | | specified by an integer | -| | | dimension number. | -| | | Otherwise omit is a list | -| | | of specifications as | -| | | described below. | -| | | | -| | | ``order`` is an optional | -| | | string determining the | -| | | output order. | -| | | | -| | | Specifications for the | -| | | axes or omit keywords | -| | | are a list, each element | -| | | having one of the | -| | | following forms: | -| | | | -| | | - an integer dimension | -| | | index, starting at 0. | -| | | - a string representing | -| | | an axis id or one of | -| | | the strings 'time', | -| | | 'latitude', 'lat', | -| | | 'longitude', 'lon', | -| | | 'lev' or 'level'. | -| | | - a function that takes | -| | | an axis as an | -| | | argument and returns | -| | | a value. If the value | -| | | returned is true, the | -| | | axis matches. | -| | | - an axis object; will | -| | | match if it is the | -| | | same object as axis. | -| | | | -| | | ``order`` can be a | -| | | string containing the | -| | | characters t,x,y,z, or | -| | | -. If a dash ('-') is | -| | | given, any elements of | -| | | the result not chosen | -| | | otherwise are filled in | -| | | from left to right with | -| | | remaining candidates. | -+--------------------------+--------------------------+--------------------------+ -| List | ``getAxisListIndex(axes= | Return a list of indices | -| | None, omit=None, order=N | of axis objects. | -| | one)`` | Arguments are as for | -| | | getAxisList. | -+--------------------------+--------------------------+--------------------------+ -| List | ``getDomain()`` | Get the domain. Each | -| | | element of the list is | -| | | itself a tuple of the | -| | | form | -| | | ``(axis,start,length,tru | -| | | e_length)`` | -| | | where axis is an axis | -| | | object, start is the | -| | | start index of the | -| | | domain relative to the | -| | | axis object, length is | -| | | the length of the axis, | -| | | and true\_length is the | -| | | actual number of | -| | | (defined) points in the | -| | | domain. *See also:* | -| | | ``getAxisList``. | -+--------------------------+--------------------------+--------------------------+ -| Horizontal-Grid | ``getGrid()`` | Return the associated | -| | | grid, or ``None`` if the | -| | | variable is not gridded. | -+--------------------------+--------------------------+--------------------------+ -| Axis | ``getLatitude()`` | Get the latitude axis, | -| | | or ``None`` if not | -| | | found. | -+--------------------------+--------------------------+--------------------------+ -| Axis | ``getLevel()`` | Get the vertical level | -| | | axis, or ``None`` if not | -| | | found. | -+--------------------------+--------------------------+--------------------------+ -| Axis | ``getLongitude()`` | Get the longitude axis, | -| | | or ``None`` if not | -| | | found. | -+--------------------------+--------------------------+--------------------------+ -| Various | ``getMissing()`` | Get the missing data | -| | | value, or ``None`` if | -| | | not found. | -+--------------------------+--------------------------+--------------------------+ -| String | ``getOrder()`` | Get the order string of | -| | | a spatio-temporal | -| | | variable. The order | -| | | string specifies the | -| | | physical ordering of the | -| | | data. It is a string of | -| | | characters with length | -| | | equal to the rank of the | -| | | variable, indicating the | -| | | order of the variable's | -| | | time, level, latitude, | -| | | and/or longitude axes. | -| | | Each character is one | -| | | of: | -| | | | -| | | - 't': time | -| | | - 'z': vertical level | -| | | - 'y': latitude | -| | | - 'x': longitude | -| | | - '-': the axis is not | -| | | spatio-temporal. | -| | | | -| | | **Example:** | -| | | | -| | | A variable with ordering | -| | | "tzyx" is 4-dimensional, | -| | | where the ordering of | -| | | axes is (time, level, | -| | | latitude, longitude). | -| | | | -| | | **Note:** The order | -| | | string is of the form | -| | | required for the order | -| | | argument of a regridder | -| | | function. | -+--------------------------+--------------------------+--------------------------+ -| List | ``getPaths(*intervals)`` | Get the file paths | -| | | associated with the | -| | | index region specified | -| | | by intervals. | -| | | | -| | | ``intervals`` is a list | -| | | of scalars, 2-tuples | -| | | representing [i,j), | -| | | slices, and/or Ellipses. | -| | | If no ``argument(s)`` | -| | | are present, all file | -| | | paths associated with | -| | | the variable are | -| | | returned. | -| | | | -| | | Returns a list of tuples | -| | | of the form | -| | | (path,slicetuple), where | -| | | path is the path of a | -| | | file, and slicetuple is | -| | | itself a tuple of | -| | | slices, of the same | -| | | length as the rank of | -| | | the variable, | -| | | representing the portion | -| | | of the variable in the | -| | | file corresponding to | -| | | intervals. | -| | | | -| | | **Note:** This function | -| | | is not defined for | -| | | transient variables. | -+--------------------------+--------------------------+--------------------------+ -| Axis | ``getTime()`` | Get the time axis, or | -| | | ``None`` if not found. | -+--------------------------+--------------------------+--------------------------+ -| Integer | ``len(var)`` | The length of the first | -| | | dimension of the | -| | | variable. If the | -| | | variable is | -| | | zero-dimensional | -| | | (scalar), a length of 0 | -| | | is returned. | -| | | | -| | | **Note:** ``size()`` | -| | | returns the total number | -| | | of elements. | -+--------------------------+--------------------------+--------------------------+ -| Transient Variable | ``pressureRegrid (newLev | Return the variable | -| | el, method="log", missin | regridded to a new set | -| | g=None, order=None | of pressure levels | -| | )`` | newLevel. The variable | -| | | must be a function of | -| | | latitude, longitude, | -| | | pressure level, and | -| | | (optionally) time. | -| | | | -| | | ``newLevel`` is an axis | -| | | of the result pressure | -| | | levels. | -| | | | -| | | ``method`` is optional, | -| | | either "log" to | -| | | interpolate in the log | -| | | of pressure (default), | -| | | or "linear" for linear | -| | | interpolation. | -| | | | -| | | ``missing`` is a missing | -| | | data value. The default | -| | | is ``var.getMissing()`` | -| | | | -| | | ``order`` is an order | -| | | string such as "tzyx" or | -| | | "zyx". The default is | -| | | ``var.getOrder()`` | -| | | | -| | | See also: ``regrid``, | -| | | ``crossSectionRegrid``. | -+--------------------------+--------------------------+--------------------------+ -| Integer | ``rank()`` | The number of dimensions | -| | | of the variable. | -+--------------------------+--------------------------+--------------------------+ -| Transient | :: | Return the variable | -| | | regridded to the | -| | regrid (togrid, miss | horizontal grid togrid. | -| | ing=None, order=None, Va | | -| | riable mask=None) | ``missing`` is a Float | -| | | specifying the missing | -| | | data value. The default | -| | | is 1.0e20. | -| | | | -| | | ``order`` is a string | -| | | indicating the order of | -| | | dimensions of the array. | -| | | It has the form returned | -| | | from | -| | | ``variable.getOrder()``. | -| | | For example, the string | -| | | "tzyx" indicates that | -| | | the dimension order of | -| | | array is (time, level, | -| | | latitude, longitude). If | -| | | unspecified, the | -| | | function assumes that | -| | | the last two dimensions | -| | | of array match the input | -| | | grid. | -| | | | -| | | ``mask`` is a Numeric | -| | | array, of datatype | -| | | Integer or Float, | -| | | consisting of ones and | -| | | zeros. A value of 0 or | -| | | 0.0 indicates that the | -| | | corresponding data value | -| | | is to be ignored for | -| | | purposes of regridding. | -| | | If mask is | -| | | two-dimensional of the | -| | | same shape as the input | -| | | grid, it overrides the | -| | | mask of the input grid. | -| | | If the mask has more | -| | | than two dimensions, it | -| | | must have the same shape | -| | | as array. In this case, | -| | | the missing data value | -| | | is also ignored. Such an | -| | | n-dimensional mask is | -| | | useful if the pattern of | -| | | missing data varies with | -| | | level (e.g., ocean data) | -| | | or time. Note: If | -| | | neither missing or mask | -| | | is set, the default mask | -| | | is obtained from the | -| | | mask of the array if | -| | | any. | -| | | | -| | | See also: | -| | | ``crossSectionRegrid``, | -| | | ``pressureRegrid``. | -+--------------------------+--------------------------+--------------------------+ -| ``None`` | ``setAxis(n, axis)`` | Set the n-th axis | -| | | (0-origin index) of to a | -| | | copy of axis. | -+--------------------------+--------------------------+--------------------------+ -| ``None`` | ``setAxisList(axislist)` | Set all axes of the | -| | ` | variable. axislist is a | -| | | list of axis objects. | -+--------------------------+--------------------------+--------------------------+ -| ``None`` | ``setMissing(value)`` | Set the missing value. | -+--------------------------+--------------------------+--------------------------+ -| Integer | ``size()`` | Number of elements of | -| | | the variable. | -+--------------------------+--------------------------+--------------------------+ -| Variable | :: | Read a coordinate region | -| | | of data, returning a | -| | subRegion(*region, t | transient variable. A | -| | ime=None, level=None, la | region is a | -| | titude=None, longitude=N | hyperrectangle in | -| | one, squeeze=0, raw=0) | coordinate space. | -| | | | -| | | ``region`` is an | -| | | argument list, each item | -| | | of which specifies an | -| | | interval of a coordinate | -| | | axis. The intervals are | -| | | listed in the order of | -| | | the variable axes. If | -| | | trailing dimensions are | -| | | omitted, all values of | -| | | those dimensions are | -| | | retrieved. If an axis is | -| | | circular | -| | | (axis.isCircular() is | -| | | true) or cycle is | -| | | specified (see below), | -| | | then data will be read | -| | | with wraparound in that | -| | | dimension. Only one axis | -| | | may be read with | -| | | wraparound. A coordinate | -| | | interval has one of the | -| | | forms listed in Table | -| | | 2.37 on page 102. Also | -| | | see | -| | | ``axis.mapIntervalExt``. | -| | | | -| | | The optional keyword | -| | | arguments ``time``, | -| | | ``level``, ``latitude``, | -| | | and ``longitude`` may | -| | | also be used to specify | -| | | the dimension for which | -| | | the interval applies. | -| | | This is particularly | -| | | useful if the order of | -| | | dimensions is not known | -| | | in advance. An exception | -| | | is raised if a keyword | -| | | argument conflicts with | -| | | a positional region | -| | | argument. | -| | | | -| | | The optional keyword | -| | | argument ``squeeze`` | -| | | determines whether or | -| | | not the shape of the | -| | | returned array contains | -| | | dimensions whose length | -| | | is 1; by default this | -| | | argument is 0, and such | -| | | dimensions are not | -| | | 'squeezed out'. | -| | | | -| | | The optional keyword | -| | | argument ``raw`` | -| | | specifies whether the | -| | | return object is a | -| | | variable or a masked | -| | | array. By default, a | -| | | transient variable is | -| | | returned, having the | -| | | axes and attributes | -| | | corresponding to2,3 the | -| | | region read. If raw=1, | -| | | an MA masked array is | -| | | returned, equivalent to | -| | | the transient variable | -| | | without the axis and | -| | | attribute information. | -+--------------------------+--------------------------+--------------------------+ -| Variable | :: | Read a slice of data, | -| | | returning a transient | -| | subSlice(*specs, tim | variable. This is a | -| | e=None, level=None, lati | functional form of the | -| | tude=None, longitude=Non | slice operator [] with | -| | e, squeeze=0, raw=0) | the squeeze option | -| | | turned off. | -| | | | -| | | ``specs`` is an argument | -| | | list, each element of | -| | | which specifies a slice | -| | | of the corresponding | -| | | dimension. There can be | -| | | zero or more positional | -| | | arguments, each of the | -| | | form: | -| | | | -| | | - a single integer n, | -| | | meaning | -| | | ``slice(n, n+1)`` | -| | | - an instance of the | -| | | slice class | -| | | - a tuple, which will | -| | | be used as arguments | -| | | to create a slice | -| | | - ':', which means a | -| | | slice covering that | -| | | entire dimension | -| | | - Ellipsis (...), which | -| | | means to fill the | -| | | slice list with ':' | -| | | leaving only enough | -| | | room at the end for | -| | | the remaining | -| | | positional arguments | -| | | - a Python slice | -| | | object, of the form | -| | | ``slice(i,j,k)`` | -| | | | -| | | If there are fewer | -| | | slices than | -| | | corresponding | -| | | dimensions, all values | -| | | of the trailing | -| | | dimensions are read. | -| | | | -| | | The keyword arguments | -| | | are defined as in | -| | | subRegion. | -| | | | -| | | There must be no | -| | | conflict between the | -| | | positional arguments and | -| | | the keywords. | -| | | | -| | | In ``(a)-(c)`` and (f), | -| | | negative numbers are | -| | | treated as offsets from | -| | | the end of that | -| | | dimension, as in normal | -| | | Python indexing. | -+--------------------------+--------------------------+--------------------------+ -| String | ``typecode()`` | The Numeric datatype | -| | | identifier. | -+--------------------------+--------------------------+--------------------------+ - -**Example:** Get a region of data. +Table Variable Internal Attributes +---------------------------------- + +.. csv-table:: + :header: "Type", "Name", "Definition" + :widths: 30, 30, 80 + + "Dictionary", "``attributes``", "External attribute dictionary." + "String", "``id``", "Variable identifier." + "String", "``name_in_file``", "The name of the variable in the file or files which represent the dataset. If different from id, the variable is aliased." + "Dataset or CdmsFile", "``parent``", "The dataset or file which contains the variable." + "Tuple", "``shape``", "The length of each axis of the variable" + + +Table Variable Constructors +--------------------------- + +.. csv-table:: + :header: "Constructor", "Description" + :widths: 30, 80 + :align: left + + + "``Dataset.createVariable(String id, String datatype, List axes)``", "Create a Variable in a Dataset. This function is not yet implemented." + "``CdmsFile.createVariable(String id, String datatype, List axes or Grids)``", "Create a Variable in a CdmsFile." + ,"``id`` is the name of the variable. ``datatype`` is the MV2 or Numpy | typecode, for example, MV2.Float. ``axesOrGrids`` is a list of Axis and/or Grid objects, on which the variable is defined. Specifying a rectilinear grid is equivalent to listing the grid latitude and longitude axes, in the order defined for the grid. \*\*Note:\*\* this argument can either be a list or a tuple. If the tuple form is used, and there is only one element, it must have a following comma, e.g.: ``(axisobj,)``." + "``cdms.createVariable(array, typecode=None, copy=0, savespace=0,mask=None, fill_value=None, grid=None, axes=None,attributes=None, id=None)``", "Create a transient variable, not associated with a file or dataset. ``array`` is the data values: a Variable, masked array, or Numpy array. ``typecode`` is the MV2 typecode of the array. Defaults to the typecode of array. ``copy`` is an integer flag: if 1, the variable is created with a copy of the array, if 0 the variable data is shared with array. ``savespace`` is an integer flag: if set to 1, internal Numpy operations will attempt to avoid silent upcasting. ``mask`` is an array of integers with value 0 or 1, having the same shape as array. array elements with a corresponding mask value of 1 are considered invalid, and are not used for subsequent Numpy operations. The default mask is obtained from array if present, otherwise is None. ``fill_value`` is the missing value flag. The default is obtained from array if possible, otherwise is set to 1.0e20 for floating point variables, 0 for integer-valued variables. ``grid`` is a rectilinear grid object. ``axes`` is a tuple of axis objects. By default the axes are obtained from array if present. Otherwise for a dimension of length n, the default axis has values [0., 1., ..., double(n)]. ``attributes`` is a dictionary of attribute values. The dictionary keys must be strings. By default the dictionary is obtained from array if present, otherwise is empty. ``id`` is the string identifier of the variable. By default the id is obtained from array if possible, otherwise is set to 'variable\_n' for some integer." + + + +Table Variable Methods +---------------------- + +.. csv-table:: + :header: "Type", "Method", "Definition" + :widths: 30, 30, 180 + :align: left + + + "Variable", "``tvar = var[ i:j, m:n]``", "Read a slice of data from the file or dataset, resulting in a transient variable. Singleton dimensions are 'squeezed' out. Data is returned in the physical ordering defined in the dataset. The forms of the slice operator are listed in `Variable Slice Operators <#table-variable-slice-operators>`_ " + "None", "``var[ i:j, m:n] = array``", "Write a slice of data to the external dataset. The forms of the slice operator are listed in `Result Entry Methods <#table-resultentry-methods>`_ . (Variables in CdmsFiles only)" + "Variable", "``tvar = var(selector)``", "Calling a variable as a function reads the region of data defined by the selector. The result is a transient variable, unless raw=1 keyword is specified. See 'Selectors'." + "None", "``assignValue(Array ar)``", "Write the entire data array. Equivalent to ``var[:] = ar``. (Variables in CdmsFiles only)." + "Variable", "``astype(typecode)``", "Cast the variable to a new datatype. Typecodes are as for MV, MV2, and Numpy modules." + "Variable", "``clone(copyData=1)``", "Return a copy of a transient variable." + ,,"If copyData is 1 (the default) the variable data is copied as well. If copyData is 0, the result transient variable shares the original transient variables data array." + "Transient Variable", "``crossSectionRegrid(newLevel, newLatitude, method='log', missing=None, order=None)``", "Return a lat/level vertical cross-section regridded to a new set of latitudes newLatitude and levels newLevel. The variable should be a function of latitude, level, and (optionally) time." + ,,"* ``newLevel`` is an axis of the result pressure levels." + ,,"* ``newLatitude`` is an axis of the result latitudes." + ,,"* ``method`` is optional, either 'log' to interpolate in the log of pressure (default), or 'linear' for linear interpolation." + ,,"* ``missing`` is a missing data value. The default is ``var.getMissing()``" + ,,"* ``order`` is an order string such as 'tzy' or 'zy'. The default is ``var.getOrder()``." + ,,"*See also:* ``regrid``, ``pressureRegrid``." + "Axis", "``getAxis(n)``", "Get the n-th axis." + ,,"``n`` is an integer." + "List", "``getAxisIds()``", "Get a list of axis identifiers." + "Integer", "``getAxisIndex(axis_spec)``", "Return the index of the axis specificed by axis\_spec. Return -1 if no match." + ,,"``axis_spec`` is a specification as defined for getAxisList" + "List", "``getAxisList(axes=None, omit=None, order=None)``", "Get an ordered list of axis objects in the domain of the variable." + ,,"If ``axes`` is not ``None``, include only certain axes. Otherwise axes is a list of specifications as described below. Axes are returned in the order specified unless the order keyword is given." + ,,"If ``omit`` is not ``None``, omit those specified by an integer dimension number. Otherwise omit is a list of specifications as described below." + ,,"``order`` is an optional string determining the output order." + ,,"Specifications for the axes or omit keywords are a list, each element having one of the following forms:" + ,,"* an integer dimension index, starting at 0." + ,,"* a string representing an axis id or one of the strings 'time', 'latitude', 'lat', 'longitude', 'lon', 'lev' or 'level'." + ,,"* a function that takes an axis as an argument and returns a value. If the value returned is true, the axis matches." + ,,"* an axis object; will match if it is the same object as axis." + ,,"``order`` can be a string containing the characters t,x,y,z, or * ." + ,,"If a dash ('-') is given, any elements of the result not chosen otherwise are filled in from left to right with remaining candidates." + "List", "``getAxisListIndex(axes=None, omit=None, order=None)``", "Return a list of indices of axis objects. Arguments are as for getAxisList." + "List", "``getDomain()``", "Get the domain. Each element of the list is itself a tuple of the form ``(axis,start,length,tru e_length)`` where axis is an axis object, start is the start index of the domain relative to the axis object, length is the length of the axis, and true\_length is the actual number of (defined) points in the domain. *See also:* ``getAxisList``." + "Horizontal-Grid", "``getGrid()``", "Return the associated grid, or ``None`` if the variable is not gridded." + "Axis", "``getLatitude()``", "Get the latitude axis, or ``None`` if not found." + "Axis", "``getLevel()``", "Get the vertical level axis, or ``None`` if not found." + "Axis", "``getLongitude()``", "Get the longitude axis, or ``None`` if not found." + "Various", "``getMissing()``", "Get the missing data value, or ``None`` if not found." + ,, "String ``getOrder()`` Get the order string of a spatio-temporal variable. The order string specifies the physical ordering of the data. It is a string of characters with length equal to the rank of the variable, indicating the order of the variable's time, level, latitude, and/or longitude axes. Each character is one of:" + ,, "* 't': time" + ,, "* 'z': vertical level" + ,, "* 'y': latitude" + ,, "* 'x': longitude" + ,, "* '-': the axis is not spatio-temporal." + ,, "**Example:**" + ,, "A variable with ordering 'tzyx' is 4-dimensional, where the ordering of axes is (time, level, latitude, longitude)." + ,, "**Note:** The order string is of the form required for the order argument of a regridder function." + ,,"``intervals`` is a list of scalars, 2-tuples representing [i,j), slices, and/or Ellipses. If no ``argument(s)`` are present, all file paths associated with the variable are returned." + ,," Returns a list of tuples of the form (path,slicetuple), where path is the path of a file, and slicetuple is itself a tuple of slices, of the same length as the rank of the variable, representing the portion of the variable in the file corresponding to intervals." + ,, "**Note:** This function is not defined for transient variables." + "Axis", "``getTime()``", "Get the time axis, or ``None`` if not found." + "List", "``getPaths(*intervals)``", "Get the file paths associated with the index region specified by intervals." + "Integer", "``len(var)``", "The length of the first dimension of the variable. If the variable is zero-dimensional (scalar), a length of 0 is returned." + ,,"**Note:** ``size()`` returns the total number of elements." + "Transient Variable", "``pressureRegrid (newLevel, method='log', missin=None, order=None)``", "Return the variable regridded to a new set of pressure levels newLevel. The variable must be a function of latitude, longitude, pressure level, and (optionally) time." + ,, "``newLevel`` is an axis of the result pressure levels." + ,, "``method`` is optional, either 'log' to interpolate in the log of pressure (default), or 'linear' for linear interpolation." + ,, "``missing`` is a missing data value. The default is ``var.getMissing()``" + ,, "``order`` is an order string such as 'tzyx' or 'zyx'. The default is ``var.getOrder()``" + ,, "See also: ``regrid``, ``crossSectionRegrid``." + "Integer", "``rank()``", "The number of dimensions of the variable." + "Transient", "``regrid (togrid, missing=None, order=None, Variable mask=None)``","Return the variable regridded to the horizontal grid togrid." + ,, "``missing`` is a Float specifying the missing data value. The default is 1.0e20." + ,, "``order`` is a string indicating the order of dimensions of the array. It has the form returned from ``variable.getOrder()``. For example, the string 'tzyx' indicates that the dimension order of array is (time, level, latitude, longitude). If unspecified, the function assumes that the last two dimensions of array match the input grid." + ,, "``mask`` is a Numpy array, of datatype Integer or Float, consisting of ones and zeros. A value of 0 or 0.0 indicates that the corresponding data value is to be ignored for purposes of regridding. If mask is two-dimensional of the same shape as the input grid, it overrides the mask of the input grid. If the mask has more than two dimensions, it must have the same shape as array. In this case, the missing data value is also ignored. Such an n-dimensional mask is useful if the pattern of missing data varies with level (e.g., ocean data) or time. Note: If neither missing or mask is set, the default mask is obtained from the mask of the array if any." + ,, "See also: ``crossSectionRegrid``, ``pressureRegrid``." + "``None``", "``setAxis(n, axis)``", "Set the n-th axis (0-origin index) of to a copy of axis." + "``None``", "``setAxisList(axislist)``", "Set all axes of the variable. axislist is a list of axis objects." + "``None``", "``setMissing(value)``", "Set the missing value. Integer ``size()`` Number of elements of the variable." + "Variable", "``subRegion(* region, time=None, level=None, latitude=None, longitude=None, squeeze=0, raw=0)``", "Read a coordinate region of data, returning a transient variable. A region is a hyperrectangle in coordinate space." + ,,"``region`` is an argument list, each item of which specifies an interval of a coordinate axis. The intervals are listed in the order of the variable axes. If trailing dimensions are omitted, all values of those dimensions are retrieved. If an axis is circular (axis.isCircular() is true) or cycle is specified (see below), then data will be read with wraparound in that dimension. Only one axis may be read with wraparound. A coordinate interval has one of the forms listed in `Index and Coordinate Intervals <#table-index-and-coordinate-intervals>`_ . Also see ``axis.mapIntervalExt``." + ,,"The optional keyword arguments ``time``, ``level``, ``latitude``, and ``longitude`` may also be used to specify the dimension for which the interval applies. This is particularly useful if the order of dimensions is not known in advance. An exception is raised if a keyword argument conflicts with a positional region argument." + ,,"The optional keyword argument ``squeeze`` determines whether or not the shape of the returned array contains dimensions whose length is 1; by default this argument is 0, and such dimensions are not 'squeezed out'." + ,,"The optional keyword argument ``raw`` specifies whether the return object is a variable or a masked array. By default, a transient variable is returned, having the axes and attributes corresponding to2,3 the region read. If raw=1, an MV2 masked array is returned, equivalent to the transient variable without the axis and attribute information." + "Variable", "``subSlice(* specs, time=None, level=None, latitude=None, longitude=None, squeeze=0, raw=0)``", "Read a slice of data, returning a transient variable. This is a functional form of the slice operator [] with the squeeze option turned off." + ,,"``specs`` is an argument list, each element of which specifies a slice of the corresponding dimension. There can be zero or more positional arguments, each of the form:" + ,,"* a single integer n, meaning ``slice(n, n+1)``" + ,,"* an instance of the slice class" + ,,"* a tuple, which will be used as arguments to create a slice" + ,,"* ':', which means a slice covering that entire dimension" + ,,"* Ellipsis (...), which means to fill the slice list with ':' leaving only enough room at the end for the remaining positional arguments" + ,,"* a Python slice object, of the form ``slice(i,j,k)``" + ,,"If there are fewer slices than corresponding dimensions, all values of the trailing dimensions are read." + ,,"The keyword arguments are defined as in subRegion." + ,,"There must be no conflict between the positional arguments and the keywords." + ,,"In ``(a)-(c)`` and (f), negative numbers are treated as offsets from the end of that dimension, as in normal Python indexing." + ,,"String ``typecode()`` The Numpy datatype identifier." + +Example Get a Region of Data. +----------------------------- Variable ta is a function of (time, latitude, longitude). Read data corresponding to all times, latitudes -45.0 up to but not including+45.0, longitudes 0.0 through and including longitude 180.0: -.. raw:: html - -
- :: data = ta.subRegion(':', (-45.0,45.0,'co'), (0.0, 180.0)) -.. raw:: html - -
- or equivalently: -.. raw:: html - -
- :: data = ta.subRegion(latitude=(-45.0,45.0,'co'), longitude=(0.0, 180.0) -.. raw:: html +Read all data for March, 1980: -
+:: -Read all data for March, 1980: + data = ta.subRegion(time=('1980-3','1980-4','co')) -.. raw:: html -
-:: +Table Variable Slice Operators +------------------------------ - data = ta.subRegion(time=('1980-3','1980-4','co')) +.. csv-table:: + :header: "Operator", "Description" + :widths: 30, 80 -.. raw:: html - -
- - - -Table 2.36 Variable Slice Operators - -+-------------------+---------------------------------------------------------------+ -| Operator | Description | -+===================+===============================================================+ -| ``[i]`` | The ith element, zero-origin indexing. | -+-------------------+---------------------------------------------------------------+ -| ``[i:j]`` | The ith element through, but not including, element j | -+-------------------+---------------------------------------------------------------+ -| ``[i:]`` | The ith element through the end | -+-------------------+---------------------------------------------------------------+ -| ``[:j]`` | The beginning element through, but not including, element j | -+-------------------+---------------------------------------------------------------+ -| ``[:]`` | The entire array | -+-------------------+---------------------------------------------------------------+ -| ``[i:j:k]`` | Every kth element | -+-------------------+---------------------------------------------------------------+ -| ``[i:j, m:n]`` | Multidimensional slice | -+-------------------+---------------------------------------------------------------+ -| ``[i, ..., m]`` | (Ellipsis) All dimensions between those specified. | -+-------------------+---------------------------------------------------------------+ -| ``[-1]`` | Negative indices ‘wrap around’. -1 is the last element | -+-------------------+---------------------------------------------------------------+ - - - -Table 2.37 Index and Coordinate Intervals - -+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------+ -| Interval Definition | Example Interval Definition | Example | -+========================+===========================================================================================================================================================================================================================================================================================================+=======================================================+ -| ``x`` | single point, such that axis[i]==x In general x is a scalar. If the axis is a time axis, x may also be a cdtime relative time type, component time type, or string of the form ‘yyyy-mm-dd hh:mi:ss’ (where trailing fields of the string may be omitted. | ``180.0`` | -| | | ``cdtime.reltime(48,"hour s since 1980-1")`` | -| | | ``'1980-1-3'`` | -+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------+ -| ``(x,y)`` | indices i such that x ≤ axis[i] ≤ y | ``(-180,180)`` | -+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------+ -| ``(x,y,'co')`` | ``x ≤ axis[i] < y``. The third item is defined as in mapInterval. | ``(-90,90,'cc')`` | -+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------+ -| ``(x,y,'co',cycle)`` | ``x ≤ axis[i]< y``, with wraparound | ``( 180, 180, 'co', 360.0)`` | -| | **Note:** It is not necesary to specify the cycle of a circular longitude axis, that is, for which ``axis.isCircular()`` is true. | | -+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------+ -| ``slice(i,j,k)`` | slice object, equivalent to i:j:k in a slice operator. Refers to the indices i, i+k, i+2k, … up to but not including index j. If i is not specified or is None it defaults to 0. If j is not specified or is None it defaults to the length of the axis. The stride k defaults to 1. k may be negative. | ``slice(1,10)`` | -| | | ``slice(,,-1)`` reverses the direction of the axis. | -+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------+ -| ``':'`` | all axis values of one dimension |   | -+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------+ -| ``Ellipsis`` | all values of all intermediate axes |   | -+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------+ - - - -2.11.1 Selectors + "``[i]``", "The ith element, zero-origin indexing." + "``[i:j]``", "The ith element through, but not including, element j" + "``[i:]``", "The ith element through the end" + "``[:j]``", "The beginning element through, but not including, element j" + "``[:]``", "The entire array" + "``[i:j:k]``", "Every kth element" + "``[i:j, m:n]``", "Multidimensional slice" + "``[i, ..., m]``", "(Ellipsis) All dimensions between those specified." + "``[-1]``", "Negative indices ‘wrap around’. -1 is the last element" -A selector is a specification of a region of data to be selected from a -variable. For example, the statement -.. raw:: html -
+Table Index and Coordinate Intervals +------------------------------------ + +.. csv-table:: + :header: "Interval Definition", "Example Interval Definition", "Example" + :widths: 30, 80, 80 + + "``x``", "single point, such that axis[i]==x In general x is a scalar. If the axis is a time axis, x may also be a cdtime relative time type, component time type, or string of the form ‘yyyy-mm-dd hh:mi:ss’ (where trailing fields of the string may be omitted.", "``180.0``" + ,,"``cdtime.reltime(48,'hour s since 1980-1')``" + ,,"``'1980-1-3'``" + "``(x,y)``", "indices i such that x ≤ axis[i] ≤ y", "``(-180,180)``" + "``(x,y,'co')``", "``x ≤ axis[i] < y``. The third item is defined as in mapInterval.", "``(-90,90,'cc')``" + "``(x,y,'co',cycle)``", "``x ≤ axis[i]< y``, with wraparound", "``( 180, 180, 'co', 360.0)``" + "","**Note:** It is not necesary to specify the cycle of a circular longitude axis, that is, for which ``axis.isCircular()`` is true.", + "``slice(i,j,k)``", " slice object, equivalent to i:j:k in a slice operator. Refers to the indices i, i+k, i+2k, … up to but not including index j. If i is not specified or is None it defaults to 0. If j is not specified or is None it defaults to the length of the axis. The stride k defaults to 1. k may be negative.","``slice(1,10)``" + ,,"``slice(,,-1)`` reverses the direction of the axis." + "``':'``", "all axis values of one dimension", + "``Ellipsis``", "all values of all intermediate axes", + + + +Selectors +^^^^^^^^^ + +A selector is a specification of a region of data to be selected from a +variable. For example, the statement: :: x = v(time='1979-1-1', level=(1000.0,100.0)) -.. raw:: html - -
means ‘select the values of variable v for time ‘1979-1-1’ and levels 1000.0 to 100.0 inclusive, setting x to the result.’ Selectors are generally used to represent regions of space and time. -The form for using a selector is - -.. raw:: html +The form for using a selector is: -
:: result = v(s) -.. raw:: html - -
- -where v is a variable and s is the selector. An equivalent form is - -.. raw:: html -
+where v is a variable and s is the selector. An equivalent form is: :: result = f('varid', s) -.. raw:: html - -
where f is a file or dataset, and ‘varid’ is the string ID of a variable. A selector consists of a list of selector components. For example, the -selector - -.. raw:: html +selector: -
:: time='1979-1-1', level=(1000.0,100.0) -.. raw:: html - -
has two components: time=’1979-1-1’, and level=(1000.0,100.0). This illustrates that selector components can be defined with keywords, using the form: -.. raw:: html - -
:: keyword=value -.. raw:: html - -
Note that for the keywords time, level, latitude, and longitude, the selector can be used with any variable. If the corresponding axis is not found, the selector component is ignored. This is very useful for writing general purpose scripts. The required keyword overrides this behavior. These keywords take values that are coordinate ranges or index -ranges as defined in Table 2.37 on page 102. +ranges as defined in See `Index and Coordinate Intervals <#table-index-and-coordinate-intervals>`_. The following keywords are available: Another form of selector components is the positional form, where the component order corresponds to the axis order of a variable. For example: +Table Selector Keywords +----------------------- -Table 2.38 Selector keywords - -+-----------------+----------------------------------------------------------------------+----------------------------------------------------------------------------+ -| Keyword | Description | Value | -+=================+======================================================================+============================================================================+ -| ``axisid`` | Restrict the axis with ID axisid to a value or range of values. | See Table 2.37 on page 102 | -+-----------------+----------------------------------------------------------------------+----------------------------------------------------------------------------+ -| ``grid`` | Regrid the result to the grid. | Grid object | -+-----------------+----------------------------------------------------------------------+----------------------------------------------------------------------------+ -| ``latitude`` | Restrict latitude values to a value or range. Short form: lat | See Table 2.37 on page 102 | -+-----------------+----------------------------------------------------------------------+----------------------------------------------------------------------------+ -| ``level`` | Restrict vertical levels to a value or range. Short form: lev | See Table 2.37 on page 102 | -+-----------------+----------------------------------------------------------------------+----------------------------------------------------------------------------+ -| ``longitude`` | Restrict longitude values to a value or range. Short form: lon | See Table 2.37 on page 102 | -+-----------------+----------------------------------------------------------------------+----------------------------------------------------------------------------+ -| ``order`` | Reorder the result. | Order string, e.g., “tzyx” | -+-----------------+----------------------------------------------------------------------+----------------------------------------------------------------------------+ -| ``raw`` | Return a masked array (MA.array) rather than a transient variable. | 0: return a transient variable (default); =1: return a masked array. | -+-----------------+----------------------------------------------------------------------+----------------------------------------------------------------------------+ -| ``required`` | Require that the axis IDs be present. | List of axis identifiers. | -+-----------------+----------------------------------------------------------------------+----------------------------------------------------------------------------+ -| ``squeeze`` | Remove singleton dimensions from the result. | 0: leave singleton dimensions (default); 1: remove singleton dimensions. | -+-----------------+----------------------------------------------------------------------+----------------------------------------------------------------------------+ -| ``time`` | Restrict time values to a value or range. | See Table 2.37 on page 10 | -+-----------------+----------------------------------------------------------------------+----------------------------------------------------------------------------+ +.. csv-table:: + :header: "Keyword", "Description", "Value" + :widths: 30, 80, 80 + + "``axisid``", "Restrict the axis with ID axisid to a value or range of values.", See `Index and Coordinate Intervals <#table-index-and-coordinate-intervals>`_ + "``grid``", "Regrid the result to the grid.", " Grid object" + "``latitude``", "Restrict latitude values to a value or range. Short form: lat", See `Index and Coordinate Intervals <#table-index-and-coordinate-intervals>`_ + "``level``", "Restrict vertical levels to a value or range. Short form: lev",See `Index and Coordinate Intervals <#table-index-and-coordinate-intervals>`_ + "``longitude``", "Restrict longitude values to a value or range. Short form: lon", See `Index and Coordinate Intervals <#table-index-and-coordinate-intervals>`_ + "``order``", "Reorder the result.", " Order string, e.g., 'tzyx'" + "``raw``", "Return a masked array (MV2.array) rather than a transient variable.", "0: return a transient variable (default); =1: return a masked array." + "``required``", "Require that the axis IDs be present.", " List of axis identifiers." + "``squeeze``", "Remove singleton dimensions from the result.", " 0: leave singleton dimensions (default); 1: remove singleton dimensions." + "``time``", "Restrict time values to a value or range.", See `Index and Coordinate Intervals <#table-index-and-coordinate-intervals>`_ Another form of selector components is the positional form, where the component order corresponds to the axis order of a variable. For example: -.. raw:: html - -
:: x9 = hus(('1979-1-1','1979-2-1'),1000.0) -.. raw:: html - -
reads data for the range (‘1979-1-1’,’1979-2-1’) of the first axis, and coordinate value 1000.0 of the second axis. Non-keyword arguments of the -form(s) listed in Table 2.37 on page 102 are treated as positional. Such +form(s) listed in `Index and Coordinate Intervals <#table-index-and-coordinate-intervals>`_ are treated as positional. Such selectors are more concise, but not as general or flexible as the other types described in this section. @@ -3398,9 +1616,6 @@ be defined and reused, independent of a particular variable. Selectors are constructed using the cdms.selectors.Selector class. The constructor takes an argument list of selector components. For example: -.. raw:: html - -
:: @@ -3409,64 +1624,40 @@ takes an argument list of selector components. For example: x1 = v1(sel) x2 = v2(sel) -.. raw:: html - -
For convenience CDMS provides several predefined selectors, which can be used directly or can be combined into more complex selectors. The selectors time, level, latitude, longitude, and required are equivalent to their keyword counterparts. For example: -.. raw:: html - -
:: from cdms import time, level x = hus(time('1979-1-1','1979-2-1'), level(1000.)) -.. raw:: html - -
and -.. raw:: html - -
:: x = hus(time=('1979-1-1','1979-2-1'), level=1000.) -.. raw:: html - -
are equivalent. Additionally, the predefined selectors ``latitudeslice``, ``longitudeslice``, ``levelslice``, and ``timeslice`` take arguments ``(startindex, stopindex[, stride])``: -.. raw:: html - -
:: from cdms import timeslice, levelslice x = v(timeslice(0,2), levelslice(16,17)) -.. raw:: html - -
Finally, a collection of selectors is defined in module cdutil.region: -.. raw:: html - -
:: @@ -3477,17 +1668,10 @@ Finally, a collection of selectors is defined in module cdutil.region: NPZ=AZ=ArcticZone=domain(latitude=(66.6,90.)) SPZ=AAZ=AntarcticZone=domain(latitude=(-90.,-66.6)) -.. raw:: html - -
Selectors can be combined using the & operator, or by refining them in the call: -.. raw:: html - -
- :: from cdms.selectors import Selector @@ -3497,13 +1681,10 @@ the call: x1 = hus(sel3) x2 = hus(sel2, level=1000.0) -.. raw:: html -
- - -2.11.2 Selector examples +Selector Examples +----------------- CDMS provides a variety of ways to select or slice data. In the following examples, variable hus is contained in file sample.nc, and is @@ -3513,10 +1694,6 @@ monthly starting at 1979-1-1. There are 17 levels, the last level being select the first two times and the last level. The last two examples remove the singleton level dimension from the result array. -.. raw:: html - -
- :: import cdms @@ -3564,18 +1741,13 @@ remove the singleton level dimension from the result array. f.close() -.. raw:: html - -
+Examples +^^^^^^^^ -2.12 Examples -^^^^^^^^^^^^^ - - -2.12.1 Example 1 -^^^^^^^^^^^^^^^^ +Example 1 +--------- In this example, two datasets are opened, containing surface air temperature (‘tas’) and upper-air temperature (‘ta’) respectively. @@ -3590,10 +1762,6 @@ three quantities are calculated: slope, variance, and correlation. The results are written to a netCDF file. For brevity, the functions ``corrCoefSlope`` and ``removeSeasonalCycle`` are omitted. -.. raw:: html - -
- :: 1. import cdms @@ -3651,9 +1819,6 @@ results are written to a netCDF file. For brevity, the functions # Process Jan80 through Dec81 ccSlopeVarianceBySeasonFiltNet(pathTa,pathTas,'80-1','81-12') -.. raw:: html - -
**Notes:** @@ -3675,17 +1840,14 @@ results are written to a netCDF file. For brevity, the functions -2.12.2 Example 2 -^^^^^^^^^^^^^^^^ +Example 2 +--------- In the next example, the pointwise variance of a variable over time is calculated, for all times in a dataset. The name of the dataset and variable are entered, then the variance is calculated and plotted via the vcs module. -.. raw:: html - -
:: @@ -3766,16 +1928,9 @@ the vcs module. pause() w.clear() -.. raw:: html - -
The result of running this script is as follows: -.. raw:: html - -
- :: % calcVar.py @@ -3799,9 +1954,6 @@ The result of running this script is as follows: -.. raw:: html - -
**Notes:** diff --git a/docs/source/manual/cdms_3.rst b/docs/source/manual/cdms_3.rst index 18a9b365..8c2f973d 100644 --- a/docs/source/manual/cdms_3.rst +++ b/docs/source/manual/cdms_3.rst @@ -1,8 +1,11 @@ -CHAPTER 3 cdtime Module ------------------------ +Module: CdTime +-------------- + +Time Types +^^^^^^^^^^ +.. highlight:: python + :linenothreshold: 3 -3.1 Time types -^^^^^^^^^^^^^^ .. testsetup:: * import requests @@ -21,7 +24,7 @@ CHAPTER 3 cdtime Module The ``cdtime`` module implements the CDMS time types, methods, and -calendars. These are made available with the command +calendars. These are made available with the command: .. doctest:: @@ -44,8 +47,8 @@ The ``cdtime`` module contains functions for converting between these forms, based on the common calendars used in climate simulation. Basic arithmetic and comparison operators are also available. -3.2 Calendars -^^^^^^^^^^^^^ +Calendars +^^^^^^^^^ A calendar specifies the number of days in each month, for a given year. cdtime supports these calendars: @@ -70,15 +73,18 @@ changed with the command: ``cdtime.DefaultCalendar = newCalendar`` -3.3 Time Constructors -^^^^^^^^^^^^^^^^^^^^^ +Time Constructors +^^^^^^^^^^^^^^^^^ The following table describes the methods for creating time types. + +Table Time Constructors +~~~~~~~~~~~~~~~~~~~~~~~ - -.. csv-table:: Time Constructors +.. csv-table:: :header: "Type", "Constructor", "Defintion" :widths: 10, 40, 80 + :align: left "Reltime", "``cdtime.reltime(value, relunits)``", "Create a relative time type." ,, "``value`` is an integer or floating point value." @@ -94,12 +100,12 @@ The following table describes the methods for creating time types. ,,"``second`` is a floating point number in the range 0.0 ,, 60.0. **Example:** ``c = cdtime.comptime(1996, 2, 28)``" -3.4 Relative Time -^^^^^^^^^^^^^^^^^ +Relative Time +^^^^^^^^^^^^^ A relative time type has two members, value and units. Both can be set. -Table 3.2 Relative Time Members +Table Relative Time Members ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+---------+-------------------------------------------------------+ @@ -110,12 +116,14 @@ Table 3.2 Relative Time Members | String | units | Relative units, of the form “unit(s) since basetime | +----------+---------+-------------------------------------------------------+ -3.5 Component Time -^^^^^^^^^^^^^^^^^^ +Component Time +^^^^^^^^^^^^^^ A component time type has six members, all of which are settable. -.. csv-table:: Table 3.3 Component Time +Table Component Time +~~~~~~~~~~~~~~~~~~~~ +.. csv-table:: :header: "Type", "Name", "Summary" :widths: 15, 15, 50 @@ -126,23 +134,26 @@ A component time type has six members, all of which are settable. "Integer", "minute", "Minute, in the range 0 .. 59" "Float", "second", "Seconds, in the range 0.0 .. 60.0" -3.6 Time Methods -^^^^^^^^^^^^^^^^ +Time Methods +^^^^^^^^^^^^ The following methods apply both to relative and component times. -.. csv-table:: Table 3.4 Time Methods +Table Time Methods +~~~~~~~~~~~~~~~~~~ +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 20, 75, 80 + :align: left - "Comptime or Reltime", "``t.add(value, intervalUnits, calendar=cdtime.Default-Calendar)``", "Add an interval of time to a time type t. Returns the same type of time." + "Comptime or Reltime", "``t.add(value,intervalUnits, calendar=cdtime.Default-Calendar)``", "Add an interval of time to a time type t. Returns the same type of time." ,, "``value`` is the Float number of interval units." ,, "``intervalUnits`` is ``cdtime.[Second (s) | Minute(s) Hour(s) | Day(s) | Week(s) | Month(s) | Season(s) | Year(s) ]``" ,, "``calendar`` is the calendar type." "Integer", "``t.cmp(t2, calendar=cdtime.DefaultCalendar)``", "Compare time values t and t2. Returns -1, 0, 1 as t is less than, equal to, or greater than t2 respectively." ,, "``t2`` is the time to compare." ,, "``calendar`` is the calendar type." - "Comptime or Reltime", "``t.sub(value, intervalUnits, calendar=cdtime.DefaultCalendar)``", "Subtract an interval of time from a time type t. Returns the same type of time." + "Comptime or Reltime", "``t.sub(value,intervalUnits, calendar=cdtime.DefaultCalendar)``", "Subtract an interval of time from a time type t. Returns the same type of time." ,, "``value`` is the Float number of interval units." ,, "``intervalUnits`` is cdtime.[Second (s) | Minute(s) | Hour(s) | Day(s) | Week(s) | Month(s) | Season(s) | Year(s)]" ,, "``calendar`` is the calendar type. " @@ -151,8 +162,8 @@ The following methods apply both to relative and component times. "Reltime", "``t.torel(units, calendar=cdtime.DefaultCalendar)``", "Convert to relative time. Returns the equivalent relative time." -3.7 Examples -^^^^^^^^^^^^ +Examples +^^^^^^^^ .. doctest:: >>> from cdtime import * diff --git a/docs/source/manual/cdms_4.rst b/docs/source/manual/cdms_4.rst index 011d345a..62655945 100644 --- a/docs/source/manual/cdms_4.rst +++ b/docs/source/manual/cdms_4.rst @@ -1,8 +1,9 @@ -CHAPTER 4 Regridding Data -------------------------- +Regridding Data +--------------- -4.1 Overview -^^^^^^^^^^^^ + +Overview +^^^^^^^^ CDMS provides several methods for interpolating gridded data: @@ -12,14 +13,17 @@ CDMS provides several methods for interpolating gridded data: - from one vertical (lat/level) cross-section to another vertical cross-section. -4.1.1 CDMS horizontal regridr -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +CDMS Horizontal Regrider +^^^^^^^^^^^^^^^^^^^^^^^^ +.. highlight:: python + :linenothreshold: 3 + .. testsetup:: * import requests fnames = [ 'clt.nc', 'geos-sample', 'xieArkin-T42.nc', 'remap_grid_POP43.nc', 'remap_grid_T42.nc', 'rmp_POP43_to_T42_conserv.n', 'rmp_T42_to_POP43_conserv.nc', 'ta_ncep_87-6-88-4.nc', 'rmp_T42_to_C02562_conserv.nc' ] for file in fnames: - url = 'http://uvcdat.llnl.gov/cdat/sample_data/'+file + url = 'http://cdat.llnl.gov/cdat/sample_data/'+file r = requests.get(url) open(file, 'wb').write(r.content) @@ -37,8 +41,8 @@ variable regridded to the target grid: .. doctest:: - >>> # wget "http://uvcdat.llnl.gov/cdat/sample_data/clt.nc" - >>> # wget "http://uvcdat.llnl.gov/cdat/sample_data/geos5-sample.nc" + >>> # wget "http://cdat.llnl.gov/cdat/sample_data/clt.nc" + >>> # wget "http://cdat.llnl.gov/cdat/sample_data/geos5-sample.nc" >>> import cdms2 >>> import cdat_info >>> f1=cdms2.open("clt.nc") @@ -58,10 +62,10 @@ variable regridded to the target grid: A somewhat more efficient method is to create a regridder function. This has the advantage that the mapping is created only once and can be used for multiple arrays. Also, this method can be used with data in the form -of an MA.MaskedArray. The steps in this process are: +of an MV2.MaskedArray. The steps in this process are: #. Given an input grid and output grid, generate a regridder function. -#. Call the regridder function on a Numeric array, resulting in an array +#. Call the regridder function on a Numpy array, resulting in an array defined on the output grid. The regridder function can be called with any array or variable defined on the input grid. @@ -70,8 +74,8 @@ is generated at line 9, and the regridding is performed at line 10: .. doctest:: - >>> # wget "http://uvcdat.llnl.gov/cdat/sample_data/clt.nc" - >>> # wget "http://uvcdat.llnl.gov/cdat/sample_data/geos5-sample.nc" + >>> # wget "http://cdat.llnl.gov/cdat/sample_data/clt.nc" + >>> # wget "http://cdat.llnl.gov/cdat/sample_data/geos5-sample.nc" >>> import cdms2 >>> from regrid2 import Regridder >>> f = cdms2.open("clt.nc") @@ -107,8 +111,8 @@ Notes **Line #11** Reads all data for variable cltf, and calls the regridder function on that data, resulting in a transient variable cltnew. -4.1.2 SCRIP horizontal regridder -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +SCRIP Horizontal Regridder +^^^^^^^^^^^^^^^^^^^^^^^^^^ To interpolate between grids where one or both grids is non-rectangular, CDMS provides an interface to the SCRIP regridder package developed at @@ -135,7 +139,7 @@ Figure 3 illustrates the process: additional arguments for the gradients of the variable. -FIGURE 3. Regridding data with SCRIP +Regridding Data with SCRIP ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Example:** @@ -145,14 +149,11 @@ conservative interpolator. In this example: -- The input grid is defined in remap\_grid\_T42.nc. -- The output grid is defined in remap\_grid\_POP43.nc. -- The input data is variable src\_array in file sampleT42Grid.nc. -- The file scrip\_in has contents: - -.. raw:: html +- The input grid is defined in remap_grid_T42.nc. +- The output grid is defined in remap_grid_POP43.nc. +- The input data is variable src_array in file sampleT42Grid.nc. +- The file scrip_in has contents: -
:: @@ -173,9 +174,6 @@ In this example: luse_grid1_area = .false. luse_grid2_area = .false. -.. raw:: html - -
``num_maps`` specifies the number of mappings generated, either 1 or 2. For a single mapping, ``grid1_file`` and ``grid2_file`` are the source @@ -187,9 +185,6 @@ in the SCRIP documentation. Once the grids and input file are defined, run the scrip executable to generate the remapping file ‘rmp\_T42\_to\_POP43\_conserv.nc’ -.. raw:: html - -
:: @@ -203,19 +198,16 @@ generate the remapping file ‘rmp\_T42\_to\_POP43\_conserv.nc’ grid2 sweep Total number of links = 63112 -.. raw:: html - -
-Next, run UV-CDAT and create the regridder: +Next, run CDAT and create the regridder: .. doctest:: - >>> # wget "http://uvcdat.llnl.gov/cdat/sample_data/remap_grid_POP43.nc" - >>> # wget "http://uvcdat.llnl.gov/cdat/sample_data/remap_grid_T42.nc" - >>> # wget "http://uvcdat.llnl.gov/cdat/sample_data/rmp_POP43_to_T42_conserv.nc" - >>> # wget "http://uvcdat.llnl.gov/cdat/sample_data/rmp_T42_to_POP43_conserv.nc" - >>> # wget "http://uvcdat.llnl.gov/cdat/sample_data/xieArkin-T42.nc" + >>> # wget "http://cdat.llnl.gov/cdat/sample_data/remap_grid_POP43.nc" + >>> # wget "http://cdat.llnl.gov/cdat/sample_data/remap_grid_T42.nc" + >>> # wget "http://cdat.llnl.gov/cdat/sample_data/rmp_POP43_to_T42_conserv.nc" + >>> # wget "http://cdat.llnl.gov/cdat/sample_data/rmp_T42_to_POP43_conserv.nc" + >>> # wget "http://cdat.llnl.gov/cdat/sample_data/xieArkin-T42.nc" >>> # Import regrid package for regridder functions >>> import regrid2, cdms2 >>> # Read the regridder from the remapper file @@ -240,8 +232,8 @@ has shape (12, 64, 128), then the input grid must have shape (64,128). Similarly if the variable had a generic grid with shape (8092,), the last dimension of the variable would have length 8092. -4.1.3 Pressure-level regridder -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Pressure-Level Regridder +^^^^^^^^^^^^^^^^^^^^^^^^ To regrid a variable which is a function of latitude, longitude, pressure level, and (optionally) time to a new set of pressure levels, @@ -251,7 +243,7 @@ returns a new variable ``d`` regridded to that dimension. .. doctest:: - >>> # wget "http://uvcdat.llnl.gov/cdat/sample_data/ta_ncep_87-6-88-4.nc" + >>> # wget "http://cdat.llnl.gov/cdat/sample_data/ta_ncep_87-6-88-4.nc" >>> f=cdms2.open("ta_ncep_87-6-88-4.nc") >>> ta=f('ta') >>> ta.shape @@ -262,8 +254,8 @@ returns a new variable ``d`` regridded to that dimension. >>> result.shape (11, 1, 73, 144) -4.1.4 Cross-section regridder -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Cross-Section Regridder +^^^^^^^^^^^^^^^^^^^^^^^ To regrid a variable which is a function of latitude, height, and (optionally) time to a new latitude/height cross-section, use the @@ -273,7 +265,7 @@ regridded to those axes. .. doctest:: - >>> # wget "http://uvcdat.llnl.gov/cdat/sample_data/ta_ncep_87-6-88-4.nc" + >>> # wget "http://cdat.llnl.gov/cdat/sample_data/ta_ncep_87-6-88-4.nc" >>> f=cdms2.open("ta_ncep_87-6-88-4.nc") >>> ta=f('ta') >>> ta.shape @@ -290,15 +282,15 @@ regridded to those axes. (2, 10, 144) -4.2 regrid module -^^^^^^^^^^^^^^^^^ +Regrid Module +^^^^^^^^^^^^^ The ``regrid`` module implements the CDMS regridding functionality as well as the SCRIP interface. Although this module is not strictly a part of CDMS, it is designed to work with CDMS objects. -4.2.1 CDMS horizontal regridder -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +CDMS Horizontal Regridder +^^^^^^^^^^^^^^^^^^^^^^^^^ .. doctest:: @@ -308,29 +300,31 @@ makes the CDMS Regridder class available within a Python program. An instance of Regridder is a function which regrids data from rectangular input to output grids. -Table 4.1 CDMS Regridder Constructor -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Table CDMS Regridder Constructor +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. csv-table:: REgridder Constructure +.. csv-table:: :header: "Constructor", "Description" :widths: 50, 90 + :align: left - "regridFunction = Regridder(inputGrid, outputGrid)", "reate a regridder function which interpolates a data array from input to output grid. `Table 4.3 <#Table_4.3>`__ on page 131 describes the calling sequence of this function. ``inputGrid`` and ``outputGrid`` are CDMS grid objects. **Note:** To set the mask associated with inputGrid or outputGrid, use the grid setMask function." + "``regridFunction = Regridder(inputGrid, outputGrid)``", "reate a regridder function which interpolates a data array from input to output grid. `CDMS regridder functions`_ describes the calling sequence of this function. ``inputGrid`` and ``outputGrid`` are CDMS grid objects. **Note:** To set the mask associated with inputGrid or outputGrid, use the grid setMask function." -4.2.2 SCRIP Regridder -^^^^^^^^^^^^^^^^^^^^^ +SCRIP Regridder +^^^^^^^^^^^^^^^ SCRIP regridder functions are created with the ``regrid.readRegridder`` function: -Table 4.2 SCRIP Regridder Constructor -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Table SCRIP Regridder Constructor +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. csv-table:: :header: "Constructor", "Description" :widths: 80, 90 + :align: left - "regridFunction = regrid.readRegridder(fileobj, mapMethod=None, checkGrid=1)", "Read a regridder from an open CDMS file object." + "``regridFunction = regrid.readRegridder(fileobj, mapMethod=None, checkGrid=1)``", "Read a regridder from an open CDMS file object." "", "``fileobj`` is a CDMS file object, as returned from ``cdms.open``." "", "``mapMethod`` is one of:" "", "- ``'conservative'``: conservative remapper, suitable where area-integrated fields such as water or heat fluxes must be conserved." @@ -341,8 +335,8 @@ Table 4.2 SCRIP Regridder Constructor "", "" "", "If ``checkGrid`` is 1 (default), the grid cells are checked for convexity, and 'repaired' if necessary. Grid cells may appear to be nonconvex if they cross a ``0 / 2pi`` boundary. The repair consists of shifting the cell vertices to the same side modulo 360 degrees." -4.3 Regridder Functions -^^^^^^^^^^^^^^^^^^^^^^^ +Regridder Functions +^^^^^^^^^^^^^^^^^^^ It is only necessary to specify the map method if it is not defined in the file. @@ -352,8 +346,8 @@ convexity, and ‘repaired’ if necessary. Grid cells may appear to be nonconvex if they cross a ``0 / 2pi`` boundary. The repair consists of shifting the cell vertices to the same side modulo 360 degrees. -4.3.1 CDMS regridder functions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +_`CDMS Regridder Functions` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ A CDMS regridder function is an instance of the CDMS ``Regridder`` class. The function is associated with rectangular input and output @@ -405,27 +399,28 @@ data value, or 1.0e20 if undefined. The result array or transient variable will have a mask value of 1 (invalid value) for those output grid cells which completely overlap input grid cells with missing values -Table 4.3 CDMS Regridder function -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Table CDMS Regridder Function +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. csv-table:: :header: "Type", "Function", "Description" :widths: 40, 40, 80 + :align: left "Array or Transient-Variable", "``regridFunction(array, missing=None, order=None, mask=None)``", "Interpolate a gridded data array to a new grid. The interpolation preservesthe area-weighted mean on each horizontal slice. If array is a Variable, a TransientVariable of the same rank as the inputarrayisreturned, otherwiseamaskedarray is returned." - , , "``array`` is a Variable, masked array, or Numeric array of rank 2, 3, or 4." + , , "``array`` is a Variable, masked array, or Numpy array of rank 2, 3, or 4." , , , , "For example, the string 'tzyx' indicates that the dimension order of ``array`` is (time, level, latitude, longitude). If unspecified, the function assumes that the last two dimensions of ``array`` match the input grid." , , "- ``missing`` is a Float specifying the missing data value. The default is 1.0e20." , , "- ``order`` is a string indicating the order of dimensions of the array. It has the form returned from ``variable.getOrder().``" - , , "- ``mask`` is a Numeric array, of datatype Integer or Float, consisting of a fractional number between 0 and 1. A value of 1 or 1.0 indicates that the corresponding data value is to be ignored for purposes of regridding. A value of 0 or 0.0 indicates that the corresponding data value is valid. This is consistent with the convention for masks used by the MA module. A fractional value between 0.0 and 1.0 indicates the fraction of the data value (e.g., the corresponding cell) to be ignored when regridding. This is useful if a variable is regridded first to grid A and then to another grid B; the mask when regridding from A to B would be (1.0 - f) where f is the maskArray returned from the initial grid operation using the ``returnTuple`` argument." + , , "- ``mask`` is a Numpy array, of datatype Integer or Float, consisting of a fractional number between 0 and 1. A value of 1 or 1.0 indicates that the corresponding data value is to be ignored for purposes of regridding. A value of 0 or 0.0 indicates that the corresponding data value is valid. This is consistent with the convention for masks used by the MV2 module. A fractional value between 0.0 and 1.0 indicates the fraction of the data value (e.g., the corresponding cell) to be ignored when regridding. This is useful if a variable is regridded first to grid A and then to another grid B; the mask when regridding from A to B would be (1.0 - f) where f is the maskArray returned from the initial grid operation using the ``returnTuple`` argument." , , "If ``mask`` is two-dimensional of the same shape as the input grid, it overrides the mask of the input grid. If the mask has more than two dimensions, it must have the same shape as ``array``. In this case, the ``missing`` data value is also ignored. Such an ndimensional mask is useful if the pattern of missing data varies with level (e.g., ocean data) or time. Note: If neither ``missing`` or ``mask`` is set, the default mask is obtained from the mask of the array if any." "Array, Array", "``regridFunction(ar, missing=None, order=None, mask=None, returnTuple=1)``", "If called with the optional ``returnTuple`` argument equal to 1, the function returns a tuple ``dataArray``, ``maskArray``)." , , "``dataArray`` is the result data array." , , "``maskArray`` is a Float32 array of the same shape as ``dataArray``, such that ``maskArray[i,j]`` is fraction of the output grid cell [i,j] overlapping a non-missing cell of the grid." -4.3.2 SCRIP Regridder functions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +SCRIP Regridder Functions +^^^^^^^^^^^^^^^^^^^^^^^^^ A SCRIP regridder function is an instance of the ScripRegridder class. Such a function is created by calling the regrid.readRegridder method. @@ -465,34 +460,31 @@ following fields: In addition, a conservative regridder has the associated grid cell areas for source and target grids. -Table 4.4 SCRIP Regridder functions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -+-------------------------------+--------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Return Type | Method | Description | -+===============================+============================================================================================+================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+ -| Array or Transient-Variable | [conservative, bilinear, and distance-weighted regridders] ``regridFunction(array)`` | Interpolate a gridded data array to a new grid. The return value is the regridded data variable. ``array`` is a Variable, MaskedArray, or Numeric array. The rank of the array may be greater than the rank of the input grid, in which case the input grid shape must match a trailing portion of the array shape. For example, if the input grid is curvilinear with shape (64,128), the last two dimensions of the array must match. Similarly, if the input grid is generic with shape (2560,), the last dimension of the array must have that length. | -+-------------------------------+--------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Array or Transient-Variable | [bicubic regridders] ``regridFunction(array, gradientLat, gradientLon, gradientLatLon)`` |

Interpolate a gridded data array to a new grid, using a bicubic regridder. The return value is the regridded data variable.

\ ``array`` is a Variable, MaskedArray, or Numeric array. The rank of the array may be greater than the rank of the input grid, in which case the input grid shape must match a trailing portion of the array shape. For example, if the input grid is curvilinear with shape (64,128), the last two dimensions of the array must match. Simiarly, if the input grid is generic with shape (2560,), the last dimension of the array must have that length.

\ ``gradientLat``: df/di (see the SCRIP documentation). Same shape as ``array``.

gradientLon: df/dj. Same shape as ``array``.

\ ``gradientLatLon``: d(df)/(di)(dj). Same shape as array.

| -+-------------------------------+--------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Numeric array | ``getDestinationArea()`` [conservative regridders only] | Return the area of the destination (output) grid cell. The array is 1-D, with length equal to the number of cells in the output grid. | -+-------------------------------+--------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Numeric array | ``getDestinationFraction()`` | Return the area fraction of the destination (output) grid cell that participates in the regridding. The array is 1-D, with length equal to the number of cells in the output grid. | -+-------------------------------+--------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CurveGrid or Generic-Grid | ``getInputGrid()`` | Return the input grid, or None if no input grid is associated with the regridder. | -+-------------------------------+--------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CurveGrid or Generic-Grid | ``getOutputGrid()`` | Return the output grid. | -+-------------------------------+--------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Numeric array | ``getSourceArea()`` [conservative regridders only] | Return the area of the source (input) grid cell. The array is 1- D, with length equal to the number of cells in the input grid. | -+-------------------------------+--------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Numeric array | ``getSourceFraction()`` | Return the area fraction of the source (input) grid cell that participates in the regridding. The array is 1-D, with length equal to the number of cells in the input grid | -+-------------------------------+--------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -4.4 Examples -^^^^^^^^^^^^ - -4.4.1 CDMS regridder -~~~~~~~~~~~~~~~~~~~~ +Table SCRIP Regridder Functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. csv-table:: + :header: "Return Type", "Method", "Description" + :widths: 40, 40, 80 + :align: left + + "Array or Transient-Variable", "[conservative, bilinear, and distance-weighted regridders] ``regridFunction(array)``", "Interpolate a gridded data array to a new grid. The return value is the regridded data variable. ``array`` is a Variable, MaskedArray, or Numpy array. The rank of the array may be greater than the rank of the input grid, in which case the input grid shape must match a trailing portion of the array shape. For example, if the input grid is curvilinear with shape (64,128), the last two dimensions of the array must match. Similarly, if the input grid is generic with shape (2560,), the last dimension of the array must have that length." + "Array or Transient-Variable", "[bicubic regridders] ``regridFunction(array, gradientLat, gradientLon, gradientLatLon)``", "Interpolate a gridded data array to a new grid, using a bicubic regridder. The return value is the regridded data variable." + ,,"``array`` is a Variable, MaskedArray, or Numpy array. The rank of the array may be greater than the rank of the input grid, in which case the input grid shape must match a trailing portion of the array shape. For example, if the input grid is curvilinear with shape (64,128), the last two dimensions of the array must match. Simiarly, if the input grid is generic with shape (2560,), the last dimension of the array must have that length." + ,,"``gradientLat``: df/di (see the SCRIP documentation). Same shape as ``array``." + ,,"``gradientLon``: df/dj. Same shape as ``array``." + ,,"``gradientLatLon``: d(df)/(di)(dj). Same shape as array." + "Numpy array", "``getDestinationArea()`` [conservative regridders only]", "Return the area of the destination (output) grid cell. The array is 1-D, with length equal to the number of cells in the output grid." + "Numpy array", "``getDestinationFraction()``", "Return the area fraction of the destination (output) grid cell that participates in the regridding. The array is 1-D, with length equal to the number of cells in the output grid." + "CurveGrid or Generic-Grid", "``getInputGrid()``", "Return the input grid, or None if no input grid is associated with the regridder." + "CurveGrid or Generic-Grid", "``getOutputGrid()``", "Return the output grid." + "Numpy array", "``getSourceFraction()``", "Return the area fraction of the source (input) grid cell that participates in the regridding. The array is 1-D, with length equal to the number of cells in the input grid" + +Examples +^^^^^^^^ + +CDMS Regridder +~~~~~~~~~~~~~~ **Example:** @@ -511,10 +503,12 @@ Regrid data to a uniform output grid. >>> newrls = regridFunc(cltf) >>> f.close() +Table Regridder Constructure +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. csv-table:: REgridder Constructure +.. csv-table:: :header: "Line", "Notes" - :widths: 8, 90 + :widths: 8, 45 "3", "Open a netCDF file for input." "6", "Create a 4 x 5 degree output grid. Note that this grid is not associated with a file or dataset." @@ -531,8 +525,8 @@ Get a mask from a separate file, and set as the input grid mask. .. doctest:: - >>> # wget http://uvcdat.llnl.gov/cdat/sample_data/clt.nc - >>> # wget http://uvcdat.llnl.gov/cdat/sample_data/geos5-sample.nc + >>> # wget http://cdat.llnl.gov/cdat/sample_data/clt.nc + >>> # wget http://cdat.llnl.gov/cdat/sample_data/geos5-sample.nc >>> import cdms2 >>> from regrid2 import Regridder >>> # @@ -568,13 +562,23 @@ Get a mask from a separate file, and set as the input grid mask. the input array sof are four-dimensional. This is the n-dimensional case. + **Example:** Generate an array of zonal mean values. -1 f = cdms.open(‘rls\_ccc\_per.nc’) 2 rlsf = f.variables[‘rls’] 3 ingrid -= rlsf.getGrid() 4 outgrid = cdms.createZonalGrid(ingrid) 5 regridFunc = -Regridder(ingrid,outgrid) 6 mean = regridFunc(rlsf) 7 f.close() + +.. doctest:: + + >>> f = cdms.open(‘rls_ccc_per.nc’) + >>> rlsf = f.variables[‘rls’] + >>> ingrid = rlsf.getGrid() + >>> outgrid = cdms.createZonalGrid(ingrid) + >>> regridFunc = Regridder(ingrid,outgrid) + >>> mean = regridFunc(rlsf) + >>> f.close() + + +--------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Line | Notes | @@ -640,8 +644,8 @@ of the result. | 13 | Calculate the area-weighted mean of the regridded data. mean and outmean should be approximately equal | +--------+----------------------------------------------------------------------------------------------------------+ -4.4.2 SCRIP regridder -~~~~~~~~~~~~~~~~~~~~~ +SCRIP Regridder +~~~~~~~~~~~~~~~ **Example:** @@ -651,9 +655,9 @@ comparison. .. doctest:: - >>> # wget "http://uvcdat.llnl.gov/cdat/sample_data/remap_grid_T42.nc" - >>> # wget http://uvcdat.llnl.gov/cdat/sample_data/rmp_T42_to_C02562_conserv.nc - >>> # wget "http://uvcdat.llnl.gov/cdat/sample_data/xieArkin-T42.nc" + >>> # wget "http://cdat.llnl.gov/cdat/sample_data/remap_grid_T42.nc" + >>> # wget http://cdat.llnl.gov/cdat/sample_data/rmp_T42_to_C02562_conserv.nc + >>> # wget "http://cdat.llnl.gov/cdat/sample_data/xieArkin-T42.nc" >>> import cdms2, regrid2, MV2 >>> # Open the SCRIP remapping file and data file >>> fremap = cdms2.open('rmp_T42_to_C02562_conserv.nc') @@ -683,4 +687,4 @@ comparison. -a + diff --git a/docs/source/manual/cdms_5.rst b/docs/source/manual/cdms_5.rst index 0da06c4f..9abdfc73 100644 --- a/docs/source/manual/cdms_5.rst +++ b/docs/source/manual/cdms_5.rst @@ -1,27 +1,30 @@ -CHAPTER 5 Plotting CDMS data in Python --------------------------------------- +Plotting CDMS data in Python +---------------------------- -5.1 Overview -~~~~~~~~~~~~ +Overview +~~~~~~~~ Data read via the CDMS Python interface can be plotted using the ``vcs`` -module. This module, part of the Ultrascale Visualization Climate Data -Analysis Tool (UV-CDAT) is documented in the UV-CDAT reference manual. +module. This module, part of the Climate Data +Analysis Tool (CDAT) is documented in the CDAT reference manual. The ``vcs`` module provides access to the functionality of the VCS visualization program. Examples of plotting data accessed from CDMS are given below, as well as documentation for the plot routine keywords. -5.2 Examples -~~~~~~~~~~~~ +Examples +~~~~~~~~ In the following examples, it is assumed that variable ``psl`` is dimensioned (time, latitude, longitude). ``psl`` is contained in the dataset named ``'sample.xml'``. -5.2.1 Example: plotting a gridded variable -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Plotting a Gridded Variable +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. highlight:: python + :linenothreshold: 3 + .. testsetup:: * import requests @@ -53,7 +56,7 @@ dataset named ``'sample.xml'``. **Notes:** -.. csv-table:: LineNotes +.. csv-table:: :header: "Line", "Notes" :widths: 10, 90 @@ -69,8 +72,8 @@ What if the units are not explicitly defined for ``clt``, or a different description is desired? ``plot`` has a number of other keywords which fill in the extra plot information. -5.2.2 Example: using aplot keywords. -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Using A Plot Keywords +^^^^^^^^^^^^^^^^^^^^^ .. doctest:: @@ -86,8 +89,8 @@ fill in the extra plot information. **Note:** Keyword arguments can be listed in any order. -5.2.3 Example: plotting a time-latitude slice -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Plotting a Time-Latitude Slice +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Assuming that variable ``clt`` has domain ``(time,latitude,longitude)``, this example selects and plots a time-latitude slice: @@ -102,15 +105,16 @@ this example selects and plots a time-latitude slice: >>> w.plot(samp, name='Total Cloudiness') -.. csv-table:: LineNotes + +.. csv-table:: Line Notes :header: "Line", "Notes" :widths: 10, 90 "4", "``samp`` is a slice of ``clt``, at index ``0`` of the last dimension. Since ``samp`` was obtained from the slice operator, it is a transient variable, which includes the latitude and time information." "6", "The ``name`` keyword defines the identifier, default is the name found in the file." -5.2.4 Example: plotting subsetted data -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Plotting Subsetted Data +^^^^^^^^^^^^^^^^^^^^^^^ Calling the variable ``clt`` as a function reads a subset of the variable. The result variable ``samp`` can be plotted directly: @@ -127,10 +131,10 @@ variable. The result variable ``samp`` can be plotted directly: >>> f.close() -5.3 ``plot`` method -~~~~~~~~~~~~~~~~~~~ +Plot Method +~~~~~~~~~~~ -The ``plot`` method is documented in the UV-CDAT Reference Manual. This +The ``plot`` method is documented in the CDAT Reference Manual. This section augments the documentation with a description of the optional keyword arguments. The general form of the plot command is: @@ -140,7 +144,7 @@ where: - canvas is a VCS Canvas object, created with the vcs.init method. -- array is a variable, masked array, or Numeric array having between +- array is a variable, masked array, or Numpy array having between two and five dimensions. The last dimensions of the array is termed the 'x' dimension, the next-to-last the 'y' dimension, then 'z', 't', and 'w'. For example, if array is three-dimensional, the axes are @@ -167,14 +171,16 @@ where: ``graphics_name``: the name of the specific graphics method ('default') - See the UV-CDAT Reference Manual and VCS Reference Manual for a + See the CDAT Reference Manual and VCS Reference Manual for a detailed description of these arguments. - ``key=value``, ... are optional keyword/value pairs, listed in any order. These are defined in the table below. +Table Plot Keywords +^^^^^^^^^^^^^^^^^^^ -.. csv-table:: "plot keywords" +.. csv-table:: :header: "Key", "Type", "Value" :widths: 20, 20, 80 @@ -187,20 +193,20 @@ where: "``hms``", "string", "Hour, minute, second" "``long_name``", "string", "Descriptive variable name, defaults to ``variable.long_name``." "``missing_value``", "same type as array", "Missing data value, defaults to ``variable.getMissing()``" - "``name``", "string", "Variable name, defaults to `variable.id``" + "``name``", "string", "Variable name, defaults to ``variable.id``" "``time``", "cdtime relative or absolute", "Time associated with the data." ,,"Example:" ,,"- ``cdtime.reltime(30.0, 'days since 1978-1-1').``" "``units``", "string", "Data units. Defaults to ``variable.units``" "``variable``", "CDMS variable object", "Variable associated with the data. The variable grid must have the same shape as the data array." - "``xarray`` (``[y|z|t|w]array``)", "1-D Numeric array", "*Rectangular grids only*. Array of coordinate values, having the same length as the corresponding dimension. Defaults to xaxis[:\] (y|z|t|waxis[:])" + "``xarray`` (``[y|z|t|w]array``)", "1-D Numpy array", "*Rectangular grids only*. Array of coordinate values, having the same length as the corresponding dimension. Defaults to ``xaxis[:\] (y|z|t|waxis[:])``" "``xaxis`` (``[y|z|t|w]axis``)", "CDMS axis object", "*Rectangular grids only*. Axis object. ``xaxis`` defaults to ``grid.getAxis(0)``, ``yaxis`` defaults to ``grid.getAxis(1)``" - "``xbounds`` (``ybounds``)", "2-D Numeric array", "*Rectangular grids only*. Boundary array of shape ``(n,2)`` where ``n`` is the axis length. Defaults to ``xaxis.getBounds()``, or ``xaxis.genGenericBounds()`` if ``None``, similarly for ``ybounds``." + "``xbounds`` (``ybounds``)", "2-D Numpy array", "*Rectangular grids only*. Boundary array of shape ``(n,2)`` where ``n`` is the axis length. Defaults to ``xaxis.getBounds()``, or ``xaxis.genGenericBounds()`` if ``None``, similarly for ``ybounds``." "``xname`` (``[y|z|t|w]name``)", "string", "*Rectangular grids only*. Axis name. Defaults to ``xaxis.id`` (``[y|z|t|w]axis.id``)" - "``xrev`` (``yrev``)", "0 or 1", "If ``xrev`` (``yrev``) is 1, reverse the direction of the x-axis (y-axis). Defaults to 0, with the following exceptions:" - ,,"- If the y-axis is latitude, and has decreasing values, ``yrev`` defaults to 1" - ,,"- If the y-axis is a vertical level, and has increasing pressure levels, ``yrev`` defaults to 1." + "``xrev`` (``yrev``)", "0 or 1", "If ``xrev`` (``yrev``) is 1, reverse the direction of the ``x-axis (y-axis)``. Defaults to 0, with the following exceptions:" + ,,"- If the ``y-axis`` is latitude, and has decreasing values, ``yrev`` defaults to 1" + ,,"- If the ``y-axis`` is a vertical level, and has increasing pressure levels, ``yrev`` defaults to 1." "``xunits`` (``[y|z|t|w]units``)", "string", "*Rectangular grids only*. Axis units. Defaults to ``xaxis.units`` (``[y|z|t|w]axis.units``)." diff --git a/docs/source/manual/cdms_6.rst b/docs/source/manual/cdms_6.rst index 98fe67d5..2bc9e8fc 100644 --- a/docs/source/manual/cdms_6.rst +++ b/docs/source/manual/cdms_6.rst @@ -1,8 +1,8 @@ -CHAPTER 6 Climate Data Markup Language (CDML) ---------------------------------------------- +Climate Data Markup Language (CDML) +----------------------------------- -6.1 Introduction -~~~~~~~~~~~~~~~~ +Introduction +~~~~~~~~~~~~ The Climate Data Markup Language (CDML) is the markup language used to represent metadata in CDMS. CDML is based on the W3C XML standard @@ -21,8 +21,8 @@ future. CDML files have the file extension .xml or .cdml. -6.2 Elements -~~~~~~~~~~~~ +Elements +~~~~~~~~ A CDML document consists of a nested collection of elements. An element is a description of the metadata associated with a CDMS object. The form @@ -50,8 +50,8 @@ where The CDML elements are: -Table 6.1 CDML Tags - +Table CDML Tags +^^^^^^^^^^^^^^^^^^^ +------------+---------------------------------------+ | Tag | Description | @@ -71,13 +71,14 @@ Table 6.1 CDML Tags | variable | Variable | +------------+---------------------------------------+ -6.3 Special Characters -~~~~~~~~~~~~~~~~~~~~~~ +Special Characters +~~~~~~~~~~~~~~~~~~ XML reserves certain characters for markup. If they appear as content, they must be encoded to avoid confusion with markup: -Table 6.2 Special Character Encodings +Table Special Character Encodings +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------+------------+ @@ -102,8 +103,8 @@ would appear in an attribute string as: **comment = "Certain "special characters", such as <, >, and ', must be encoded."** -6.4 Identifiers -~~~~~~~~~~~~~~~ +Identifiers +~~~~~~~~~~~ In CDMS, all objects in a dataset have a unique string identifier. The id attribute holds the value of this identifier. If the variable, axis, @@ -118,16 +119,16 @@ case), an underscore (_), or a colon (:). Characters after the first must be alphanumeric, an underscore, or colon. There is no restriction on the length of an identifier. -6.5 CF Metadata Standard -~~~~~~~~~~~~~~~~~~~~~~~~ +CF Metadata Standard +~~~~~~~~~~~~~~~~~~~~ `The CF metadata standard `__ defines a set of conventions for usage of netCDF. This standard is supported by CDML. The document defines names and usage for metadata attributes. CF supersedes the GDT 1.3 standard. -6.6 CDML Syntax -~~~~~~~~~~~~~~~ +CDML Syntax +~~~~~~~~~~~ The following notation is used in this section: @@ -150,8 +151,8 @@ Version 1.0. ``prolog ::= `` -6.6.1 Dataset Element -^^^^^^^^^^^^^^^^^^^^^ +Dataset Element +^^^^^^^^^^^^^^^ A dataset element describes a single dataset. The content is a list of elements corresponding to the axes, grids, and variables contained in @@ -163,7 +164,7 @@ defined. ``dataset-content ::= (axis-element | grid-element | variable-element)* extra-attribute-element+`` -Table 6.3 Dataset Attributes +Dataset Attributes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. csv-table:: :header: "Attribute", "Required", "CF", "GDT", "Notes" @@ -219,8 +220,8 @@ into files. The format is: The pathname is appended to the value of the directory attribute, to obtain an absolute pathname. -6.6.2 Axis Element -^^^^^^^^^^^^^^^^^^ +Axis Element +^^^^^^^^^^^^ An axis element describes a single coordinate axis. The content can be a blank-separated list of axis values or a linear element. A linear @@ -235,12 +236,12 @@ length). ``linear-element ::=`` ** ** -Table 6.4 -^^^^^^^^^ +Table Axis Elements +^^^^^^^^^^^^^^^^^^^ .. csv-table:: :header: "Attribute", "Required?", "CF", "GDT", "Notes" - :widths: 15,1,1,1,80 + :widths: 18,1,1,1,80 "``associate``", "N", "N", "Y", "IDs of variables containing alternative sets of coordinates." "``axis``", "N", "Y", "Y", "The spatial type of the axis:" @@ -270,7 +271,7 @@ Table 6.4 "``month_lengths``", "N", "Y", "N", "Length of each month in a non-leap year for a user-defined calendar." "``name_in_file``", "N", "N", "N", "Name of the axis in the underlying file(s). See id." "``partition``", "N", "N", "N", "How the axis is split across files." - "``partition_lengt h``", "N", "N", "N", "Number of axis points for which data is actually defined. If data is missing for some values, this will be smaller than the length." + "``partition_length``", "N", "N", "N", "Number of axis points for which data is actually defined. If data is missing for some values, this will be smaller than the length." "``positive``", "N", "Y", "Y", "Direction of positive for a vertical axis" "``standard_name``", "N", "Y", "N", "Reference to an entry in the standard name table." "``topology``", "N", "N", "Y", "- Axis topology." @@ -278,8 +279,8 @@ Table 6.4 "``units``", "Y", "Y", "Y", "Units of a physical quantity" "``weights``", "N", "N", "N", "Name of the weights array" -6.6.3 partition attribute -^^^^^^^^^^^^^^^^^^^^^^^^^ +Partition attribute +^^^^^^^^^^^^^^^^^^^ For an axis in a dataset, the .partition attribute describes how an axis @@ -304,8 +305,8 @@ Note that the end index of the second interval is strictly less than the start index of the following interval. This indicates that data for that period is missing. -6.6.4 Grid Element -^^^^^^^^^^^^^^^^^^ +Grid Element +^^^^^^^^^^^^ A grid element describes a horizontal, latitude-longitude grid which is rectilinear in topology, @@ -314,6 +315,7 @@ rectilinear in topology, ``extra-attribute-element*`` **** Table 6.5 RectGrid Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. raw:: html @@ -331,18 +333,20 @@ Table 6.5 RectGrid Attributes :: idYNGrid identifier - typeYN

Grid classification

"gaussian" | "uniform" | "equalarea" |"generic"

Default: "generic"

+ typeYN

Grid classification

"gaussian" | "uniform" + | "equalarea" |"generic"

Default: "generic"

latitudeYNLatitude axis name longitudeYNLongitude axis name maskNNName of associated mask variable - orderYN

Grid ordering "yx" | "xy"

Default: “yx”, axis order is latitude, longitude

+ orderYN

Grid ordering "yx" + | "xy"

Default: “yx”, axis order is latitude, longitude

.. raw:: html -6.6.5 Variable Element -^^^^^^^^^^^^^^^^^^^^^^ +Variable Element +^^^^^^^^^^^^^^^^ A variable element describes a data variable. The domain of the variable is an ordered list of domain elements naming the axes on which the @@ -365,1429 +369,144 @@ the length. start=\ **"``Integer``" **\ length=\ **"``Integer``" **\ partition\_length=\ **"``Integer``"**/>\*\* -Table 6.6 Variable Attributes - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html +Table Variable Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. raw:: html +Attribute Element +^^^^^^^^^^^^^^^^^ - +A Sample CDML Document +~~~~~~~~~~~~~~~~~~~~~~ -.. raw:: html +Dataset "sample" has two variables, and six axes. - +**Note:** -.. raw:: html +- The file is indented for readability. This is not required; the added + whitespace is ignored. +- The dataset contains three axes and two variables. Variables u and v + are functions of time, latitude, and longitude. +- The global attribute cdms\_filemap describes the mapping between + variables and files. The entry + ``[[u],[[0,1,-,-,u_2000.nc],[1,2,-,-,u_2001.nc],[2,3,,-,u_2002.nc] ]`` + indicates that variable ``u`` is contained in file u\_2000.nc for + time index 0, u\_2001.nc for time index 1, etc. - +{% highlight xml %} .. raw:: html - - -.. raw:: html + - + [ 0. 11.25 22.5 33.75 45. 56.25 67.5 78.75 90. -.. raw:: html + 101.25 112.5 123.75 135. 146.25 157.5 168.75 180. 191.25 - + [ 0. 366. 731.] + -.. raw:: html + + + + + + + - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - -
- -Attribute - -.. raw:: html - - - -Required? - -.. raw:: html - - - -CF - -.. raw:: html - - - -GDT - -.. raw:: html - - - -Notes - -.. raw:: html - -
- -id - -.. raw:: html - - - -Y - -.. raw:: html - - - -N - -.. raw:: html - - - -N - -.. raw:: html - - - -Variable identifier. Also, the name of the variable in the underlying -file(s), if name\_in\_file is undefined. - -.. raw:: html - -
- -add\_offset - -.. raw:: html - - - -N - -.. raw:: html - - - -Y - -.. raw:: html - - - -Y - -.. raw:: html - - -Additive offset for packing data. See scale\_factor. - -.. raw:: html - -
- -associate - -.. raw:: html - - - -N - -.. raw:: html - - - -N - -.. raw:: html - - -Y +.. csv-table:: + :header: "Attribute", "Required?", "CF", "GDT", "Notes" + :widths: 15,1,1,1,80 -.. raw:: html + "``id``", "Y", "N", "N", "Variable identifier. Also, the name of the variable in the underlying file(s), if name_in_file is undefined." + "``ad_offset``", "N", "Y", "Y", "Additive offset for packing data. See scale_factor." + "``associate``", "N", "N", "Y", "IDs of variables containing alternative sets of coordinates Spatio-temporal dimensions." + "``axis``", "N", "N", "Y", "Example: TYX for a variable with domain (time, latitude, longitude) Note: for CF, applies to axes only." + "``cell_methods``", "N", "Y", "N", "The method used to derive data that represents cell values, e.g., maximum,mean,variance, etc." + "``comments``", "N", "N", "N", "Comment string" + "``coordinates``", "N", "Y", "N", "IDs of variables containing coordinate data." + "``datatype``", "Y", "N", "N", "Char, Short, Long, Float, Double, or String" + "``grid_name``", "N", "N", "N", "Id of the grid." + "``grid_type``", "N", "N", "N", "gaussian, uniform, equalarea, generic" + "``long_name``", "N", "Y", "Y", "Long description of a physical quantity." + "``missing_value``", "N", "Y", "Y", "Value used for data that are unknown or missing." + "``name_in_file``", "N", "N", "N", "Name of the variable in the underlying file(s). See id." + "``scale_factor``", "N", "Y", "Y", "Multiplicative factor for packing data. See add_offset." + "``standard_name``", "N", "Y", "N", "Reference to an entry in the standard name table." + "``subgrid``", "N", "N", "Y", "Records how data values represent subgrid variation." + "``template``", "N", "N", "N", "Name of the file template to use for this variable. Overrides the dataset value." + "``units``", "N", "Y", "Y", "Units of a physical quantity." + "``valid_max``", "N", "Y", "Y", "Largest valid value of a variable." + "``valid_min``", "N", "Y", "Y", "Smallest valid value of a variable." + "``valid_range``", "N", "Y", "Y", "Largest and smallest valid values of a variable." - +Attributes which are not explicitly defined by the GDT convention are +represented as extra attribute elements. Any dataset, axis, grid, or +variable element can have an extra attribute as part of its content. +This representation is also useful if the attribute value has non-blank +whitespace characters (carriage returns, tabs, linefeeds) which are +significant. -IDs of variables containing alternative sets of coordinates +The datatype is one of: **Char**, **Short**, **Long**, **Float**, +**Double**, or **String**. -.. raw:: html +``extra-attribute-element ::=`` **** ``attribute-value`` +**** -
- -axis + .. raw:: html - + [-90. -78. -66. -54. -42. -30. -18. -6. 6. 18. 30. 42. 54. 66. 78. 90.] -N +:: -.. raw:: html + - + 202.5 213.75 225. 236.25 247.5 258.75 270. 281.25 292.5 -N + 303.75 315. 326.25 337.5 348.75] + -.. raw:: html + - + + + + + + + -Y + {% endhighlight %} -.. raw:: html - - - -.. raw:: html - -

- -Spatio-temporal dimensions. - -.. raw:: html - -

- -.. raw:: html - -

- -Example: "TYX" for a variable with domain (time, latitude, longitude) - -.. raw:: html - -

- -.. raw:: html - -

- -Note: for CF, applies to axes only. - -.. raw:: html - -

- -.. raw:: html - -
- -cell\_methods - -.. raw:: html - - - -N - -.. raw:: html - - - -Y - -.. raw:: html - - - -N - -.. raw:: html - - - -The method used to derive data that represents cell values, e.g., -"maximum", "mean", "variance", etc. - -.. raw:: html - -
- -comments - -.. raw:: html - - - -N - -.. raw:: html - - - -N - -.. raw:: html - - - -N - -.. raw:: html - - - -Comment string - -.. raw:: html - -
- -coordinates - -.. raw:: html - - - -N - -.. raw:: html - - - -Y - -.. raw:: html - - - -N - -.. raw:: html - - - -IDs of variables containing coordinate data. - -.. raw:: html - -
- -datatype - -.. raw:: html - - - -Y - -.. raw:: html - - - -N - -.. raw:: html - - - -N - -.. raw:: html - - - -Char, Short, Long, Float, Double, or String - -.. raw:: html - -
- -grid\_name - -.. raw:: html - - - -N - -.. raw:: html - - - -N - -.. raw:: html - - - -N - -.. raw:: html - - - -Id of the grid - -.. raw:: html - -
- -grid\_type - -.. raw:: html - - - -N - -.. raw:: html - - - -N - -.. raw:: html - - - -N - -.. raw:: html - - - -"gaussian" \| "uniform" \| "equalarea" \| "generic" - -.. raw:: html - -
- -long\_name - -.. raw:: html - - - -N - -.. raw:: html - - - -Y - -.. raw:: html - - - -Y - -.. raw:: html - - - -Long description of a physical quantity. - -.. raw:: html - -
- -missing\_value - -.. raw:: html - - - -N - -.. raw:: html - - - -Y - -.. raw:: html - - - -Y - -.. raw:: html - - - -Value used for data that are unknown or missint. - -.. raw:: html - -
- -name\_in\_file - -.. raw:: html - - - -N - -.. raw:: html - - - -N - -.. raw:: html - - - -N - -.. raw:: html - - - -Name of the variable in the underlying file(s). See id. - -.. raw:: html - -
- -scale\_factor - -.. raw:: html - - - -N - -.. raw:: html - - - -Y - -.. raw:: html - - - -Y - -.. raw:: html - - - -Multiplicative factor for packing data. See add\_offset. - -.. raw:: html - -
- -standard\_name - -.. raw:: html - - - -N - -.. raw:: html - - - -Y - -.. raw:: html - - - -N - -.. raw:: html - - - -Reference to an entry in the standard name table. - -.. raw:: html - -
- -subgrid - -.. raw:: html - - - -N - -.. raw:: html - - - -N - -.. raw:: html - - - -Y - -.. raw:: html - - - -Records how data values represent subgrid variation. - -.. raw:: html - -
- -template - -.. raw:: html - - - -N - -.. raw:: html - - - -N - -.. raw:: html - - - -N - -.. raw:: html - - - -Name of the file template to use for this variable. Overrides the -dataset value. - -.. raw:: html - -
- -units - -.. raw:: html - - - -N - -.. raw:: html - - - -Y - -.. raw:: html - - - -Y - -.. raw:: html - - - -Units of a physical quantity. - -.. raw:: html - -
- -valid\_max - -.. raw:: html - - - -N - -.. raw:: html - - - -Y - -.. raw:: html - - - -Y - -.. raw:: html - - - -Largest valid value of a variable - -.. raw:: html - -
- -valid\_min - -.. raw:: html - - - -N - -.. raw:: html - - - -Y - -.. raw:: html - - - -Y - -.. raw:: html - - - -Smallest valid value of a variable - -.. raw:: html - -
- -valid\_range - -.. raw:: html - - - -N - -.. raw:: html - - - -Y - -.. raw:: html - - - -Y - -.. raw:: html - - - -Largest and smallest valid values of a variable - -.. raw:: html - -
- -6.6.6 Attribute Element -^^^^^^^^^^^^^^^^^^^^^^^ - -Attributes which are not explicitly defined by the GDT convention are -represented as extra attribute elements. Any dataset, axis, grid, or -variable element can have an extra attribute as part of its content. -This representation is also useful if the attribute value has non-blank -whitespace characters (carriage returns, tabs, linefeeds) which are -significant. - -The datatype is one of: **Char**, **Short**, **Long**, **Float**, -**Double**, or **String**. - -``extra-attribute-element ::=`` **** ``attribute-value`` -**** - -6.7 A Sample CDML Document -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Dataset "sample" has two variables, and six axes. - -**Note:** - -- The file is indented for readability. This is not required; the added - whitespace is ignored. -- The dataset contains three axes and two variables. Variables u and v - are functions of time, latitude, and longitude. -- The global attribute cdms\_filemap describes the mapping between - variables and files. The entry - ``[[u],[[0,1,-,-,u_2000.nc],[1,2,-,-,u_2001.nc],[2,3,,-,u_2002.nc] ]`` - indicates that variable ``u`` is contained in file u\_2000.nc for - time index 0, u\_2001.nc for time index 1, etc. - -{% highlight xml %} - -.. raw:: html - - - -.. raw:: html - - - - [-90. -78. -66. -54. -42. -30. -18. -6. 6. 18. 30. 42. 54. 66. 78. 90.] - -:: - - - - [ 0. 11.25 22.5 33.75 45. 56.25 67.5 78.75 90. - - 101.25 112.5 123.75 135. 146.25 157.5 168.75 180. 191.25 - - 202.5 213.75 225. 236.25 247.5 258.75 270. 281.25 292.5 - - 303.75 315. 326.25 337.5 348.75] - - - - - [ 0. 366. 731.] - - - - - - - - - - - - - - - - - - - {% endhighlight %} - c + diff --git a/docs/source/manual/cdms_7.rst b/docs/source/manual/cdms_7.rst index ca533760..0e311778 100644 --- a/docs/source/manual/cdms_7.rst +++ b/docs/source/manual/cdms_7.rst @@ -1,11 +1,11 @@ -CHAPTER 7 CDMS Utilities ------------------------- +CDMS Utilities +-------------- -7.1 ``cdscan``: Importing datasets into CDMS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +CdScan: Importing datasets into CDMS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -7.1.1 Overview -^^^^^^^^^^^^^^ +Overview +^^^^^^^^ A dataset is a partitioned collection of files. To create a dataset, the files must be scanned to produce a text representation of the dataset. @@ -40,8 +40,8 @@ partitioned: - Files may be in any of the self-describing formats supported by CDMS, including netCDF, HDF, GrADS/GRIB, and DRS. -7.1.2 ``cdscan`` Syntax -^^^^^^^^^^^^^^^^^^^^^^^ +Syntax +^^^^^^ The syntax of the ``cdscan`` command is @@ -60,8 +60,8 @@ where Output is written to standard output by default. Use the -x option to specify an output filename. -Table 7.1 cdscan command options -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Table CDScan Command Options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. csv-table:: :header: "Option:, "Description" @@ -125,14 +125,14 @@ Table 7.1 cdscan command options - The ``[--time-linear]`` option should be used with caution, as it is applied to all the time dimensions found. -7.1.3 Examples -^^^^^^^^^^^^^^ +Examples +^^^^^^^^ - cdscan -c noleap -d test -x test.xml [uv]\*.nc - cdscan -d pcmdi\_6h -i 0.25 -r 'days since 1979-1-1' *6h*.ctl -7.1.4 File Formats -^^^^^^^^^^^^^^^^^^ +File Formats +^^^^^^^^^^^^ Data may be represented in a variety of self-describing binary file formats, including @@ -143,8 +143,8 @@ formats, including non-comment line of the control file must be a dset specification. - DRS, the PCMDI legacy format. -7.1.5 Name Aliasing -^^^^^^^^^^^^^^^^^^^ +Name Aliasing +^^^^^^^^^^^^^ A problem can occur if variables in different files are defined on different grids. What if the axis names are the same? CDMS requires that diff --git a/docs/source/manual/cdms_appendix.rst b/docs/source/manual/cdms_appendix.rst index 70e4c29e..af76da90 100644 --- a/docs/source/manual/cdms_appendix.rst +++ b/docs/source/manual/cdms_appendix.rst @@ -35,14 +35,34 @@ as identical. FIGURE 1. CDMS Classes + + APPENDIX B ---------- -Version Notes +Quick Start (Cheat Sheet) +~~~~~~~~~~~~~~~~~~~~~~~~~ +.. figure:: /manual/images/cdms_quick_start.jpg + :scale: 25% + :alt: cheat sheet + +:download:`cdms quick start ` + + +VCS Quick Reference (Cheat Sheet) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: /manual/images/vcs_quick_ref.jpg + :scale: 25% + :alt: VCS Cheat Sheet + + + +Release Notes ~~~~~~~~~~~~~ -B.1 Version 4.0 -^^^^^^^^^^^^^^^ +Release 4.0 +^^^^^^^^^^^ CDMS version 4.0 adds support for nonrectangular grids: @@ -56,15 +76,15 @@ CDMS version 4.0 adds support for nonrectangular grids: - The getMesh and clone methods were added for grids. - An interface to the SCRIP package was added. -B.2 Version 3.0 Overview -^^^^^^^^^^^^^^^^^^^^^^^^ +Release 3.0 Overview +^^^^^^^^^^^^^^^^^^^^ CDMS version 3.0 is a significant enhancement of previous versions. The major changes were: -- UV-CDAT/CDMS was integrated with the Numerical Python masked array - class MA.MaskedVariable. The MV submodule was added as a wrapper - around MA. +- CDAT/CDMS was integrated with the Numpyal Python masked array + class MV2.MaskedVariable. The MV submodule was added as a wrapper + around MV. - Methods that read data, such as subRegion, subSlice, and the slice operations, return instances of class TransientVariable. The plot and regrid modules were modified to handle masked array input. The @@ -81,20 +101,20 @@ major changes were: allows CDMS classes to be subclassed more readily. - The class Variable was renamed DatasetVariable. - The cu module was emulated in cdms. cu and cdms methods can be mixed. -- The code was modularized, so that Python, CDMS, and Numerical Python +- The code was modularized, so that Python, CDMS, and Numpyal Python can be built and installed separately. This significantly enhances the portability of the code. -B.3 V3.0 Details -^^^^^^^^^^^^^^^^ +Details +^^^^^^^ -B.3.1 AbstractVariable -'''''''''''''''''''''' +AbstractVariable +'''''''''''''''' - Functions getDomain, getSlice, rank, regrid, setMissing, size, subRegion, and subSlice were added. - The functions getRegion, getSlice, getValue, and the slice operators - all return an instance of MA, a masked array. Singleton dimensions + all return an instance of MV, a masked array. Singleton dimensions are squeezed. - The functions subRegion and subSlice return an instance of TransientVariable. Singleton dimensions are not squeezed. @@ -107,8 +127,8 @@ B.3.1 AbstractVariable - AbstractVariable implements arithmetic functions, astype. - The write function was added. -B.3.2 AbstractAxis -'''''''''''''''''' +AbstractAxis +'''''''''''' - The functions asComponentTime, asRelativeTime, clone, getAxisIds, getAxis-Index, getAxisList, getAxisListIndex, mapIntervalExt were @@ -119,87 +139,88 @@ B.3.2 AbstractAxis closed. The intersection options 'n','e','b',and 's' were added to the interval indicator - see mapIntervalExt. -B.3.3 AbstractDatabase -'''''''''''''''''''''' +AbstractDatabase +'''''''''''''''' - The function open is synonymous with openDataset. -B.3.4 Dataset -''''''''''''' +Dataset +''''''' - The function open is synonymous with openDataset. -B.3.5 cdms module -''''''''''''''''' +cdms module +''''''''''' - The functions asVariable, isVariable, and createVariable were added. - The function setAutoReshapeMode was removed. It is replaced by the squeeze option for all I/O functions. -B.3.6 CdmsFile -'''''''''''''' +CdmsFile +'''''''' - The function createVariable has a keyword fill\_value. The datatype - may be a Numeric/MA typecode. + may be a Numpy/MV typecode. - The function write was added. -B.3.7 CDMSError -''''''''''''''' +CDMSError +''''''''' - All errors are an instance of the class CDMSError. -B.3.8 AbstractRectGrid -'''''''''''''''''''''' +AbstractRectGrid +'''''''''''''''' - The function createGaussianGrid was added. -B.3.9 InternalAttributes -'''''''''''''''''''''''' +InternalAttributes +'''''''''''''''''' - The class InternalAttributes was added. It has methods add\_internal\_attribute, is\_internal\_attribute, and replace\_external\_attributes. -B.3.10 TransientVariable -'''''''''''''''''''''''' +TransientVariable +''''''''''''''''' - The class TransientVariable was added. It inherits from both - AbstractVariable and MA. + AbstractVariable and MV. - The cdms module function createVariable returns a transient variable. - This class does not implement the functions getPaths or getTemplate. -B.3.11 MV -''''''''' +MV +'' - The MV submodule of cdms was added. APPENDIX C ---------- -``cu`` Module -~~~~~~~~~~~~~ +Module `cu` +~~~~~~~~~~~ -The ``cu`` module is the original UV-CDAT I/O interface. As of version 3 +The ``cu`` module is the original CDAT I/O interface. As of version 3 it is emulated in the ``cdms`` module. It is maintained for backward compatibility. The ``cu`` classes are ``Slab``, corresponding to ``TransientVariable`` in CDMS, and ``cuDataset``, corresponding to ``Dataset`` in CDMS. -C.1 Slab -~~~~~~~~ +Slab +~~~~ -Table C.1 Slab Methods +Table Slab Methods ^^^^^^^^^^^^^^^^^^^^^^ -.. csv-table:: Slab_Methods - :header: "Type","Method","Definition" +.. csv-table:: + :header: "Type", "Method", "Definition" :widths: 20,50,80 + :align: left "Various", "``getdimattribute(dim, field)``", "Get the value of a dimension attribute. ``dim`` is the dimension number, an integer in the range 0..rank- 1. ``field`` is a string, one of: 'name', 'values', 'length', 'units', 'weights', 'bounds'." "Various", "``getattribute(name)``", "Get the value of an attribute.``name`` is the string name of the attribute. The following special names can always be used: 'filename', 'comments', 'grid_name', 'grid_type', 'time_statistic', 'long_name', 'units'." - "None", "``info(flag=None, device=sys.stdout)``", "Print slab information. If ``flag`` is nonzero, dimension values, weights, and bounds are also printed. Output is sent to ``device ``. " + "None", "``info(flag=None, device=sys.stdout)``", "Print slab information. If ``flag`` is nonzero, dimension values, weights, and bounds are also printed. Output is sent to ``device``." "List", "``listall(all=None)``", "Print slab information. If ``all`` is nonzero, dimension values, weights, and bounds are also printed." "List", "``listdimattributes(dim, field)``", "List dimension attributes. Returns a list of string attribute names which can be input to ``getdimattribute``. ``dim`` is the dimension number, an integer in the range 0..rank-1. ``field`` is a string, one of: 'name', 'values', 'length', 'units', 'weights', 'bounds'." "None", "``setattribute(name, value)``", "Set an attribute. ``name`` is the string name of the attribute. ``value`` is the value of the attribute." @@ -207,45 +228,46 @@ Table C.1 Slab Methods -C.2 cuDataset -~~~~~~~~~~~~~ +cuDataset +~~~~~~~~~ -Table C.2 cuDataset Methods +Table cuDataset Methods ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. csv-table:: cuDataset_Methods +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 20, 50, 80 + :align: left - "None", "cleardefault()", "Clear the default variable name." - "None", "default_variable(vname)", "Set the default variable name." + "None", "``cleardefault()``", "Clear the default variable name." + "None", "``default_variable(vname``)", "Set the default variable name." ,,"vname is the string variable name." - "Array", "dimensionarray(dname, vname=None)", "Values of the axis named dname." + "Array", "``dimensionarray(dname, vname=None``)", "Values of the axis named dname." ,,"dname is the string axis name." ,,"vname is the string variable name. The default is the variable name set by default_variable." - "Axis", "dimensionobject(dname, vname=None)", "Get an axis. dname is the string name of an axis. vname is a string variable name. The default is the variable name set by default_variable." - "Various", "getattribute (vname, attribute)", "Get an attribute value. vname is a string variable name. attribute is the string attribute name." - "String", "getdimensionunits (dname,vname=None)", "Get the units for the given dimension." + "Axis", "``dimensionobject(dname, vname=None)``", "Get an axis. dname is the string name of an axis. vname is a string variable name. The default is the variable name set by default_variable." + "Various", "``getattribute (vname, attribute``)", "Get an attribute value. vname is a string variable name. attribute is the string attribute name." + "String", "``getdimensionunits (dname,vname=None``)", "Get the units for the given dimension." ,,"dname is the string name of an axis." ,,"vname is a string variable name. The default is the variable name set by default_variable." - "Various", "getglobal (attribute)", "Get the value of the global attribute. attribute is the string attribute name." - "Variable", "getslab (vname, \*args)", "Read data for a variable." + "Various", "``getglobal (attribute)``", "Get the value of the global attribute. attribute is the string attribute name." + "Variable", "``getslab (vname, \*args)``", "Read data for a variable." ,, "vname is the string name of the variable." ,, "args is an argument list corresponding to the dimensions of the variable. Arguments for each dimension can be:" ,, "- ':' or None -- select the entire dimension" ,, "- Ellipsis -- select entire dimensions between the ones given." ,, "- a pair of successive arguments giving an interval in world coordinates." ,, "- a CDMS-style tuple of world coordinates e.g. (start, stop, 'cc')" - "List", "listall (vname=None, all=None)", "Get info about data from the file." + "List", "``listall (vname=None, all=None)``", "Get info about data from the file." ,, "vname is the string name of the variable." ,, "If all is non-zero, dimension values, weights, and bounds are returned as well" - "List", "listattribute (vname=None )", "Return a list of attribute names. vname is the name of the variable. The default is the variable name set by default_variable." - "List", "listdimension (vname=None)", "Return a list of the dimension names associated with a variable. vname is the name of the variable. The default is the variable name set by default_variable." - "List", "listglobal ()", "Return a list of the global attribute names." - "List", "listvariable ()", "Return a list of the variables in the file." - "None", "showall (vname=None, all=None, device=sys.stdout)", "Print a description of the variable. vname is the string name of the variable. If all is non-zero, dimension values, weights, and bounds are returned as well. Output is sent to device." - "None", "showattribute (vname=None, device=sys.stdout)", "Print the attributes of a variable. vname is the string name of the variable. Output is sent to device." - "None", "showdimension (vname=None, device=sys.stdout)", "Print the dimension names associated with a variable. vname is the string name of the variable. Output is sent to device." - "None", "showglobal (device=sys.stdout)", "Print the global file attributes. Output is sent to device." - "None", "showvariable (device=sys.stdout)", "Print the list of variables in the file." + "List", "``listattribute (vname=None )``", "Return a list of attribute names. vname is the name of the variable. The default is the variable name set by default_variable." + "List", "``listdimension (vname=None)``", "Return a list of the dimension names associated with a variable. vname is the name of the variable. The default is the variable name set by default_variable." + "List", "``listglobal ()``", "Return a list of the global attribute names." + "List", "``listvariable ()``", "Return a list of the variables in the file." + "None", "``showall (vname=None, all=None, device=sys.stdout)``", "Print a description of the variable. vname is the string name of the variable. If all is non-zero, dimension values, weights, and bounds are returned as well. Output is sent to device." + "None", "``showattribute (vname=None, device=sys.stdout)``", "Print the attributes of a variable. vname is the string name of the variable. Output is sent to device." + "None", "``showdimension (vname=None, device=sys.stdout)``", "Print the dimension names associated with a variable. vname is the string name of the variable. Output is sent to device." + "None", "``showglobal (device=sys.stdout)``", "Print the global file attributes. Output is sent to device." + "None", "``showvariable (device=sys.stdout)``", "Print the list of variables in the file." diff --git a/docs/source/manual/docs/cdms_quick_start.pdf b/docs/source/manual/docs/cdms_quick_start.pdf new file mode 100644 index 00000000..b87cbcf9 Binary files /dev/null and b/docs/source/manual/docs/cdms_quick_start.pdf differ diff --git a/docs/source/manual/images/cdms_logo2_nocube.png b/docs/source/manual/images/cdms_logo2_nocube.png new file mode 100644 index 00000000..3ba6a2a2 Binary files /dev/null and b/docs/source/manual/images/cdms_logo2_nocube.png differ diff --git a/docs/source/manual/images/cdms_quick_start.jpg b/docs/source/manual/images/cdms_quick_start.jpg new file mode 100644 index 00000000..7669fc20 Binary files /dev/null and b/docs/source/manual/images/cdms_quick_start.jpg differ diff --git a/docs/source/manual/sample_data.rst b/docs/source/manual/sample_data.rst new file mode 100644 index 00000000..7ab72453 --- /dev/null +++ b/docs/source/manual/sample_data.rst @@ -0,0 +1,125 @@ +CDMS Sample Dataset +------------------- + +* http://cdat.llnl.gov/cdat/sample_data/161122_RobertPincus_multiple_input4MIPs_radiation_RFMIP_UColorado-RFMIP-20161122_none.nc +* http://cdat.llnl.gov/cdat/sample_data/20160520.A_WCYCL1850.ne30_oEC.edison.alpha6_01_ANN_climo_Q.nc +* http://cdat.llnl.gov/cdat/sample_data/area_weights.nc +* http://cdat.llnl.gov/cdat/sample_data/BlueMarble.ppm +* http://cdat.llnl.gov/cdat/sample_data/CCTM_ACONC.D1.001 +* http://cdat.llnl.gov/cdat/sample_data/CCTM_ACONC.D1.002 +* http://cdat.llnl.gov/cdat/sample_data/CCTM_ACONC.D1.003 +* http://cdat.llnl.gov/cdat/sample_data/CCTM_ACONC.D1.004 +* http://cdat.llnl.gov/cdat/sample_data/CCTM_ACONC.D1.005 +* http://cdat.llnl.gov/cdat/sample_data/CCTM_CONC.D1.001 +* http://cdat.llnl.gov/cdat/sample_data/cdtest10.xml +* http://cdat.llnl.gov/cdat/sample_data/cdtest13.xml +* http://cdat.llnl.gov/cdat/sample_data/cdtest14.xml +* http://cdat.llnl.gov/cdat/sample_data/clt2.nc +* http://cdat.llnl.gov/cdat/sample_data/clt.nc +* http://cdat.llnl.gov/cdat/sample_data/dar.meteo.mod.cam3.era.v31.h0.l3.nrstpt.cp.2000070100.2000080100.tau.12.36.nc +* http://cdat.llnl.gov/cdat/sample_data/dvtest1.dat +* http://cdat.llnl.gov/cdat/sample_data/dvtest1.dic +* http://cdat.llnl.gov/cdat/sample_data/era15_tas_sample.nc +* http://cdat.llnl.gov/cdat/sample_data/era40_sst_sample.nc +* http://cdat.llnl.gov/cdat/sample_data/era40_tas_sample.nc +* http://cdat.llnl.gov/cdat/sample_data/genutil_statistics.nc +* http://cdat.llnl.gov/cdat/sample_data/geo.1deg.ctl +* http://cdat.llnl.gov/cdat/sample_data/geo.1deg.gmp +* http://cdat.llnl.gov/cdat/sample_data/geo.1deg.grb +* http://cdat.llnl.gov/cdat/sample_data/geos5-sample.nc +* http://cdat.llnl.gov/cdat/sample_data/gfs.globl.b20121028_00z.e20121102_00z.ctl +* http://cdat.llnl.gov/cdat/sample_data/gfs.globl.b20121028_00z.e20121102_00z.data +* http://cdat.llnl.gov/cdat/sample_data/GPCP_ANN_climo.nc +* http://cdat.llnl.gov/cdat/sample_data/gpcp_cdr_v23rB1_y2016_m08.nc +* http://cdat.llnl.gov/cdat/sample_data/GRIDCRO2D_D1.001 +* http://cdat.llnl.gov/cdat/sample_data/hadcrut2_sample.nc +* http://cdat.llnl.gov/cdat/sample_data/junk.nc +* http://cdat.llnl.gov/cdat/sample_data/MERRA_ANN_climo_SHUM.nc +* http://cdat.llnl.gov/cdat/sample_data/meshfill.nc +* http://cdat.llnl.gov/cdat/sample_data/model_ANN_climo.nc +* http://cdat.llnl.gov/cdat/sample_data/navy_land.nc +* http://cdat.llnl.gov/cdat/sample_data/netcdf4_compressed_example.nc +* http://cdat.llnl.gov/cdat/sample_data/obs_timeseries.nc +* http://cdat.llnl.gov/cdat/sample_data/prcp_1951.nc +* http://cdat.llnl.gov/cdat/sample_data/psl_6h.nc +* http://cdat.llnl.gov/cdat/sample_data/ps.wrap.test.0E.nc +* http://cdat.llnl.gov/cdat/sample_data/ps.wrap.test.180E.nc +* http://cdat.llnl.gov/cdat/sample_data/ps.wrap.test.180W.nc +* http://cdat.llnl.gov/cdat/sample_data/ps.wrap.test.60E.nc +* http://cdat.llnl.gov/cdat/sample_data/readonly.nc +* http://cdat.llnl.gov/cdat/sample_data/remap_grid_POP43.nc +* http://cdat.llnl.gov/cdat/sample_data/remap_grid_T42.nc +* http://cdat.llnl.gov/cdat/sample_data/rlut_CERES_000001-000012_ac.nc +* http://cdat.llnl.gov/cdat/sample_data/rmp_C02562_to_T42_conserv.nc +* http://cdat.llnl.gov/cdat/sample_data/rmp_POP43_to_T42_conserv.nc +* http://cdat.llnl.gov/cdat/sample_data/rmp_T42_to_C02562_conserv.nc +* http://cdat.llnl.gov/cdat/sample_data/rmp_T42_to_POP43_conserv.nc +* http://cdat.llnl.gov/cdat/sample_data/sampleCurveGrid4.nc +* http://cdat.llnl.gov/cdat/sample_data/sampleGenGrid3.nc +* http://cdat.llnl.gov/cdat/sample_data/sample.nc +* http://cdat.llnl.gov/cdat/sample_data/sample_polar.nc +* http://cdat.llnl.gov/cdat/sample_data/sftbyrgn.nc +* http://cdat.llnl.gov/cdat/sample_data/sftlf_10x10.nc +* http://cdat.llnl.gov/cdat/sample_data/sftlf_ccsr.nc +* http://cdat.llnl.gov/cdat/sample_data/sftlf_dnm.nc +* http://cdat.llnl.gov/cdat/sample_data/sftlf_visus.nc +* http://cdat.llnl.gov/cdat/sample_data/so_Omon_ACCESS1-0_historical_r1i1p1_185001-185412_2timesteps.nc +* http://cdat.llnl.gov/cdat/sample_data/so_Omon_GISS-E2-R_historicalNat_r5i1p1_185001-187512_2timesteps.nc +* http://cdat.llnl.gov/cdat/sample_data/so_Omon_HadGEM2-CC_historical_r1i1p1_185912-186911_2timesteps.nc +* http://cdat.llnl.gov/cdat/sample_data/so_Omon_MPI-ESM-LR_1pctCO2_r1i1p1_185001-185912_2timesteps.nc +* http://cdat.llnl.gov/cdat/sample_data/stereographic.nc +* http://cdat.llnl.gov/cdat/sample_data/swan.four.nc +* http://cdat.llnl.gov/cdat/sample_data/ta_300_850_PCM_O_mm_xy_wa_r0000_0000.dat +* http://cdat.llnl.gov/cdat/sample_data/ta_300_850_PCM_O_mm_xy_wa_r0000_0000.dic +* http://cdat.llnl.gov/cdat/sample_data/ta_ncep_87-6-88-4.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_6h.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_ccsr-95a_1979.01-1979.12.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_ccsr-95a_1980.01-1980.12.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_ccsr-95a_1981.01-1981.12.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_ccsr-95a_1982.01-1982.12.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_ccsr-95a_1983.01-1983.12.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_ccsr-95a_1984.01-1984.12.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_ccsr-95a.xml +* http://cdat.llnl.gov/cdat/sample_data/tas_cru_1979.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_dnm-95a_1979.01-1979.12.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_dnm-95a_1980.01-1980.12.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_dnm-95a_1981.01-1981.12.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_dnm-95a_1982.01-1982.12.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_dnm-95a_1983.01-1983.12.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_dnm-95a_1984.01-1984.12.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_dnm-95a.xml +* http://cdat.llnl.gov/cdat/sample_data/tas_ecm_1979.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_gavg_rnl_ecm.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_GFDL-ESM2G_Amon_historical_r1i1p1_198501-200512-clim.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_mo_clim.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_mo.nc +* http://cdat.llnl.gov/cdat/sample_data/tas_ukmo_con.nc +* http://cdat.llnl.gov/cdat/sample_data/taylor.nc +* http://cdat.llnl.gov/cdat/sample_data/tdata.hdf +* http://cdat.llnl.gov/cdat/sample_data/test.2.bin +* http://cdat.llnl.gov/cdat/sample_data/test_anim.nc +* http://cdat.llnl.gov/cdat/sample_data/test.bin +* http://cdat.llnl.gov/cdat/sample_data/test.cdms +* http://cdat.llnl.gov/cdat/sample_data/test_col.asc +* http://cdat.llnl.gov/cdat/sample_data/testgrib2.ctl +* http://cdat.llnl.gov/cdat/sample_data/testgrib2.grib2 +* http://cdat.llnl.gov/cdat/sample_data/testgrib2.idx +* http://cdat.llnl.gov/cdat/sample_data/test_mesa_leak.nc +* http://cdat.llnl.gov/cdat/sample_data/testpp.pp +* http://cdat.llnl.gov/cdat/sample_data/test.xml +* http://cdat.llnl.gov/cdat/sample_data/thermo.nc +* http://cdat.llnl.gov/cdat/sample_data/th_yr.nc +* http://cdat.llnl.gov/cdat/sample_data/ts_da.nc +* http://cdat.llnl.gov/cdat/sample_data/u_2000.nc +* http://cdat.llnl.gov/cdat/sample_data/u_2001.nc +* http://cdat.llnl.gov/cdat/sample_data/u_2002.nc +* http://cdat.llnl.gov/cdat/sample_data/v_2000.nc +* http://cdat.llnl.gov/cdat/sample_data/v_2001.nc +* http://cdat.llnl.gov/cdat/sample_data/v_2002.nc +* http://cdat.llnl.gov/cdat/sample_data/vertical.nc +* http://cdat.llnl.gov/cdat/sample_data/vmro3_input4MIPs_ozone_DAMIP_CCMI-hist-stratO3-1-0_gr_185001_nco.nc +* http://cdat.llnl.gov/cdat/sample_data/wk_data.nc +* http://cdat.llnl.gov/cdat/sample_data/wk_results.nc +* http://cdat.llnl.gov/cdat/sample_data/wspd.coads.nc +* http://cdat.llnl.gov/cdat/sample_data/wspd.nc +* http://cdat.llnl.gov/cdat/sample_data/xieArkin-T42.nc diff --git a/docs/source2/manual/images/curvilinear_grid.jpg b/docs/source2/manual/images/curvilinear_grid.jpg new file mode 100644 index 00000000..f09fe0d6 Binary files /dev/null and b/docs/source2/manual/images/curvilinear_grid.jpg differ diff --git a/docs/source2/manual/images/generic_grid.jpg b/docs/source2/manual/images/generic_grid.jpg new file mode 100755 index 00000000..935a1de2 Binary files /dev/null and b/docs/source2/manual/images/generic_grid.jpg differ diff --git a/tests/test_cdscan.py b/tests/test_cdscan.py index e5730c25..e53bdcba 100755 --- a/tests/test_cdscan.py +++ b/tests/test_cdscan.py @@ -52,6 +52,10 @@ def testopenFile(self): ''' retrieve value from cdscan ''' + try: + os.unlink(os.environ['HOME']+'/.dodsrc') + except: + pass argv = 'cdscan -x test_dap.xml https://dataserver.nccs.nasa.gov/thredds/dodsC/bypass/CREATE-IP/Reanalysis/NASA-GMAO/GEOS-5/MERRA/mon/atmos/zg.ncml'.split() pth = cdat_info.get_sampledata_path() os.chdir(pth)