cdms2 package¶
Submodules¶
cdms2.CDML module¶
CDML Document Type Definition This defines the CDML language
cdms2.CDMLParser module¶
Parse a CDML/XML file
-
class
CDMLParser
(verbose=0)[source]¶ Bases:
cdms2.cdxmllib.XMLParser
cdms2.MV2 module¶
CDMS Variable objects, MaskedArray interface
-
arange
(start, stop=None, step=1, typecode=None, axis=None, attributes=None, id=None, dtype=None)¶ Just like range() except it returns a variable whose type can be specfied by the keyword argument typecode. The axis of the result variable may be specified.
-
argsort
(x, axis=- 1, fill_value=None)[source]¶ Treating masked values as if they have the value fill_value, return sort indices for sorting along given axis. if fill_value is None, use fill_value(x)
-
arrayrange
(start, stop=None, step=1, typecode=None, axis=None, attributes=None, id=None, dtype=None)[source]¶ Just like range() except it returns a variable whose type can be specfied by the keyword argument typecode. The axis of the result variable may be specified.
-
asarray
(data, typecode=None, dtype=None) is equivalent to array(data, dtype=None, copy=0)[source]¶ Assarray
- Returns
- data if dtype is None or data is a MaskedArray of the same dtype.
- typecode arg is for backward compatibility.
-
average
(a, axis=None, weights=None, returned=False)[source]¶ Return the weighted average of array over the given axis.
- Parameters
- aarray_like
Data to be averaged. Masked entries are not taken into account in the computation.
- axisint, optional
Axis along which to average a. If None, averaging is done over the flattened array.
- weightsarray_like, optional
The importance that each element has in the computation of the average. The weights array can either be 1-D (in which case its length must be the size of a along the given axis) or of the same shape as a. If
weights=None
, then all data in a are assumed to have a weight equal to one. The 1-D calculation is:avg = sum(a * weights) / sum(weights)
The only constraint on weights is that sum(weights) must not be 0.
- returnedbool, optional
Flag indicating whether a tuple
(result, sum of weights)
should be returned as output (True), or just the result (False). Default is False.
- Returns
- average, [sum_of_weights](tuple of) scalar or MaskedArray
The average along the specified axis. When returned is True, return a tuple with the average as the first element and the sum of the weights as the second element. The return type is np.float64 if a is of integer type and floats smaller than float64, or the input data-type, otherwise. If returned, sum_of_weights is always float64.
Examples
>>> a = np.ma.array([1., 2., 3., 4.], mask=[False, False, True, True]) >>> np.ma.average(a, weights=[3, 1, 0, 0]) 1.25
>>> x = np.ma.arange(6.).reshape(3, 2) >>> x masked_array( data=[[0., 1.], [2., 3.], [4., 5.]], mask=False, fill_value=1e+20) >>> avg, sumweights = np.ma.average(x, axis=0, weights=[1, 2, 3], ... returned=True) >>> avg masked_array(data=[2.6666666666666665, 3.6666666666666665], mask=[False, False], fill_value=1e+20)
-
choose
(myindices, t)[source]¶ Choose
- Returns
- an array shaped like indices containing elements chosen from t.
- If an element of t is the special element masked, any element of
- the result that “chooses” that element is masked. The result has
- only the default axes.
-
commonAxes
(a, bdom, omit=None)[source]¶ Helper function for commonDomain.
- Parameters
- ‘a’is a variable or array,
- ‘b’is an axislist or None.
-
commonDomain
(a, b, omit=None)[source]¶ Common Domain
- Parameters
- commonDomain(a,b)tests that the domains of variables/arrays a and b are equal,
- Returns
- the common domain if equal, or None if not equal.
- The domains may differ in that one domain may have leading
- axes not common to the other; the result domain will contain those axes.
If <omit> is specified, as an integer i, skip comparison of the ith dimension and return None for the ith (common) dimension.
-
commonGrid
(a, b, axes)[source]¶ Common Grid
- Parameters
- commonGrid(a,b,axes)tests if the grids associated with variables a, b are equal
and consistent with the list of axes.
- If so, the common grid is returned, else None is returned.
- a and b can be numpy arrays, in which case the result is None.
- The common grid is ‘consistent’ with axes if the grid axes (e.g., the axes of
- latitude and longitude coordinate variables) are members of the list ‘axes’.
- If the grid(s) of a, b are rectilinear, the result is None, as the grids
- are implicitly defined by the axes.
-
concatenate
(arrays, axis=0, axisid=None, axisattributes=None)[source]¶ Concatenate the arrays along the given axis. Give the extended axis the id and attributes provided - by default, those of the first array.
-
diagonal
(a, offset=0, axis1=0, axis2=1)[source]¶ Diagonal
- Parameters
- diagonal(a, offset=0, axis1=0, axis2 = 1)
- Returns
- The given diagonals defined by the two dimensions of the array.
-
dump
(file)¶ Dump a pickle of the array to the specified file. The array can be read back with pickle.load or numpy.load.
- Parameters
- filestr or Path
A string naming the dump file.
Changed in version 1.17.0: pathlib.Path objects are now accepted.
-
masked_array
(a, mask=None, fill_value=None, axes=None, attributes=None, id=None)[source]¶ Masked Array
- Parameters
- masked_array(a, mask=None) = array(a, mask=mask, copy=0, fill_value=fill_value)
- Use fill_value(a) if None.
-
masked_equal
(x, value)[source]¶ masked_equal(x, value) = x masked where x == value For floating point consider masked_values(x, value) instead.
-
masked_object
(data, value, copy=1, savespace=0, axes=None, attributes=None, id=None)[source]¶ Create array masked where exactly data equal to value
-
masked_values
(data, value, rtol=1e-05, atol=1e-08, copy=1, savespace=0, axes=None, attributes=None, id=None)[source]¶ Masked Values
- Parameters
- masked_values(data, value, rtol=1.e-5, atol=1.e-8)
- Create a masked array; mask is None if possible.
- May share data values with original array, but not recommended.
- Masked where abs(data-value)<= atol + rtol * abs(value)
-
masked_where
(condition, x, copy=1)[source]¶ Marked Where
- Returns
- x as an array masked where condition is true. Also masked where x or condition masked.
-
max
(a, axis=None)[source]¶ Return the maximum along a given axis.
- Parameters
- axis{None, int}, optional
Axis along which to operate. By default,
axis
is None and the flattened input is used.- outarray_like, optional
Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output.
- fill_value{var}, optional
Value used to fill in the masked values. If None, use the output of maximum_fill_value().
- keepdimsbool, optional
If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the array.
- Returns
- amaxarray_like
New array holding the result. If
out
was specified,out
is returned.
See also
maximum_fill_value
Returns the maximum filling value for a given datatype.
-
min
(a, axis=None)[source]¶ Return the minimum along a given axis.
- Parameters
- axis{None, int}, optional
Axis along which to operate. By default,
axis
is None and the flattened input is used.- outarray_like, optional
Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output.
- fill_value{var}, optional
Value used to fill in the masked values. If None, use the output of minimum_fill_value.
- keepdimsbool, optional
If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the array.
- Returns
- aminarray_like
New array holding the result. If
out
was specified,out
is returned.
See also
minimum_fill_value
Returns the minimum filling value for a given datatype.
-
ones
(myshape, typecode=<class 'float'>, savespace=0, axes=None, attributes=None, id=None, grid=None, dtype=None)[source]¶ ones(n, typecode=float, savespace=0, axes=None, attributes=None, id=None) = an array of all ones of the given length or shape.
-
repeat
(a, repeats, axis=None)[source]¶ repeat elements of a repeats times along axis repeats is a sequence of length a.shape[axis] telling how many times to repeat each element.
-
reshape
(a, newshape, axes=None, attributes=None, id=None, grid=None)[source]¶ - numpy doc:
Gives a new shape to an array without changing its data.
- Parameters
- aarray_like
Array to be reshaped.
- newshapeint or tuple of ints
The new shape should be compatible with the original shape. If an integer, then the result will be a 1-D array of that length. One shape dimension can be -1. In this case, the value is inferred from the length of the array and remaining dimensions.
- order{‘C’, ‘F’, ‘A’}, optional
Read the elements of a using this index order, and place the elements into the reshaped array using this index order. ‘C’ means to read / write the elements using C-like index order, with the last axis index changing fastest, back to the first axis index changing slowest. ‘F’ means to read / write the elements using Fortran-like index order, with the first index changing fastest, and the last index changing slowest. Note that the ‘C’ and ‘F’ options take no account of the memory layout of the underlying array, and only refer to the order of indexing. ‘A’ means to read / write the elements in Fortran-like index order if a is Fortran contiguous in memory, C-like order otherwise.
- Returns
- reshaped_arrayndarray
This will be a new view object if possible; otherwise, it will be a copy. Note there is no guarantee of the memory layout (C- or Fortran- contiguous) of the returned array.
See also
ndarray.reshape
Equivalent method.
Notes
It is not always possible to change the shape of an array without copying the data. If you want an error to be raised when the data is copied, you should assign the new shape to the shape attribute of the array:
>>> a = np.zeros((10, 2)) # A transpose makes the array non-contiguous >>> b = a.T # Taking a view makes it possible to modify the shape without modifying # the initial object. >>> c = b.view() >>> c.shape = (20) Traceback (most recent call last): ... AttributeError: Incompatible shape for in-place modification. Use `.reshape()` to make a copy with the desired shape.
The order keyword gives the index ordering both for fetching the values from a, and then placing the values into the output array. For example, let’s say you have an array:
>>> a = np.arange(6).reshape((3, 2)) >>> a array([[0, 1], [2, 3], [4, 5]])
You can think of reshaping as first raveling the array (using the given index order), then inserting the elements from the raveled array into the new array using the same kind of index ordering as was used for the raveling.
>>> np.reshape(a, (2, 3)) # C-like index ordering array([[0, 1, 2], [3, 4, 5]]) >>> np.reshape(np.ravel(a), (2, 3)) # equivalent to C ravel then C reshape array([[0, 1, 2], [3, 4, 5]]) >>> np.reshape(a, (2, 3), order='F') # Fortran-like index ordering array([[0, 4, 3], [2, 1, 5]]) >>> np.reshape(np.ravel(a, order='F'), (2, 3), order='F') array([[0, 4, 3], [2, 1, 5]])
axes/attributes/grid are applied onto the new variable
-
resize
(a, new_shape)[source]¶ Resize
- Returns
- a new array with the specified shape.
- The original array’s total size can be any size.
-
set_default_fill_value
(value_type, value)[source]¶ Set the default fill value for value_type to value. Parameters ———- value_type is a string : real’,’complex’,’character’,’integer’,or ‘object’.
value should be a scalar or single-element array.
-
sort
(a, axis=- 1)[source]¶ The sort axis is replaced with a dummy axis.
Return a sorted copy of the masked array.
Equivalent to creating a copy of the array and applying the MaskedArray
sort()
method.Refer to
MaskedArray.sort
for the full documentationSee also
MaskedArray.sort
equivalent method
-
take
(a, myindices, axis=None)[source]¶ take(a, indices, axis=None) returns selection of items from a.
cdms2.avariable module¶
CDMS Variable objects, abstract interface
-
class
AbstractVariable
(parent=None, variableNode=None)[source]¶ Bases:
cdms2.cdmsobj.CdmsObj
,cdms2.slabinterface.Slab
Not to be called by users.
- Parameters
- variableNode
is the variable tree node, if any.
- parent
is the containing dataset instance.
-
crossSectionRegrid
(newLevel, newLatitude, missing=None, order=None, method='log')[source]¶ Return the variable regridded to new pressure levels and latitudes. The variable should be a function of lat, level, and (optionally) time.
- Parameters
- newLevelis an axis of the result pressure levels.
- newLatitudeis an axis of latitude values.
- methodOptional either “log” to interpolate in the log of pressure (default),
or “linear” for linear interpolation.
- missing and orderare as for regrid.CrossSectionRegridder.
-
decode
(ar)[source]¶ Decode compressed data.
- Parameters
- aris a masked array, scalar, or numpy.ma.masked.
-
generateGridkey
(convention, vardict)[source]¶ Determine if the variable is gridded.
- Parameters
- conventionMetadata convention class
- vardictVariable metedata
- Returns
- ((latname, lonname, order, maskname, class), lat, lon) if gridded
- (None, None, None) if not gridded
-
generateRectGridkey
(lat, lon)[source]¶ Determine if the variable is gridded, rectilinear.
- Parameters
- latlatitude axis
- lonlongitude axis
- Returns
- (latname, lonname, order, maskname, class) if gridded, None if not gridded.
-
getAxis
(n)[source]¶ Get the n-th axis.
- Parameters
- nAxis number
- Returns
- if n < 0: n = n + self.rank()
- self.getDomain()[n][0]
-
getAxisIndex
(axis_spec)[source]¶ Get the index of the axis specificed by axis_spec.
- Parameters
- axis_spec :
- Returns
- the axis index or -1 if no match is found.
-
getAxisList
(axes=None, omit=None, order=None)[source]¶ Get the list of axis objects
Notes
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
-
getAxisListIndex
(axes=None, omit=None, order=None)[source]¶ Get Axis List Index
- Returns
- a list of indices of axis objects
Notes
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.
-
getForecastTime
()[source]¶ Get the first forecast time dimension.
- Returns
- First forecast time dimension axis or None.
-
getGridIndices
()[source]¶ Get Grid Indices
- Returns
- a tuple of indices corresponding to the variable grid.
-
getLatitude
()[source]¶ Get the first latitude dimension.
- Returns
- First latitude dimension axis or None.
-
getLevel
()[source]¶ Get the first vertical level dimension in the domain.
- Returns
- First vertical level dimension axis or None.
-
getLongitude
()[source]¶ Get the first longitude dimension.
- Returns
- First longitude dimension axis or None.
-
getMissing
(asarray=0)[source]¶ Get Missing
- Parameters
- asarray‘0’
- ‘1’numpy array
- Returns
- the missing value as a scalar, or as a numpy array if asarray==1
-
getOrder
(ids=0)[source]¶ Get Order
- Parameters
- id0 or 1
- Returns
- the order string, such as t, z, y, x (time, level, lat, lon).
- Notes
- 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.
-
getRegion
(*specs, **keys)[source]¶ Read a region of data. A region is an n-dimensional rectangular region specified in coordinate space.
- Parameters
- sliceis 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.
- EllipsisRepresents the full range of all dimensions bracketed by non-Ellipsis items.
- None, colonRepresents the full range of one dimension.
- Notes
- 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’.
-
getSlice
(*specs, **keys)[source]¶ getSlice takes arguments of the following forms and produces a return array.
- Parameters
- rawif set to 1, return numpy.ma only
- squeezeif set to 1, eliminate any dimension of length 1
- gridif given, result is regridded ont this grid.
- orderif given, result is permuted into this order
- numericSqueezeif index slice is given, eliminate that dimension.
- isitemif given, result is return as a scaler for 0-D data
- Notes
- 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
- #. `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 (1)-(5) above.
- There must be no conflict between the positional arguments and
- the keywords.
- In (1)-(5) negative numbers are treated as offsets from the end
- of that dimension, as in normal Python indexing.
-
getValue
(squeeze=1)[source]¶ Get the entire set of values.
- Returns
- All values and elimite the 1-D dimension.
-
hasCellData
()[source]¶ 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.
-
info
(flag=None, device=None)[source]¶ Write info about slab; include dimension values and weights if flag
-
pressureRegrid
(newLevel, missing=None, order=None, method='log')[source]¶ Return the variable regridded to new pressure levels. The variable should be a function of lat, lon, pressure, and (optionally) time.
- Parameters
- newLevelis an axis of the result pressure levels.
- methodis optional, either log to interpolate in the log of pressure (default),
or linear for linear interpolation.
- missing and orderare as for regrid.PressureRegridder.
-
regrid
(togrid, missing=None, order=None, mask=None, **keywords)[source]¶ return self regridded to the new grid. One can use the regrid2.Regridder optional arguments as well.
Example
>>> new_cdmsVar = cdmsVar.regrid(newGrid) # uses libcf >>> new_cdmsVar = cdmsVar.regrid(newGrid, regridMethod = 'conserve', coordSys = 'cart')
- Parameters
- togridtogrid destination grid. CDMS grid
- missingOptional missing missing values
- orderOptional order axis order
- maskOptional mask grid/data mask
- **keyords
- keywords optional keyword arguments dependent on regridTool
- Returns
- regridded variable
-
reorder
(order)[source]¶ Reorder per the specification order.
- Parameters
- orderstring can be “tzyx” with all possible axes permutation.
- Returns
- New reordered variable.
-
select
(*args, **kwargs)¶ Selection of a subregion using selectors.
- Parameters
- rawif set to 1, return numpy.ma only
- squeezeif set to 1, eliminate any dimension of length 1
- gridif given, result is regridded ont this grid
- orderif given, result is permuted into this order
- Returns
- Subregion selected
-
setMissing
(value)[source]¶ Set the missing value.
- Parameters
- valuescalar, a single-valued numpy array, or None.
- Note :
- The value is cast to the same type as the variable.
-
specs2slices
(speclist, force=None)[source]¶ 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
The size of the speclist must be self.rank()
-
getMinHorizontalMask
(var)[source]¶ Get the minimum mask associated with ‘x’ and ‘y’ (i.e. with the min number of ones) across all axes
- Parameters
- varCDMS variable with a mask
- N/ANone
- Returns
- mask array or Noneif order ‘x’ and ‘y’ were not found
-
order2index
(axes, order)[source]¶ 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.
-
orderparse
(order)[source]¶ 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
cdms2.axis module¶
CDMS Axis objects
-
class
AbstractAxis
(parent, node)[source]¶ Bases:
cdms2.cdmsobj.CdmsObj
- Parameters
- parentcdms2.dataset.CdmsFile
Reference to
CdmsFile
containing axis.- nodeNone
Not used.
-
asComponentTime
(calendar=None)[source]¶ Returns values as component time if axis represents time.
- Parameters
- calendarcdtime.Calendar
Calendar used to convert relative time to component time. If
None
then the calendar set in attributes will be used. If this is not set then the default calendar will be used.
-
asDTGTime
(calendar=None)[source]¶ Returns values as DTG if axis represents time.
- Parameters
- calendarcdtime.Calendar
Calendar used to convert relative time to component time. If
None
then the calendar set in attributes will be used. If this is not set then the default calendar will be used.
-
asRelativeTime
(units=None)[source]¶ Returns values as relative time if axis represents time.
- Parameters
- unitsstr
Base units used in conversion of values.
-
asdatetime
(calendar=None)[source]¶ Returns values as
datetime.datetime
if axis represents time.- Parameters
- calendarcdtime.Calendar
Calendar used to convert relative time to component time. If
None
then the calendar set in attributes will be used. If this is not set then the default calendar will be used.
-
clone
(copyData=1)[source]¶ Clone axis.
- Parameters
- copyDataint
1 Will copy the data. 0 Will use a reference of the axis data.
- Returns
- cdms2.TransientAxis
Returns a
TransientAxis
containing a clone.
-
designateCircular
(modulo, persistent=0)[source]¶ Designates axis as circular.
- Parameters
- modulofloat
Length of cycle.
- persistent(bool/int)
True: Sets values in underlying file. Flase: Sets values in memory.
-
designateLatitude
(persistent=0)[source]¶ Designate axis as latitude.
Sets attribute
axis
to “Y”.- Parameters
- persistentint
0: Sets value in memory. 1: Sets value in underlying file.
-
designateLevel
(persistent=0)[source]¶ Designate axis as level.
Sets attribute
axis
to “Z”.- Parameters
- persistentint
0: Sets value in memory. 1: Sets value in underlying file.
-
designateLongitude
(persistent=0, modulo=360.0)[source]¶ Designate axis as longitude.
Sets attribute
axis
to “X”.- Parameters
- persistentint
0: Sets value in memory. 1: Sets value in underlying file.
- modulofloat
Sets topology of longitude. None will set topology to “linear”.
-
designateTime
(persistent=0, calendar=None)[source]¶ Designate axis as time.
Sets attribute
axis
to “T”.- Parameters
- persistentint
0: Sets value in memory. 1: Sets value in underlying file.
- calendarcdtime.Calendar
Sets the calendar for the time axis. See
cdtime
for valid calendars.
-
dtype
(name=None)¶ Gets numpy dtype.
- Parameters
- namestr
Name of the dtype
-
genGenericBounds
(width=1.0)[source]¶ Generate generic bounds.
Generate generic bounds. The axis values will be in the center of the bounds.
If the axis is latitude the endpoints of the bounds are capped at 90 and -90 respectively.
If the axis is longitude the endpoints of the bounds will be adjusted as to ensure they are circular.
- Parameters
- widthfloat
Width of the bounds when axis length is 1.
- Returns
- numpy.ndarray
2D (n,2) array containing bounds values.
Examples
>>> a1 = cdms2.createAxis(np.arange(0, 360, 1), id='lon') >>> a1.designateLongitude() >>> b1 = a1.genGenericBounds() >>> b1[0, 0], b1[-1, 1] (array([-0.5, 0.5]), array([358.5, 359.5]))
>>> a1 = cdms2.createAxis(np.arange(0, 360, 1), id='lon') >>> a1.designateLongitude() >>> b1 = a1.genGenericBounds() >>> b1[0, 0], b1[-1, 1] (array([90.5, 89.5]), array([-88.5, -89.5]))
-
getBounds
(isGeneric=None)[source]¶ Gets axis bounds.
- Parameters
- isGenericbool
If True generic bounds will be generated otherwise bounds in file be returned.
-
getBoundsForDualGrid
(dualGrid)[source]¶ Get explicit bounds for dual grid.
- Parameters
- dualGridbool
True if targetting dual grids otherwise False.
- Returns
- numpy.ndarray
If bounds are explicit and
dualGrid
is True then the explicit bounds are returned otherwiseNone
is.If bounds are no explicit and
dualGrid
is False then the bounds are returned otheriseNone
is.
-
getCalendar
()[source]¶ Gets calendar for axis.
If the axis represents time then the calendar is return if stored in the attributes.
- Returns
- cdtime.Calendar
Returns the calendar for the axis if defined otherwise
None`
-
getExplicitBounds
()[source]¶ Gets explicit bounds.
- Returns
- numpy.ndarray
Returns bounds if they are cells otherise
None
is returned.
-
getModulo
()[source]¶ Get axis modulo.
- Returns
- float
The modulo value for the axis if axis is circular.
-
getModuloCycle
()[source]¶ Gets axis modulo.
Defaults to 360.0 if not store in attributes.
- Returns
- float
The modulo value for the axis.
-
idtaxis
= {}¶
-
info
(flag=None, device=None)[source]¶ Write info about axis; include dimension values and weights if flag
-
isCircular
()[source]¶ Checks if axis is circular.
Checks for attribute “realtopology” first. If “realtopology” is not present then the data is checked. Attribute “realtopology” is set from the result of checking the data.
- Returns
- bool
True if axis is circular otherwise False.
-
isCircularAxis
()[source]¶ Superficial check if axis is circular.
- Returns
- (bool/int)
True if axis topology is set to circular. False if axis topology is not circular. 1 if axis is longitude. 0 if not circular.
-
isForecast
()[source]¶ Checks if axis is forecast.
- Returns
- bool
True if axis is forecast otherwise False.
-
isForecastTime
()[source]¶ Checks if axis is forecast.
- Returns
- bool
True if axis is forecast otherwise False.
-
isLatitude
()[source]¶ Checks if axis is latitude.
- Returns
- bool
True if axis is latitude otherwise false.
-
isLongitude
()[source]¶ Checks if axis is longitude.
- Returns
- bool
True if axis is longitude otherwise False.
-
listall
(all=None)[source]¶ List axis information.
- Parameters
- allbool
If True values and bounds will be printed.
- Returns
- str
Returns a string with all the information about the axis.
-
mapInterval
(interval, indicator='ccn', cycle=None)[source]¶ 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
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.
- Parameters
- internvaltuple of float, float, str (optional), float (optional)
(x, y) First and last value to map. (x, y, indicator) First and last value to map with indicator for handling endpoints. (x, y, indicator, cycle) First and last value to map with endpoint indicator and cycle length.
- indicatorstr
String indicator describing how to handle interval endpoints.
- cyclefloat
Length of cycle to use when mapping interval.
- Returns
- The corresponding index interval (i,j), where i<j, indicating
- the half-open index interval [i,j), or None if the intersection is empty.
- For an axis which is circular (self.topology == ‘circular’), [i,j)
- is interpreted as follows (where N = len(self)):
if j<=N, the interval does not wrap around the axis endpoint ..
if j>N, the interval wraps around, and is equivalent to the two consecutive intervals [i,N), [0,j-N)
- 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.
-
mapIntervalExt
(interval, indicator='ccn', cycle=None, epsilon=None)[source]¶ Extended
mapInterval
.See
mapInterval
for full documentation.- Parameters
- internvaltuple of float, float, str (optional), float (optional)
(x, y) First and last value to map. (x, y, indicator) First and last value to map with indicator for handling endpoints. (x, y, indicator, cycle) First and last value to map with endpoint indicator and cycle length.
- indicatorstr
String indicator describing how to handle interval endpoints.
- cyclefloat
Length of cycle to use when mapping interval.
- epsilonNot use.
- Returns
- int, int, int
Returns tuple containing the first and last index along with the stride.
-
setBounds
(bounds)[source]¶ Sets the bounds for the axis.
- Parameters
- boundsnumpy.ndarray
2D array containing bounds for the axis.
-
setCalendar
(calendar, persistent=1)[source]¶ Sets calendar for axis.
- Parameters
- calendarcdtime.Calendar
Calendar to set for the axis.
- persistent(bool/int)
Sets the calender in the underlying file if True otherwise its set in memory.
-
property
shape
¶
-
subAxis
(i, j, k=1, wrap=True)¶ Returns subaxis.
- Parameters
- iint
Positive start index.
- jint
Positive stop index.
- kint
Positive/Negative step value.
- wrapbool
True if subaxis can be wrapper otherwise False to prevent wrapping.
- Returns
- cdms2.TransientAxis
Returns
TransientAxis
containing sub-axis.
-
subaxis
(i, j, k=1, wrap=True)[source]¶ Returns subaxis.
- Parameters
- iint
Positive start index.
- jint
Positive stop index.
- kint
Positive/Negative step value.
- wrapbool
True if subaxis can be wrapper otherwise False to prevent wrapping.
- Returns
- cdms2.TransientAxis
Returns
TransientAxis
containing sub-axis.
-
toRelativeTime
(units, calendar=None)[source]¶ Converts values in-place to relative time.
- Parameters
- unitsstr
Base units used converting component to relative values.
- calendarcdtime.Calendar
Calendar used to convert relative time to component time. If
None
then the calendar set in attributes will be used. If this is not set then the default calendar will be used.
-
class
Axis
(parent, axisNode=None)[source]¶ Bases:
cdms2.axis.AbstractAxis
Base Axis class.
- Parameters
- parentcdms2.CdmsFile
Underlying file object.
- axisNodexml.etree.Element
Xml element for axis.
-
getBounds
(isGeneric=None)[source]¶ Get axis bounds.
If bounds are not available and you want them generated set the correct behavior using
setAutoBounds
.- Parameters
- isGenericlist of bool
First value is set True if bounds are generated.
- Returns
- numpy.ndarray
Returns bounds if available, generates bounds if
setAutoBounds
has been set accordingly otheriseNone
is returned.
-
getCalendar
()[source]¶ Gets calendar for axis.
If the axis represents time then the calendar is return if stored in the attributes.
- Returns
- cdtime.Calendar
Returns the calendar for the axis if defined otherwise
None`
-
class
FileAxis
(parent, axisname, obj=None)[source]¶ Bases:
cdms2.axis.AbstractAxis
Axis stored in a file.
- Parameters
- parentcdms2.CdmsFile
Underlying file.
- axisnamestr
Name of the axis.
- obj
-
getBounds
(isGeneric=None)[source]¶ Gets axis bounds.
- Parameters
- isGenericbool
If True generic bounds will be generated otherwise bounds in file be returned.
-
getCalendar
()[source]¶ Gets calendar for axis.
If the axis represents time then the calendar is return if stored in the attributes.
- Returns
- cdtime.Calendar
Returns the calendar for the axis if defined otherwise
None`
-
getExplicitBounds
()[source]¶ Gets explicit bounds.
- Returns
- numpy.ndarray
Returns bounds if they are cells otherise
None
is returned.
-
class
FileVirtualAxis
(parent, axisname, axislen)[source]¶ Bases:
cdms2.axis.FileAxis
Virual FileAxis.
- Parameters
- parentCdmsFile
Underlying file.
- axisnamestr
Name of the axis.
- axislenint
Length of the axis.
-
class
TransientAxis
(data, bounds=None, id=None, attributes=None, copy=0, genericBounds=False)[source]¶ Bases:
cdms2.axis.AbstractAxis
Axis in memory.
- Parameters
- datanumpy.ndarray
Array with data for axis.
- boundsnumpy.ndarray
2D array containing bounds, should be shaped (N,2).
- idstr
Identifier for axis.
- attributesdict
Mapping of attribute names and values.
- copyint
1: Store copy of data 0: Store reference to data
- genericBoundsbool
If
True
and bounds isNone
generic bounds will be generated.
-
axis_count
= 0¶
-
getBounds
(isGeneric=None)[source]¶ Gets axis bounds.
- Parameters
- isGenericbool
If True generic bounds will be generated otherwise bounds in file be returned.
-
getExplicitBounds
()[source]¶ Gets explicit bounds.
- Returns
- numpy.ndarray
Returns bounds if they are cells otherise
None
is returned.
-
setBounds
(bounds, persistent=0, validate=0, index=None, boundsid=None, isGeneric=False)[source]¶ Sets axis bounds.
If
bounds
is None then generic bounds will be generated. SeegenGenericBounds
for details.- Parameters
- boundsnumpy.ndarray
2D array containing bounds for axis.
- persistentint
0: Stores bounds in memory 1: Stores bounds in underlying file.
- validateint
0: No validation 1: Validate bounds
- index :
Not used.
- boundsid :
Not used.
- isGenericbool
True if bounds are generic.
-
class
TransientVirtualAxis
(axisname, axislen)[source]¶ Bases:
cdms2.axis.TransientAxis
Virtual in-memory axis.
- Parameters
- axisnamestr
Name of the axis.
- axislenint
Length of the axis.
-
clone
(copyData=1)[source]¶ Clone axis.
- Parameters
- copyDataint
1 Will copy the data. 0 Will use a reference of the axis data.
- Returns
- cdms2.TransientAxis
Returns a
TransientAxis
containing a clone.
-
allclose
(ax1, ax2, rtol=1e-05, atol=1e-08)[source]¶ All close
- Parameters
- ax1, ax2array_like
- Returns
- bool
True if all elements of axes ax1 and ax2 are close, in the sense of numpy.ma.allclose.
- See Alsoall, 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
-
axisMatchAxis
(axes, specifications=None, omit=None, order=None)[source]¶ Match a list of axes following a specification or list of specificatons, and a specification or list of specifications 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.
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.
- Returns
- A list of axes that 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.
-
axisMatchIndex
(axes, specifications=None, omit=None, order=None)[source]¶ Match a list of axes following a specification or list of specificatons, and a specification or list of specifications 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.
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.
- Returns
- 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.
-
axisMatches
(axis, specification)[source]¶ Axis Matches
- Parameters
- axisSee note below
- specificationsSee note below
- Returns
- 1 or 0 depending on whether axis matches the specification.
- Notes
- Specification must be one of:
- 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.
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.
- 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.
-
concatenate
(axes, id=None, attributes=None)[source]¶ Concatenate multiple axes including boundaries.
- Parameters
- axesAxes to concatenate
- idNew axis identification (default None)
- attributesAttributes to attached to the new Axis
- Returns
- Transient axis.
-
createAxis
(data, bounds=None, id=None, copy=0, genericBounds=False)[source]¶ Creates an axis.
To enabled automatic bounds generation see
setAutoBounds
.- Parameters
- data(list/
numpy.ndarray
) Values for axis.
- bounds
numpy.ndarray
2D array containing boundaries for
data
.- idstr
Axis identifier.
- copyint
0: Stores reference of data. 1: Stores copy of data.
- genericBoundsbool
True will create generic bounds if
bounds
is None.
- data(list/
- Returns
- cdms2.TransientAxis
Returns a
TransientAxis
containing data.
-
createEqualAreaAxis
(nlat)[source]¶ Creates an equal area axis.
- Parameters
- nlatint
Number of latitudes to generate.
- Returns
- cdms2.TransientAxis
TransientAxis
containing equal area axis ofnlat
.
-
createGaussianAxis
(nlat)[source]¶ Creates Guassian Axis.
- Parameters
- nlatint
Number of latitudes to generate.
- Returns
- ——
- cdms2.TransientAxis
TransientaAxis
containing guassian axis ofnlat
.
-
createUniformLatitudeAxis
(startLat, nlat, deltaLat)[source]¶ Creates a uniform latitude axis.
- Parameters
- startLatfloat
Starting latitude value.
- nlat :
Number of latitudes.
- deltaLatfloat
Difference between each latitude point.
- Returns
- cdms2.TransientAxis
TransientAxis
containing uniform latitude axis.
-
createUniformLongitudeAxis
(startLon, nlon, deltaLon)[source]¶ Creates a uniform longitude axis.
- Parameters
- startLonfloat
Starting longitude value.
- nlonint
Number of longitudes.
- deltaLonfloat
Difference between each longitude point.
- Returns
- cdms2.TransientAxis
TransientAxis
containing uniform longitude axis.
-
isOverlapVector
(vec1, vec2, atol=1e-08)[source]¶ Is Overlap Vector
- Parameters
- vec1Input arrays to compare
- vec2Input arrays to compare
- atolfloat, 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]
-
isSubsetVector
(vec1, vec2, tol)[source]¶ Checks if
vec1
is a subset ofvec2
.- Parameters
- vec1(cdms2.TransientAxis, cdms2.FileAxis, numpy.ndarray)
Subset data.
- vec2(cdms2.TransientAxis, cdms2.FileAxis, numpy.ndarray)
Superset data.
- tolfloat
Tolerance used when checking for subset.
- Returns
- (bool/int), int
First value of
True
denotesvec1
is a subset ofvec2
. A value of 0 orFalse
denotes the opposite.Second value is the starting index of
vec1
invec2
if it is a subset.
-
lookupArray
(ar, value)[source]¶ Lookup value in array ar.
- Parameters
- arInput array
- valueValue 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)
-
mapLinearExt
(axis, bounds, interval, indicator='ccn', epsilon=None, stride=1, wrapped=0)[source]¶ 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 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 how the intersection of the interval and axis is treated:
‘n’ - the node is in the interval ‘b’ - the interval intersects the cell bounds ‘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<j, indicating the
- half-open index interval [i,j), or None if the intersection is empty.
-
mapLinearIntersection
(xind, yind, iind, aMinusEps, aPlusEps, bPlusEps, bMinusEps, boundLeft, nodeSubI, boundRight)[source]¶ Map Linear Intersection
- Parameters
- xindc’ if (a,b) is closed on the left, ‘o’ if open,
- yindsame 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
-
setAutoBounds
(mode)[source]¶ Sets AutoBounds behavior.
Automatically generates axis and grid boundaries when
getBounds
is called.- Parameters
- mode(str/int)
0 : ‘off’ (No bounds will be generated) 1 : ‘on’ (Generate bounds) 2 : ‘grid’ (Generate bounds for lat/lon grids only)
Notes
This only affects 1D axes.
cdms2.bindex module¶
Bin index for non-rectilinear grids
-
bindexHorizontalGrid
(latlin, lonlin)[source]¶ Create a bin index for a horizontal grid.
- Parameters
- latlinlatlin is the raveled latitude values.
- latlonlonlin is the raveled longitude values.
- Returns
- resulting index.
-
intersectHorizontalGrid
(latspecs, lonspecs, latlin, lonlin, index)[source]¶ Intersect a horizontal grid with a lat-lon region.
- Parameters
- latspecslatitude specs as defined in the grid module.
- lonspecslongitude specs as defined in the grid module.
- latlinlatlin is the raveled latitude array.
- lonlinlonlin is the raveled longitude array.
- indexindex is the bin index as returned from bindex.
- Returns
- an array of indices, in latlin/lonlin, of the points in the intersection.
cdms2.cache module¶
cdms2.cdmsNode module¶
CDMS node classes
-
class
AttrNode
(name, value=None)[source]¶ Bases:
cdms2.cdmsNode.CdmsNode
-
class
AxisNode
(id, length, datatype='Long', data=None)[source]¶ Bases:
cdms2.cdmsNode.CdmsNode
-
class
DatasetNode
(id)[source]¶ Bases:
cdms2.cdmsNode.CdmsNode
-
class
DocLinkNode
(uri, content='')[source]¶ Bases:
cdms2.cdmsNode.CdmsNode
-
class
DomElemNode
(name, start=None, length=None)[source]¶ Bases:
cdms2.cdmsNode.CdmsNode
-
class
DomainNode
[source]¶ Bases:
cdms2.cdmsNode.CdmsNode
-
class
LinearDataNode
(start, delta, length)[source]¶ Bases:
cdms2.cdmsNode.CdmsNode
-
validDeltaTypes
= [<class 'int'>, <class 'float'>, <class 'list'>]¶
-
validStartTypes
= [<class 'int'>, <class 'float'>, <class 'comptime'>, <class 'reltime'>]¶
-
-
class
RectGridNode
(id, latitude, longitude, gridtype='unknown', order='yx', mask=None)[source]¶ Bases:
cdms2.cdmsNode.CdmsNode
-
class
VariableNode
(id, datatype, domain)[source]¶ Bases:
cdms2.cdmsNode.CdmsNode
-
class
XLinkNode
(id, uri, contentRole, content='')[source]¶ Bases:
cdms2.cdmsNode.CdmsNode
cdms2.cdmsURLopener module¶
Overrides urllib error handling
cdms2.cdmsobj module¶
CDMS module-level functions and definitions
-
class
CdmsObj
(node=None)[source]¶ Bases:
object
-
property
attributes
¶
-
dumpXML
(self, path=None, format=1)[source]¶ 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
- 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
-
matchPattern
(pattern, attribute, tag)[source]¶ 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.
- Parameters
- pattern: (str)
pattern
- attribute: (str/None)
attribute name
- tag: (str/None)
node tag
- Results
- ——-
result: (list)
-
matchone
(pattern, attname)[source]¶ 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.
-
searchPattern
(pattern, attribute, tag)[source]¶ 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)
-
searchPredicate
(predicate, tag)[source]¶ 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
-
searchone
(pattern, attname)[source]¶ 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
-
property
cdms2.cdscan module¶
-
addAttrs
(fobj, eattrs)[source]¶ Add extra attributes to file/dataset fobj. eattrs has the form [(varid,attr,value), (varid,attr,value), …] where if varid is ‘’, set the global attribute.
-
cloneWithLatCheck
(axis)[source]¶ Clone an axis, ensuring that latitudes (in degrees) are in the range [-90:90]
-
combineKeys
(mydict, typedict, timeIsLinear=0, referenceDelta=None, forecast=None)[source]¶ Combine dictionary keys into an axis. dict: (i,j) => (path, axisname) typedict is either timedict or levdict or fcdict. timeIsLinear is true iff time has a linear representation. referenceDelta is only used for error checks if timeIsLinear is true.
-
disambig
(name, mydict, num, comparator, value)[source]¶ Make an unique name from name, wrt to the keys in dictionary dict. Try using num first. comparator(value,dict[name]) returns 0 if equal, 1 if not.
-
initialize_filemap
(filemap, timedict, levdict, timeid, extendDset, splitOnTime, referenceTime, timeIsLinear, referenceDelta, splitOnLevel, dirlen, overrideCalendar)[source]¶
-
timeindex
(value, units, basetime, delta, calendar)[source]¶ Calculate (t - basetime)/delu where t = reltime(value, units) and delu is the time interval (delta, delunits) (e.g., 1 month).
-
useKeys
(mydict, typedict, timeIsLinear=0, referenceDelta=None, forecast=None)[source]¶ Use dictionary keys for an axis. This is like combineKeys (same arguments, same return values, was written by simplifying combineKeys), but this doesn’t do nearly so much because this is for an axis where there is no splitting across files, hence partitions are not needed. dict: (i,j) => (path, axisname) typedict is either timedict or levdict or fcdict. timeIsLinear is true iff time has a linear representation. referenceDelta is only used for error checks if timeIsLinear is true.
cdms2.cdurllib module¶
Customized URLopener
cdms2.cdurlparse module¶
Parse (absolute and relative) URLs. See RFC 1808: “Relative Uniform Resource Locators”, by R. Fielding, UC Irvine, June 1995.
cdms2.cdxmllib module¶
A parser for XML, using the derived class as static DTD.
-
class
TestXMLParser
(**kw)[source]¶ Bases:
cdms2.cdxmllib.XMLParser
cdms2.convention module¶
metadata conventions
-
class
CFConvention
(version)[source]¶ Bases:
cdms2.convention.COARDSConvention
-
current
= 'CF-1.0'¶
-
cdms2.dataset module¶
CDMS dataset and file objects
-
class
CdmsFile
(path, mode, hostObj=None, mpiBarrier=False)[source]¶ Bases:
cdms2.cdmsobj.CdmsObj
,cdms2.cudsinterface.cuDataset
-
copyAxis
(axis, newname=None, unlimited=0, index=None, extbounds=None)[source]¶ Copy axis description and data from another axis.
- Parameters
- axisaxis 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)
-
copyGrid
(grid, newname=None)[source]¶ 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)
- gridfile grid
(cdms2.grid.FileRectGrid/cdms2.hgrid.FileCurveGrid/cdms2.gengrid.FileGenericGrid)
- Returns
- file grid
- (cdms2.grid.FileRectGrid/cdms2.hgrid.FileCurveGrid/cdms2.gengrid.FileGenericGrid)
-
createAxis
(name, ar, unlimited=0)[source]¶ Create an axis.
- Parameters
- namestr is the string name of the Axis
- arnumpy.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).
-
createRectGrid
(id, lat, lon, order, type='generic', mask=None)[source]¶ 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)
-
createVariable
(name, datatype, axesOrGrids, fill_value=None)[source]¶ Create a variable.
- Parameters
- nameThe string name of the Variable
- datatypeA CDMS datatype or numpy typecode
- axesOrGridsis a list of axes, grids.
- fill_valuefill_value (cast into data type).
- Returns
- Return a variable object (cdms2.fvariable.FileVariable.
Notes
This should be generalized to allow subintervals of axes and/or grids.
-
createVariableCopy
(var, id=None, attributes=None, axes=None, extbounds=None, extend=0, fill_value=None, index=None, newname=None, grid=None)[source]¶ Define a new variable, with the same axes and attributes as in <var>.
- Parameters
- varvariable to copy (cdms2.tvariable.TransientVariable or cdms2.fvariable.FileVariable)
- attributesA dictionary of attributes. Default is var.attributes.
- axesThe list of axis objects. Default is var.getAxisList()
- extboundsBounds of the (portion of) the extended dimension being written.
- id or newnameString 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_valueThe missing value flag.
- indexThe extended dimension index for writting. The default index is determined
by lookup relative to the existing extended dimension.
- gridThe variable grid. none the value of var.getGrid() will used.
- Returns
- file variable (cdms2.fvariable.FileVariable)
-
createVirtualAxis
(name, axislen)[source]¶ Create an axis without any associated coordinate array. This axis is read-only. This is useful for the ‘bound’ axis.
- Parameters
- nameis the string name of the axis.
- axislenis the integer length of the axis.
- Returns
- axisfile axis whose id is name (cdms2.axis.FileVirtualAxis)
Notes
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.
-
getAxis
(id)[source]¶ Get the axis object with the given id. Returns None if not found.
- Parameters
- idid of the axis to get
- Returns
- file axis
-
getBoundsAxis
(n, boundid=None)[source]¶ Get a bounds axis of length n. Create the bounds axis if necessary.
- Parameters
- nbound id (bound_%d)
- Returns
- bounds axis
-
getGrid
(id)[source]¶ Get the grid object with the given id. Returns None if not found.
- Parameters
- idid of the grid to get
- Returns
- file axis
-
getVariable
(id)[source]¶ Get the variable object with the given id. Returns None if not found.
- Parameters
- idstr id of the variable to get
- Returns
- variable (cdms2.fvariable.FileVariable/None)
- file variable
-
getVariables
(spatial=0)[source]¶ Get a list of variable objects.
- Parameters
- spatialIf spatial=1 or True, only return those axes defined on latitude
or longitude, excluding weights and bounds
- Returns
- file variable.
-
matchPattern
(pattern, attribute, tag)[source]¶ 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.
- Parameters
- patternString expression.
- attributeAttribute Name. If None search all attributre.
- tagnode tag, if cdmsFile only match the current dataset otherwise match
all object matching the tag.
- Returns
- list of match patterns.
-
searchPattern
(pattern, attribute, tag)[source]¶ 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
- patternexpression pattern
- attributeattribute name
- tagnode tag
- Returns
- list of match pattern
-
searchPredicate
(predicate, tag)[source]¶ Apply a truth-valued predicate.
- Parameters
- predicatefunction use as predicate
- tagnode 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.
-
write
(var, attributes=None, axes=None, extbounds=None, id=None, extend=None, fill_value=None, index=None, typecode=None, dtype=None, pack=False)[source]¶ Write var to the file.
- Parameters
- varvariable to copy.
- attributesThe attribute dictionary for the variable. The default is var.attributes.
- axesThe list of file axes comprising the domain of the variable. The default is to
copy var.getAxisList().
- extboundsThe extended dimension bounds. Defaults to var.getAxis(0).getBounds().
- idThe 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_valueis the missing value flag.
- indexThe extended dimension index to write to. The default index is determined b
lookup relative to the existing extended dimension.
- dtypeThe numpy dtype.
- typecodeDeprecated, for backward compatibility only
- Returns
- File variable
Notes
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.
-
write_it_yourself
(obj)[source]¶ Tell obj to write itself to self (already open for writing), using its writeg method (AbstractCurveGrid has such a method, for example).
- Parameters
- objobject containing writeg, writeToFile or write method.
- Returns
- Nothing is returned.
Notes
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.
-
-
class
Dataset
(uri, mode, datasetNode=None, parent=None, datapath=None)[source]¶ Bases:
cdms2.cdmsobj.CdmsObj
,cdms2.cudsinterface.cuDataset
-
createRectGrid
(id, lat, lon, order, type='generic', mask=None)[source]¶ Create rectilinear grid.
- Parameters
- idstr
Identifier for the grid.
- lat(cdms2.TransientAxis, cdms2.FileAxis)
Latitude axis used to generate grid.
- lon(cdms2.TransientAxis, cdms2.FileAxis)
Longitude axis used to generate grid.
- orderstr
Order of axis e.g. “yx”
- mask(numpy.ndarray)
Array containing mask.
-
getLogicalCollectionDN
(base=None)[source]¶ Return the logical collection distinguished name of this dataset.
Notes
If <base> is defined, append it to the lc name.
-
getVariables
(spatial=0)[source]¶ Get a list of variable objects. If spatial=1, only return those axes defined on latitude or longitude, excluding weights and bounds.
-
matchPattern
(pattern, attribute, tag)[source]¶ 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.
- Parameters
- pattern: (str)
pattern
- attribute: (str/None)
attribute name
- tag: (str/None)
node tag
- Results
- ——-
result: (list)
-
searchPattern
(pattern, attribute, tag)[source]¶ 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)
-
searchPredicate
(predicate, tag)[source]¶ 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
-
-
createDataset
(path, template=None)[source]¶ Create a dataset.
- Parameters
- pathis the XML file name, or netCDF filename for simple file creation.
- templateis a string template for the datafile(s), for dataset creation.
- Returns
- writing file handle.
-
getMpiRank
()[source]¶ Return number of processor available.
- Returns
- rank or 0 if MPI is not enabled.
-
getNetcdfDeflateLevelFlag
()[source]¶ Get Net CDF Deflate Level Flag
- Returns
- NetCDF deflate level flag value.
-
getNetcdfUseNCSwitchModeFlag
()[source]¶ Get current netCDF define mode.
- Returns
- NetCDF define mode .
-
getNetcdfUseParallelFlag
()[source]¶ Get NetCDF UseParallel flag value.
- Parameters
- value0/1, False/True
- Returns
- No return value.
-
openDataset
(uri, mode='r', template=None, dods=1, dpath=None, hostObj=None)[source]¶ Open Dataset
- Parameters
- uristr
Filename to open.
- modestr
Mode to open file with. ‘r’: Read (default) ‘w’: Write ‘a’: Append
- templatestr
Template for the datafile(s) used for dataset creation.
- dodsint
Opens remote/local files when set to 1 or attempts to open local when set 0.
- dpathstr
Destination path.
- Returns
- cdms2.CdmsFile
Opened handle to file.
-
parseFileMap
(text)[source]¶ Parse a CDMS filemap.
- Parameters
- filemaplist [ varmap, varmap, …]
- varmaplist [ namelist, slicelist ]
- namelistlist [name, name, …]
- slicelistlist [indexlist, indexlist, ,,,]
- indexlistlist [i,j,k,l,path]
- Returns
- Parsing results.
-
parseIndexList
(text)[source]¶ Parse a string of the form [i,j,k,l,…,path].
- Parameters
- texti,j,k,l,… are indices or ‘-‘, and path is a filename. Coerce the indices to integers.
- Returns
- Parser results.
- n number of matches.
-
parselist
(text, f)[source]¶ Parse a string of the form [A, A, …].
- Parameters
- textInput String.
- ffunction which parses A and returns (A, nconsumed).
- Returns
- Parser results.
- n number of matches.
-
setCompressionWarnings
(value=None)[source]¶ 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.
-
setNetcdf4Flag
(value)[source]¶ Enable netCDF4 (HDF5) mode in libnetcdf.
- Parameters
- value0/1, False/True.
- Returns
- No return value.
-
setNetcdfClassicFlag
(value)[source]¶ Enable netCDF3 (classic) mode in libnetcdf.
- Parameters
- value0/1, False/True.
- Returns
- No return value.
-
setNetcdfDeflateFlag
(value)[source]¶ Enable/Disable NetCDF deflattion.
- Parameters
- value0/1, False/True.
- Returns
- No return value.
-
setNetcdfDeflateLevelFlag
(value)[source]¶ Sets NetCDF deflate level flag value
- Parameters
- valueDeflation Level 1-9.
- Returns
- No return value.
-
setNetcdfShuffleFlag
(value)[source]¶ Enable/Disable NetCDF shuffle.
- Parameters
- value0/1, False/True.
- Returns
- No return value.
-
setNetcdfUseNCSwitchModeFlag
(value)[source]¶ Tells cdms2 to switch constantly between netcdf define/write modes.
- Parameters
- value0/1, False/True.
- Returns
- No return value.
cdms2.error module¶
Error object for cdms module
cdms2.forecast module¶
CDMS Forecast
-
available_forecasts
(dataset_file, path='.')[source]¶ Available Forecasts
- Returns
- a list of forecasts (as their generating times) which are available
through the specified cdscan-generated dataset xml file.
- Note
The forecasts are given in 64-bit integer format, but can be converted to component times with the function two_times_from_one. This function may help in choosing the right arguments for initializing a “forecasts” (forecast set) object.
-
comptime
(t)[source]¶ Comptime
- Parameters
- Inputis a time representation, either as the long int used in the cdscan
script, or a string in the format “2010-08-25 15:26:00”, or as a cdtime comptime (component time) object.
- Outputis the same time a cdtime.comptime (component time).
-
class
forecast
(tau0time, dataset_list, path='.')[source]¶ Bases:
object
represents a forecast starting at a single time
- Parameters
- tau0timeis the first time of the forecast, i.e. the time at which tau=0.
- dataset_listis used to get the forecast file from the forecast time.
Notes
N.B. This is like a CdmsFile. Creating a forecast means opening a file, so later on you should call forecast.close() to close it.
-
class
forecasts
(dataset_file, forecast_times, path='.')[source]¶ Bases:
object
Represents a set of forecasts
-
forecast_axis
(varname, fcss=None)[source]¶ Forecast Axis
- Returns
- a tuple (axis,start,length,true_length) where axis is in the forecast direction.
Notes
If a list of forecasts be specified, the axis’ data will be limited to them.
-
forecast_times_to_list
(forecast_times)[source]¶ For internal list, translates a “forecast_times” argument of __init__ or other methods, into a list of times.
-
reduce_inplace
(min_time, max_time, openclosed='co')[source]¶ Reduce Inplace
Example
For a forecasts object f, f( min_time, max_time ) will reduce the scope of f, to forecasts whose start time t has min_time<=t<max_time. This is done in place, i.e. any other forecasts in f will be discarded. If slice notation were possible for forecasts (it’s not because we need too many bits to represent time), this function would do the same as f = f[min_time : max_time ]
The optional openclosed argument lets you specify the treatment of the endpoints min_time, max_time. The first character should be ‘c’ if you want to include min_time in the new scope of f, or ‘o’ to exclude it. Similarly, the second character should be ‘c’ to include max_time or ‘o’ to exclude it. Thus ‘co’ yields the default min_time<=t<max_time and ‘oo’ yields min_time<t<max_time.
If you don’t want to change the original “forecasts” object, just do copy.copy(forecasts) first.
Times can be the usual long integers, strings, or cdtime component times.
-
cdms2.fvariable module¶
CDMS File-based variables.
-
class
FileVariable
(parent, varname, cdunifobj=None)[source]¶ Bases:
cdms2.variable.DatasetVariable
A variable in a single file.
-
property
shape
¶
-
property
cdms2.gengrid module¶
CDMS Generic Grids
-
class
AbstractGenericGrid
(latAxis, lonAxis, id=None, maskvar=None, tempmask=None, node=None)[source]¶ Bases:
cdms2.hgrid.AbstractHorizontalGrid
-
checkAxes
(axes)[source]¶ Check Axes
- Returns
- 1 iff every element of self.getAxisList() is in the list ‘axes’.
-
flatAxes
()[source]¶ Flat Axes
- Returns
- (flatlat, flatlon) where flatlat is a 1D NumPy array
Notes
having the same length as the number of cells in the grid, similarly for flatlon.
-
getGridSlices
(domainlist, newaxislist, slicelist)[source]¶ Determine which slices in slicelist correspond to the lat/lon elements of the grid.
domainlist : is a list of axes of a variable.
newaxislist : is a list of result axes after the slicelist is applied to domainlist.
slicelist : is a list of slices.
All lists are of equal length.
Return value : is (newslicelist, gridaxislist) where
- newslicelistis the elements of slicelist that correspond to the grid, in the
preferred order of the grid.
- gridaxislistis the elements of newaxislist that correspond to the grid, in the
preferred order of the grid.
-
getMesh
(transpose=None)[source]¶ Generate a mesh array for the meshfill graphics method.
- Parameters
- ‘transpose’is for compatibility with other grid types, is ignored.
-
intersect
(spec)[source]¶ Intersect with the region specification.
- Parameters
- ‘spec’region specification of the form defined in the grid module.
- Returns
- (mask, indexspecs) where’mask’ is the mask of the result grid AFTER self
and region spec are interested. ‘indexspecs’ is a dictionary of index specifications suitable for slicing a variable with the given grid.
-
isClose
(g)[source]¶ Is Close
- Returns
- 1 iff g is a grid of the same type and shape.
Notes
A real element-by-element comparison would be too expensive here.
-
reconcile
(axes)[source]¶ Reconcile
- Returns
- a grid that is consistent with the axes, or None.
Notes
For curvilinear grids this means that the grid-related axes are contained in the ‘axes’ list.
-
property
shape
¶
-
subSlice
(*specs, **keys)[source]¶ Get a transient subgrid based on an argument list <specs> of slices.
-
-
class
DatasetGenericGrid
(latAxis, lonAxis, id, parent=None, maskvar=None, tempmask=None, node=None)[source]¶
-
class
FileGenericGrid
(latAxis, lonAxis, id, parent=None, maskvar=None, tempmask=None, node=None)[source]¶
-
class
TransientGenericGrid
(latAxis, lonAxis, id=None, maskvar=None, tempmask=None)[source]¶ Bases:
cdms2.gengrid.AbstractGenericGrid
-
grid_count
= 0¶
-
-
readScripGenericGrid
(fileobj, dims, whichType, whichGrid)[source]¶ Read a ‘native’ SCRIP grid file, returning a transient generic grid.
- Parameters
- fileobjis an open CDMS dataset or file object.
- dimsis the grid shape.
- whichTypeis the type of file, either “grid” or “mapping”
Notes
if whichType is “mapping”, whichGrid is the choice of grid, either “source” or “destination”
cdms2.git module¶
cdms2.grid module¶
CDMS Grid objects
-
class
AbstractGrid
(node)[source]¶ Bases:
cdms2.cdmsobj.CdmsObj
-
flatAxes
()[source]¶ Flat Axes
- Returns
- (flatlat, flatlon) where flatlat is a raveled NumPy array
having the same length as the number of cells in the grid, similarly for flatlon.
-
info
(flag=None, device=None)[source]¶ Write info about slab; include dimension values and weights if flag
-
-
class
AbstractRectGrid
(node)[source]¶ Bases:
cdms2.grid.AbstractGrid
Abstract Rect Grid
- Parameters
- AbstractRectGriddefines the interface for rectilinear grids
- gridswhich can be decomposed into 1-D latitude and longitude axes
-
flatAxes
()[source]¶ Flat Axes
- Returns
- flatlat, flatlon) where flatlat is a 1D NumPy array having the same
- length as the number of cells in the grid, similarly for flatlon.
-
gridtypes
= ['gaussian', 'uniform', 'equalarea', 'generic']¶
-
property
shape
¶
-
toCurveGrid
(gridid=None)[source]¶ Convert to a curvilinear grid.
- Parameters
- grididis the string identifier of the resulting curvilinear grid object.
-
class
FileRectGrid
(parent, gridname, latobj, lonobj, order, gridtype, maskobj=None, tempMask=None)[source]¶ Bases:
cdms2.grid.AbstractRectGrid
-
class
RectGrid
(parent, rectgridNode=None)[source]¶ Bases:
cdms2.grid.AbstractRectGrid
-
class
TransientRectGrid
(latobj, lonobj, order, gridtype, maskarray=None)[source]¶ Bases:
cdms2.grid.AbstractRectGrid
Grids that live in memory only.
-
createGaussianGrid
(nlats, xorigin=0.0, order='yx')[source]¶ Create a Gaussian grid, with shape (nlats, 2*nlats).
- Parameters
- nlatsis the number of latitudes.
- xoriginis the origin of the longitude axis
- orderis either “yx” or “xy”
-
createGenericGrid
(latArray, lonArray, latBounds=None, lonBounds=None, order='yx', mask=None)[source]¶ Not documented
-
createUniformGrid
(startLat, nlat, deltaLat, startLon, nlon, deltaLon, order='yx', mask=None)[source]¶ Not documented
-
setRegionSpecs
(grid, coordSpec, coordType, resultSpec)[source]¶ Modify a list of coordinate specifications, given a coordinate type and a specification for that coordinate.
- Parameters
- gridis the grid object to be associated with the region.
- coordSpecis a coordinate specification, having one of the forms:
x
(x,y)
(x,y,’co’)
(x,y,’co’,cycle)
‘:’ None
- coordTypeis one of CoordinateTypes
- resultSpecis a list of 4-tuples of the form (x,y,’co’,cycle), or None
if no spec for the corresponding dimension type. The function sets the appropriate coordinate in resultSpec, in the canonical form (x,y,’co’,cycle). A CDMSError exception is raised if the entry in resultSpec is not None.
Notes
That time coordinate types are not permitted.
cdms2.tvariable module¶
TransientVariable (created by createVariable) is a child of both AbstractVariable and the masked array class. Contains also the write part of the old cu interface.
-
class
TransientVariable
(data, typecode=None, copy=0, savespace=0, mask=False, fill_value=None, grid=None, axes=None, attributes=None, id=None, copyaxes=1, dtype=None, order='C', **kargs)[source]¶ Bases:
cdms2.avariable.AbstractVariable
,numpy.ma.core.MaskedArray
Variable in-memory.
To enabled automatic bounds generation see
setAutoBounds
.- Parameters
- datanumpy.ndarray
NDArray containing variable data.
- typecode(float, int, np.dtype)
Sets the dtype of the underlying masked array.
- copyint
0: Stores reference of data. 1: Stores copy of data.
- savespaceint
Deprecated.
- masknumpy.ndarray
Mask passed to the underlying masked array.
- fill_valuefloat
Sets the value to use when data is missing.
- grid
Sets the grid of the variable.
- axeslist of (cdms2.TransientAxis, cdms2.FileAxis)
Sets the list of axes associated with the variable.
- attributesdict
Mapping of attribute names and values.
- idstr
Identifier for the variable.
- copyaxesint
0: Stores reference to axes. 1: Stores copies of axes.
- dtype(float, int, np.dtype)
Sets the dtype of the underlying masked array.
- orderstr
Sets the order for the underlying masked array (`Masked Array`_).
- no_update_frombool
If
False
andaxes
is None, then axes will be generated fromdata
. IfFalse
andgrid
is None, then an attempt to get a grid from thedata
will be made. Set toTrue
will prevent the above behavior.- **kargs
Unused.
- .. _Masked Array:
https://numpy.org/doc/stable/reference/generated/numpy.ma.array.html
-
ascontiguous
()¶
-
clone
(copyData=1)[source]¶ Clone
- Parameters
- clone(self, copyData=1)
- Returns
- a copy of self as a transient variable.
- If copyData is 1 (default), make a separate copy of the data.
-
copy
(order='C')[source]¶ Return a copy of the array.
- Parameters
- order{‘C’, ‘F’, ‘A’, ‘K’}, optional
Controls the memory layout of the copy. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible. (Note that this function and
numpy.copy()
are very similar, but have different default values for their order= arguments.)
See also
numpy.copy
numpy.copyto
Examples
>>> x = np.array([[1,2,3],[4,5,6]], order='F')
>>> y = x.copy()
>>> x.fill(0)
>>> x array([[0, 0, 0], [0, 0, 0]])
>>> y array([[1, 2, 3], [4, 5, 6]])
>>> y.flags['C_CONTIGUOUS'] True
-
copydimension
(idim, other, jdim)[source]¶ Set idim dimension of self to variable other’s jdim’th This is for old cu compatibility. Use copyAxis for new code.
-
dumps
(*args, **kargs)[source]¶ Dumps Variable to a jason object, args are passed directly to json.dump
-
exposeHalo
(ghostWidth=1)[source]¶ Expose the halo to other processors. The halo is the region within the local MPI data domain that is accessible to other processors. The halo encompasses the edge of the data region and has thickness ghostWidth.
ghostWidth - width of the halo region (> 0)
-
fetchHaloData
(pe, side)[source]¶ Fetch the halo data from another processor. The halo side is a subdomain of the halo that is exposed to other processors. It is an error to call this method when MPI is not enabled. This is a collective method (must be called by all processes), which involves synchronization of data among all processors.
- Parameters
- pe:
processor owning the halo data. This is a no operation when pe is None.
- side:
a tuple of zeros and one +1 or -1. To access the “north” side for instance, set side=(1, 0), (-1, 0) to access the south side, (0, 1) the east side, etc.
- Note: collective, all procs must invoke this method. If some processors should not fetch then pass None for pe.
-
property
fill_value
¶ The filling value of the masked array is a scalar. When setting, None will set to a default based on the data type.
Examples
>>> for dt in [np.int32, np.int64, np.float64, np.complex128]: ... np.ma.array([0, 1], dtype=dt).get_fill_value() ... 999999 999999 1e+20 (1e+20+0j)
>>> x = np.ma.array([0, 1.], fill_value=-np.inf) >>> x.fill_value -inf >>> x.fill_value = np.pi >>> x.fill_value 3.1415926535897931 # may vary
Reset to default:
>>> x.fill_value = None >>> x.fill_value 1e+20
-
freeHalo
()[source]¶ Free the MPI windows attached to the halo. This must be called before MPI_Finalize.
-
getAxis
(n)[source]¶ Get the n-th axis.
- Parameters
- nAxis number
- Returns
- if n < 0: n = n + self.rank()
- self.getDomain()[n][0]
-
getHaloEllipsis
(side)[source]¶ Get the ellipsis for a given halo side.
- Parameters
- side:
a tuple of zeros and one +1 or -1. To access the “north” side for instance, set side=(1, 0), (-1, 0) to access the south side, (0, 1) the east side, etc. This does not involve any communication.
_:None
- Returns
- none if halo was not exposed (see exposeHalo)
-
getValue
(squeeze=1)[source]¶ Get the entire set of values.
- Returns
- All values and elimite the 1-D dimension.
-
iscontiguous
()[source]¶ Return a boolean indicating whether the data is contiguous.
- Parameters
- None
Examples
>>> x = np.ma.array([1, 2, 3]) >>> x.iscontiguous() True
iscontiguous returns one of the flags of the masked array:
>>> x.flags C_CONTIGUOUS : True F_CONTIGUOUS : True OWNDATA : False WRITEABLE : True ALIGNED : True WRITEBACKIFCOPY : False UPDATEIFCOPY : False
-
property
missing
¶
-
property
missing_value
¶
-
setMaskFromGridMask
(mask, gridindices)[source]¶ Set the mask for self, given a grid mask and the variable domain indices corresponding to the grid dimensions.
-
setdimattribute
(dim, field, value)[source]¶ Set the attribute named field from the dim’th dimension.
-
property
shape
¶ Tuple of array dimensions.
The shape property is usually used to get the current shape of an array, but may also be used to reshape the array in-place by assigning a tuple of array dimensions to it. As with numpy.reshape, one of the new shape dimensions can be -1, in which case its value is inferred from the size of the array and the remaining dimensions. Reshaping an array in-place will fail if a copy is required.
See also
numpy.reshape
similar function
ndarray.reshape
similar method
Examples
>>> x = np.array([1, 2, 3, 4]) >>> x.shape (4,) >>> y = np.zeros((2, 3, 4)) >>> y.shape (2, 3, 4) >>> y.shape = (3, 8) >>> y array([[ 0., 0., 0., 0., 0., 0., 0., 0.], [ 0., 0., 0., 0., 0., 0., 0., 0.], [ 0., 0., 0., 0., 0., 0., 0., 0.]]) >>> y.shape = (3, 6) Traceback (most recent call last): File "<stdin>", line 1, in <module> ValueError: total size of new array must be unchanged >>> np.zeros((4,2))[::2].shape = (-1,) Traceback (most recent call last): File "<stdin>", line 1, in <module> AttributeError: Incompatible shape for in-place modification. Use `.reshape()` to make a copy with the desired shape.
-
squeeze
(axis=None)¶ Remove single-dimensional entries from the shape of a.
Refer to numpy.squeeze for full documentation.
See also
numpy.squeeze
equivalent function
-
toVisit
(filename, format='Vs', sphereRadius=1.0, maxElev=0.1)[source]¶ Save data to file for postprocessing by the VisIt visualization tool filename: name of the file where the data will be saved format: ‘Vs’ for VizSchema, ‘VTK’ for VTK, … sphereRadius: radius of the earth maxElev: maximum elevation for representation on the sphere
-
to_dataframe
()[source]¶ Convert a TransientVariable into a pandas.DataFrame.
Transient variable the column of the DataFrame. The DataFrame is be indexed by the cartesian product of this Transient variable dimensions
-
variable_count
= 0¶
-
asVariable
(s, writeable=1)[source]¶ As Variable
- Returns
- s if s is a Variable; if writeable is 1,
- return s if s is a TransientVariable.
- If s is not a variable of
- the desired type, attempt to make it so and return that.
- If we fail raise CDMSError
-
createVariable
(*args, **kargs)[source]¶ Creates variable in-memory.
To enabled automatic bounds generation see
setAutoBounds
.- Parameters
- datanumpy.ndarray
NDArray containing variable data.
- typecode(float, int, np.dtype)
Sets the dtype of the underlying masked array.
- copyint
0: Stores reference of data. 1: Stores copy of data.
- savespaceint
Deprecated.
- masknumpy.ndarray
Mask passed to the underlying masked array.
- fill_valuefloat
Sets the value to use when data is missing.
- grid
Sets the grid of the variable.
- axeslist of (cdms2.TransientAxis, cdms2.FileAxis)
Sets the list of axes associated with the variable.
- attributesdict
Mapping of attribute names and values.
- idstr
Identifier for the variable.
- copyaxesint
0: Stores reference to axes. 1: Stores copies of axes.
- dtype(float, int, np.dtype)
Sets the dtype of the underlying masked array.
- orderstr
Sets the order for the underlying masked array (`Masked Array`_).
- no_update_frombool
If
False
andaxes
is None, then axes will be generated fromdata
. IfFalse
andgrid
is None, then an attempt to get a grid from thedata
will be made. Set toTrue
will prevent the above behavior.- *args
Url to JSON file if
fromJSON
is in kwargs.- **kargs
- fromJSONbool
Load variable from JSON.
- .. _Masked Array:
https://numpy.org/doc/stable/reference/generated/numpy.ma.array.html
Examples
>>> v1 = createVariable(np.random.random(size=(200,200)), typecode=float, fill_value=123)
>>> v2 = createVariable('data.json', fromJSON=True)
cdms2.variable module¶
DatasetVariable: Dataset-based variables
-
class
DatasetVariable
(parent, id, variableNode=None)[source]¶ Bases:
cdms2.avariable.AbstractVariable
Variable (parent, variableNode=None)
- Parameters
- variableNodeis the variable tree node, if any.
- parentis the containing dataset instance.
-
property
dtype
¶
-
expertPaths
(slist)[source]¶ Expert Paths
- Parameters
- expertPaths(self, slicelist) takes a list of slices
- Returns
- a 3-tuple (npart, dimensionlist, partitionSlices)
- Where
- npartis the number of partitioned dimensions: 0, 1, or 2;
- dimensionlistis a tuple of length npart, having the dimension numbers of the partitioned dimensions;
- partitionSlicesis the list of file-specific (filename, slice) corresponding
- to the paths and slices within the files to be read.
- The exact form of partitionSlices depends on the value of npart
- npartpartitionSlices
- 0(filename,slicelist)
- 1[(filename,slicelist),…,(filename,slicelist)]
- 2[[(filename,slicelist),…,(filename,slicelist)]
[(filename,slicelist),…,(filename,slicelist)] [(filename,slicelist),…,(filename,slicelist)]]
Notes
A filename of None indicates that no file was found with data corresponding to the slicelist.
If partitionSlices is None, the slicelist does not intersect the domain.
An empty partitionSlices [] means that the variable is zero-dimensional.
-
genMatch
(axis, interval, matchnames)[source]¶ Helper function for expertPaths.
- Parameters
- axisis a partitioned axis, either time or vertical level or forecast.
- intervalis an index interval (istart, iend).
- matchnamesis a partially filled list [id, timestart, timeend, levstart, levend, fc] If a filemap
is used, matchnames has indices, otherwise has coordinates.
- Functionmodifies matchnames based on axis and interval, returns the modified matchnames tuple.
-
getAxis
(n)[source]¶ Get the n-th axis.
- Parameters
- nAxis number
- Returns
- if n < 0: n = n + self.rank()
- self.getDomain()[n][0]
-
getFilePath
(matchnames, template)[source]¶ Lookup or generate the file path, depending on whether a filemap or template is present.
-
getPartition
(axis)[source]¶ Get the partition attribute for this variable, axis.
- Parameters
- axisis either a time or level axis. If cdms_filemap is being used, get the
partition from the _varpart_ attribute, otherwise (for templating) use axis.partition.
-
initDomain
(axisdict, griddict)[source]¶ Must be called by whoever made this Variable to set up axes, grids.
-
property
shape
¶
Module contents¶
CDMS module-level API