from copy import deepcopy from functools import partial as functools_partial from re import match as re_match from re import findall as re_findall from textwrap import fill as textwrap_fill from itertools import izip from cPickle import dumps, loads, PicklingError from re import search as re_search from netCDF4 import default_fillvals as _netCDF4_default_fillvals from operator import truediv as truediv from operator import itruediv as itruediv from re import compile as re_compile from numpy import array as numpy_array from numpy import result_type as numpy_result_type from numpy import vectorize as numpy_vectorize from .flags import Flags from .functions import RTOL, ATOL, equals, set_equals from .functions import inspect as cf_inspect from .query import Query from .units import Units from .timeduration import TimeDuration from .data.data import Data _units_None = Units() docstring = { # ---------------------------------------------------------------- '{+chunksizes}': '''chunksizes: `dict` or `None`, optional Specify the chunk sizes for axes of the {+variable}. Axes are given by dictionary keys, with a chunk size for those axes as the dictionary values. A dictionary key may be an integer or a tuple of integers defining axes by position in the data array. Iln the special case of *chunksizes* being `None`, then chunking is set to the netCDF default. *Example:* To set the chunk size for first axes to 365: ``{0: 365}``. *Example:* To set the chunk size for the first and third data array axes to 100: ``{0: 100, 2: 100}``, or equivalently ``{(0, 2): 100}``. *Example:* To set the chunk size for the second axis to 100 and for the third axis to 5: ``{1: 100, 2: 5}``. *Example:* To set the chunking to the netCDF default: ``None``.''', # ---------------------------------------------------------------- '{+data-like}': '''A data-like object is any object containing array-like or scalar data which could be used to create a `cf.Data` object. *Example:* Instances, ``x``, of following types are all examples of data-like objects (because ``cf.Data(x)`` creates a valid `cf.Data` object): :py:obj:`int`, :py:obj:`float`, :py:obj:`str`, :py:obj:`tuple`, :py:obj:`list`, `numpy.ndarray`, `cf.Data`, `cf.Coordinate`, `cf.Field`.''', # ---------------------------------------------------------------- '{+data-like-scalar}': '''A data-like scalar object is any object containing scalar data which could be used to create a `cf.Data` object. *Example:* Instances, ``x``, of following types are all examples of scalar data-like objects (because ``cf.Data(x)`` creates a valid `cf.Data` object): :py:obj:`int`, :py:obj:`float`, :py:obj:`str`, and scalar-valued `numpy.ndarray`, `cf.Data`, `cf.Coordinate`, `cf.Field`.''', # ---------------------------------------------------------------- '{+atol}': '''atol: `float`, optional The absolute tolerance for all numerical comparisons, By default the value returned by the `cf.ATOL` function is used.''', # ---------------------------------------------------------------- '{+rtol}': '''rtol: `float`, optional The relative tolerance for all numerical comparisons, By default the value returned by the `cf.RTOL` function is used.''', # ---------------------------------------------------------------- '{+axis_selection}': '''Axes are selected with the criteria specified by the keyword parameters. If no keyword parameters are specified then all axes are selected.''', # ---------------------------------------------------------------- '{+HDF_chunks}': '''Specify HDF5 chunks for the data array. Chunking refers to a storage layout where the data array is partitioned into fixed-size multi-dimensional chunks when written to a netCDF4 file on disk. Chunking is ignored if the data array is written to a netCDF3 format file. A chunk has the same rank as the data array, but with fewer (or no more) elements along each axis. The chunk is defined by a dictionary in which the keys identify axes and the values are the chunk sizes for those axes. If a given chunk size for an axis is larger than the axis size, then the size of the axis at the time of writing to disk will be used instead. If chunk sizes have been specified for some but not all axes, then the each unspecified chunk size is assumed to be the full size of its axis. If no chunk sizes have been set for any axes then the netCDF default chunk is used (http://www.unidata.ucar.edu/software/netcdf/docs/netcdf_perf_chunking.html). A detailed discussion of HDF chunking and I/O performance is available at https://www.hdfgroup.org/HDF5/doc/H5.user/Chunking.html and http://www.unidata.ucar.edu/software/netcdf/workshops/2011/nc4chunking. Basically, you want the chunks for each dimension to match as closely as possible the size and shape of the data block that users will read from the file.''', # ---------------------------------------------------------------- '{+item_selection}': '''Items are selected with the criteria specified by the keyword parameters. By default, if multiple criteria are given then the items will be the intersection of each keyword's selection (see the *match_and* parameter). If no keyword parameters are specified then all items are selected.''', # ---------------------------------------------------------------- '{+item_criteria}': '''There are two main types of item selection criteria: ============================ ================================== Selection criteria Parameters ============================ ================================== Attributes and CF properties *items* Data array axes *axes*, *axes_all*, *axes_subset*, *axes_superset*, *ndim* ============================ ==================================''', # ---------------------------------------------------------------- '{+items_criteria}': '''There are three main types of item selection criteria: ============================ ================================== Selection criteria Parameters ============================ ================================== Attributes and CF properties *items* Data array axes *axes*, *axes_all*, *axes_subset*, *axes_superset*, *ndim* Item role *role* ============================ ==================================''', # ---------------------------------------------------------------- '{+ndim}': '''ndim: optional {+Fef,}Select the items whose number of data array dimensions satisfy the given condition. A range of data numbers of array axes may be selected if *ndim* is a `cf.Query` object. *Example:* ``ndim=1`` selects items which span exactly one axis and ``ndim=cf.ge(2)`` selects items which span two or more axes (see `cf.ge`).''', # ---------------------------------------------------------------- '{+axes}': '''axes: optional {+Fef,}Select items which span at least one of the specified axes, taken in any order, and possibly others. Axes are defined by identfiying items of the field (such as dimension coordinate objects) or by specifying axis sizes. In the former case the selected axes are those which span the identified items. The axes are interpreted as those that would be returned by the field's `~cf.Field.axes` method, i.e. by ``f.axes(axes)`` or, if *axes* is a dictionary, ``f.axes(**axes)``. See `cf.Field.axes` for details. *Example:* To select items which span a time axis, and possibly others, you could set: ``axes='T'``. *Example:* To select items which span a latitude and/or longitude axes, and possibly others, you could set: ``axes=['X', 'Y']``. *Example:* To specify axes with size 19 you could set ``axes={'size': 19}``. To specify depth axes with size 40 or more, you could set: ``axes={'axes': 'depth', 'size': cf.ge(40)}`` (see `cf.ge`).''', # ---------------------------------------------------------------- '{+axes_subset}': '''axes_subset: optional {+Fef,}Select items whose data array spans all of the specified axes, taken in any order, and possibly others. The axes are those that would be selected by this call of the field's `~cf.Field.axes` method: ``f.axes(axes_subset)`` or, if *axes_subset* is a dictionary of parameters , ``f.axes(**axes_subset)``. Axes are defined by identfiying items of the field (such as dimension coordinate objects) or by specifying axis sizes. In the former case the selected axes are those which span the identified field items. See `cf.Field.axes` for details. *Example:* To select items which span a time axes, and possibly others, you could set: ``axes_subset='T'``. *Example:* To select items which span latitude and longitude axes, and possibly others, you could set: ``axes_subset=['X', 'Y']``. *Example:* To specify axes with size 19 you could set ``axes_subset={'size': 19}``. To specify depth axes with size 40 or more, you could set: ``axes_subset={'axes': 'depth', 'size': cf.ge(40)}`` (see `cf.ge`).''', # ---------------------------------------------------------------- '{+axes_superset}': '''axes_superset: optional {+Fef,}Select items whose data arrays span a subset of the specified axes, taken in any order, and no others. The axes are those that would be selected by this call of the field's `~cf.Field.axes` method: ``f.axes(axes_superset)`` or, if *axes_superset* is a dictionary of parameters, ``f.axes(**axes_superset)``. Axes are defined by identfiying items of the field (such as dimension coordinate objects) or by specifying axis sizes. In the former case the selected axes are those which span the identified field items. See `cf.Field.axes` for details. *Example:* To select items which span a time axis, and no others, you could set: ``axes_superset='T'``. *Example:* To select items which span latitude and/or longitude axes, and no others, you could set: ``axes_superset=['X', 'Y']``. *Example:* To specify axes with size 19 you could set ``axes_superset={'size': 19}``. To specify depth axes with size 40 or more, you could set: ``axes_superset={'axes': 'depth', 'size': cf.ge(40)}`` (see `cf.ge`).''', # ---------------------------------------------------------------- '{+axes_all}': '''axes_all: optional {+Fef,}Select items whose data arrays span all of the specified axes, taken in any order, and no others. The axes are those that would be selected by this call of the field's `~cf.Field.axes` method: ``f.axes(axes_all)`` or, if *axes_all* is a dictionary of parameters, ``f.axes(**axes_all)``. Axes are defined by identfiying items of the field (such as dimension coordinate objects) or by specifying axis sizes. In the former case the selected axes are those which span the identified field items. See `cf.Field.axes` for details. *Example:* To select items which span a time axis, and no others, you could set: ``axes_all='T'``. *Example:* To select items which span latitude and longitude axes, and no others, you could set: ``axes_all=['X', 'Y']``. *Example:* To specify axes with size 19 you could set ``axes_all={'size': 19}``. To specify depth axes with size 40 or more, you could set: ``axes_all={'axes': 'depth', 'size': cf.ge(40)}`` (see `cf.ge`).''', # ---------------------------------------------------------------- '{+role}': '''role: (sequence of) `str`, optional Select items of the given roles. Valid roles are: ======= ============================ role Items selected ======= ============================ ``'d'`` Dimension coordinate objects ``'a'`` Auxiliary coordinate objects ``'m'`` Cell measure objects ``'r'`` Coordinate reference objects ======= ============================ Multiple roles may be specified by a multi-character string or a sequence. *Example:* Selecting auxiliary coordinate and cell measure objects may be done with any of the following values of *role*: ``'am'``, ``'ma'``, ``('a', 'm')``, ``['m', 'a']``, ``set(['a', 'm'])``, etc.''', # ---------------------------------------------------------------- '{+exact}': '''exact: `bool`, optional {+Fef,}The *exact* parameter applies to the interpretation of string-valued conditions given by the *items* parameter. By default *exact* is False, which means that: * A string-valued condition is treated as a regular expression understood by the :py:obj:`re` module and an item is selected if its corresponding value matches the regular expression using the `re.match` method (i.e. if zero or more characters at the beginning of item's value match the regular expression pattern). * Units and calendar strings are evaluated for equivalence rather then equality (e.g. ``'metre'`` is equivalent to ``'m'`` and to ``'km'``). .. *Example:* To select items with with any units of pressure: ``f.{+name}('units:hPa')``. To select items with a standard name which begins with "air" and with any units of pressure: ``f.{+name}({'standard_name': 'air', 'units': 'hPa'})``. If *exact* is True then: * A string-valued condition is not treated as a regular expression and an item is selected if its corresponding value equals the string. * Units and calendar strings are evaluated for exact equality rather than equivalence (e.g. ``'metre'`` is equal to ``'m'``, but not to ``'km'``). .. *Example:* To select items with with units of hectopascals but not, for example, Pascals: ``f.{+name}('units:hPa', exact=True)``. To select items with a standard name of exactly "air_pressure" and with units of exactly hectopascals: ``f.{+name}({'standard_name': 'air_pressure', 'units': 'hPa'}, exact=True)``. Note that `cf.Query` objects provide a mechanism for overriding the *exact* parameter for individual values. *Example:* ``f.{+name}({'standard_name': cf.eq('air', exact=False), 'units': 'hPa'}, exact=True)`` will select items with a standard name which begins "air" but with units of exactly hectopascals (see `cf.eq`). *Example:* ``f.{+name}({'standard_name': cf.eq('air_pressure'), 'units': 'hPa'})`` will select items with a standard name of exactly "air_pressure" but with any units of pressure (see `cf.eq`).''', # ---------------------------------------------------------------- '{+match_and}': '''match_and: `bool`, optional By default *match_and* is True and{+,fef,} items are selected if they satisfy the all of the specified conditions. If *match_and* is False then items are selected if they satisfy at least one of the specified conditions. *Example:* To select items with identity beginning with "ocean" **and** two data array axes: ``f.{+name}('ocean', ndim=2)``. *Example:* To select items with identity beginning with "ocean" **or** two data array axes: ``f.{+name}('ocean', ndim=2, match_and=False)``.''', # ---------------------------------------------------------------- '{+inverse}': '''inverse: `bool`, optional If True then{+,fef,} select items other than those selected by all other criteria.''', # ---------------------------------------------------------------- '{+copy}': '''copy: `bool`, optional If True then a returned item is a copy. By default it is not copied.''', # ---------------------------------------------------------------- '{+key}': '''key: `bool`, optional If True then{+,fef,} return the domain's identifier for the selected item, rather than the item itself.''', # ---------------------------------------------------------------- '{+items}': '''items: optional {+Fef,}Select items whose attributes or CF properties satisfy the given conditions. The *items* parameter may be one, or a sequence, of: * `None` or an empty dictionary. All items are selected. This is the default. .. * A string specifying one of the CF coordinate types: ``'T'``, ``'X'``, ``'Y'`` or ``'Z'``. An item has an attribute for each coordinate type and is selected if the attribute for the specified type is True. *Example:* To select CF time items: ``items='T'``. .. * A string which identifies items based on their string-valued metadata. The value may take one of the following forms: ============== ======================================== Value Interpretation ============== ======================================== Contains ``:`` Selects on the CF property specified before the first ``:`` Contains ``%`` Selects on the attribute specified before the first ``%`` Anything else Selects on identity as returned by the item's `!identity` method ============== ======================================== By default the part of the string to be compared with an item is treated as a regular expression understood by the :py:obj:`re` module and an item is selected if its corresponding value matches the regular expression using the :py:obj:`re.match` method (i.e. if zero or more characters at the beginning of item's value match the regular expression pattern). See the *exact* parameter for details. *Example:* To select items with standard names which begin "lat": ``items='lat'``. *Example:* To select items with long names which begin "air": ``items='long_name:air'``. *Example:* To select items with netCDF variable names which begin "lon": ``items='ncvar%lon'``. *Example:* To select items with identities which end with the letter "z": ``items='.*z$'``. *Example:* To select items with long names which start with the string ".*a": ``items='long_name%\.\*a'``. .. * A dictionary which identifies properties of the items with corresponding tests on their values. An item is selected if **all** of the tests in the dictionary are passed. In general, each dictionary key is a CF property name with a corresponding value to be compared against the item's CF property value. If the dictionary value is a string then by default it is treated as a regular expression understood by the :py:obj:`re` module and an item is selected if its corresponding value matches the regular expression using the :py:obj:`re.match` method (i.e. if zero or more characters at the beginning of item's value match the regular expression pattern). See the *exact* parameter for details. *Example:* To select items with standard name of exactly "air_temperature" and long name beginning with the letter "a": ``items={'standard_name': cf.eq('air_temperature'), 'long_name': 'a'}`` (see `cf.eq`). Some key/value pairs have a special interpretation: ================== ==================================== Special key Value ================== ==================================== ``'units'`` The value must be a string and by default is evaluated for equivalence, rather than equality, with an item's `units` property, for example a value of ``'Pa'`` will match units of Pascals or hectopascals, etc. See the *exact* parameter. ``'calendar'`` The value must be a string and by default is evaluated for equivalence, rather than equality, with an item's `calendar` property, for example a value of ``'noleap'`` will match a calendar of noleap or 365_day. See the *exact* parameter. `None` The value is interpreted as for a string value of the *items* parameter. For example, ``items={None: 'air'}`` is equivalent to ``items='air'``, ``items={None: 'ncvar%pressure'}`` is equivalent to ``items='ncvar%pressure'`` and ``items={None: 'Y'}`` is equivalent to ``items='Y'``. ================== ==================================== *Example:* To select items with standard name starting with "air", units of temperature and a netCDF variable name of "tas" you could set ``items={'standard_name': 'air', 'units': 'K', None: 'ncvar%tas$'}``. .. * A domain item identifier (such as ``'dim1'``, ``'aux0'``, ``'msr2'``, ``'ref0'``, etc.). Selects the corresponding item. *Example:* To select the item with domain identifier "dim1": ``items='dim1'``. If *items* is a sequence of any combination of the above then the selected items are the union of those selected by each element of the sequence. If the sequence is empty then no items are selected.''', # ---------------------------------------------------------------- '{+axes, kwargs}': '''axes, kwargs: optional Select axes. The *axes* parameter may be one, or a sequence, of: * `None`. If no *kwargs* arguments have been set then all axes are selected. This is the default. .. * An integer. Explicitly selects the axis corresponding to the given position in the list of axes of the field's data array. *Example:* To select the third data array axis: ``axes=2``. To select the last axis: ``axes=-1``. .. * A :py:obj:`slice` object. Explicitly selects the axes corresponding to the given positions in the list of axes of the field's data array. *Example:* To select the last three data array axes: ``axes=slice(-3, None)`` .. * A domain axis identifier. Explicitly selects this axis. *Example:* To select axis "dim1": ``axes='dim1'``. .. * Any value accepted by the *items* parameter of the field's `items` method. Used in conjunction with the *kwargs* parameters to select the axes which span the items that would be identified by this call of the field's `items` method: ``f.items(items=axes, axes=None, **kwargs)``. See `cf.Field.items` for details. *Example:* To select the axes spanned by one dimensionsal time coordinates: ``f.{+name}('T', ndim=1)``. If *axes* is a sequence of any combination of the above then the selected axes are the union of those selected by each element of the sequence. If the sequence is empty then no axes are selected.''', # ---------------------------------------------------------------- '{+size}': '''size: optional Select axes whose sizes equal *size*. Axes whose sizes lie within a range sizes may be selected if *size* is a `cf.Query` object. *Example:* ``size=1`` selects size 1 axes. *Example:* ``size=cf.ge(2)`` selects axes with sizes greater than 1 (see `cf.ge`).''', # ---------------------------------------------------------------- '{+i}': '''i: `bool`, optional If True then update the {+variable} in place. By default a new {+variable} is created. In either case, a {+variable} is returned.''', # ---------------------------------------------------------------- } p = re_compile('(?<=.)([A-Z])') # E.g. DimensionCoordinate or Variable one = re_compile('(\[\+N\].*\n|\[\+1\])') many = re_compile('(\[\+1\].*\n|\[\+N\])') zero = re_compile('\[\+0\]') #first_char = re.compile('^(\s|\n)*(.)') fef = re_compile('{\+.*?[Ff]ef,?}(.)') fefx = re_compile('{\+(.*?)([Ff])ef,?}(.)') def _replacement(match): '''Used in a `re.sub` for for replacing: '{+Fef,}X' with 'For each field, x' and '{+,fef,}' with ', for each field,' ''' comma = match.group(1) if comma: comma += ' ' return comma+match.group(2)+"or each field, "+match.group(3).lower() def _replacement0(match): '''Used in a `re.sub` for for replacing: '{+Fef,}X' with 'For each field, X' and '{+,fef,}' with ', for each field,' ''' return match.group(1) def _update_docstring(name, f, attr_name): ''' ''' doc = f.__doc__ if doc is None: return name_lc = p.sub(r' \1', name).lower() doc = doc.replace('{+name}' , attr_name) doc = doc.replace('{+Variable}', name) doc = doc.replace('{+variable}', name_lc) kwargs = {} for arg in set(re_findall('{\+.*?}', doc)): if arg in ('{+Fef,}', '{+,fef,}', '{+fef}'): continue ds = docstring[arg].replace('{+name}', attr_name) ds = ds.replace('{+Variable}', name) ds = ds.replace('{+variable}', name_lc) doc = doc.replace(arg, ds) if name == 'FieldList': doc = many.sub('', doc) doc = zero.sub('[0]', doc) doc = fefx.sub(_replacement, doc) else: doc = one.sub('', doc) doc = zero.sub('', doc) doc = fef.sub(_replacement0, doc) f.__doc__ = doc #--- End: def class RewriteDocstringMeta(type): '''Modify docstrings. To do this, we intercede before the class is created and modify the docstrings of its attributes. This will not affect inherited methods, however, so we also need to loop through the parent classes. We cannot simply modify the docstrings, because then the parent classes' methods will have the wrong docstring. Instead, we must actually copy the functions, and then modify the docstring. ''' # http://www.jesshamrick.com/2013/04/17/rewriting-python-docstrings-with-a-metaclass/ def __new__(cls, name, parents, attrs): for attr_name in attrs: # skip special methods if attr_name.startswith('__'): continue # skip non-functions attr = attrs[attr_name] if not hasattr(attr, '__call__'): continue if not hasattr(attr, 'func_doc'): continue # update docstring _update_docstring(name, attr, attr_name) for parent in parents: for attr_name in dir(parent): # we already have this method if attr_name in attrs: continue # skip special methods if attr_name.startswith('__'): continue # get the original function and copy it a = getattr(parent, attr_name) # skip non-functions if not hasattr(a, '__call__'): continue f = getattr(a, '__func__', None) if f is None: continue # copy function attr = type(f)( f.func_code, f.func_globals, f.func_name, f.func_defaults, f.func_closure) doc = f.__doc__ # update docstring and add attr _update_docstring(name, attr, attr_name) attrs[attr_name] = attr # create the class obj = super(RewriteDocstringMeta, cls).__new__( cls, name, parents, attrs) return obj #--- End: class # ==================================================================== # # Variable object # # ==================================================================== class Variable(object): ''' Base class for storing a data array with metadata. A variable contains a data array and metadata comprising properties to describe the physical nature of the data. All components of a variable are optional. ''' __metaclass__ = RewriteDocstringMeta # Do not ever change this: _list = False # Define the reserved attributes. These are methods which can't be # overwritten, as well as a few attributes. _reserved_attrs = ('_reserved_attrs', '_insert_data' '_set_Data_attributes', 'binary_mask', 'chunk', 'clip', 'copy', 'cos', 'delprop', 'dump', 'equals', 'expand_dims', 'flip', 'getprop', 'hasprop', 'identity', 'match', 'name', 'override_units', 'select', 'setprop', 'sin', 'subspace', 'transpose', 'where', ) _special_properties = set(('units', 'calendar', '_FillValue', 'missing_value')) def __init__(self, properties={}, attributes=None, data=None, copy=True): ''' **Initialization** :Parameters: properties: dict, optional Initialize a new instance with CF properties from the dictionary's key/value pairs. attributes: dict, optional Provide the new instance with attributes from the dictionary's key/value pairs. data: cf.Data, optional Provide the new instance with an N-dimensional data array. copy: bool, optional If False then do not deep copy arguments prior to initialization. By default arguments are deep copied. ''' self._fill_value = None # _hasbounds is True if and only if there are cell bounds. self._hasbounds = False # True if and only if there is a data array stored in # self.Data self._hasData = False # Initialize the _private dictionary with an empty Units # object self._private = {'special_attributes': {}, 'simple_properties' : {}, } setprop = self.setprop if copy: for prop, value in properties.iteritems(): setprop(prop, deepcopy(value)) if attributes: for attr, value in attributes.iteritems(): setattr(self, attr, deepcopy(value)) # self.__dict__.update(deepcopy(attributes)) else: for prop, value in properties.iteritems(): setprop(prop, value) if attributes: # self.__dict__.update(attributes) for attr, value in attributes.iteritems(): setattr(self, attr, value) #--- End: if if data is not None: self.insert_data(data, copy=copy) else: # _hasData is True if and only if there is a data array # stored in self.Data self._hasData = False #--- End: def def __array__(self, *dtype): ''' ''' if self._hasData: return self.data.__array__(*dtype) raise ValueError("%s has no numpy.ndarray interface'" % self.__class__.__name__) #--- End: def def __contains__(self, value): ''' Called to implement membership test operators. x.__contains__(y) <==> y in x ''' return self.equals(value) #--- End: def def __data__(self): ''' Returns a new reference to self.data. ''' if self._hasData: return self.data raise ValueError( "{0} has no Data interface".format(self.__class__.__name__)) #--- End: def def __delattr__(self, attr): ''' x.__delattr__(attr) <==> del x.attr ''' if attr in self._reserved_attrs: raise AttributeError("Can't delete reserved attribute %r" % attr) super(Variable, self).__delattr__(attr) #--- End: def def __getitem__(self, index): ''' Called to implement evaluation of x[index]. x.__getitem__(index) <==> x[index] Not to be confused with `subspace`. ''' # if ((isinstance(index, slice) and len((None,)[index]) != 1) or # index not in (0, -1)): # raise IndexError("%s index out of range: %s" % # (self.__class__.__name__, index)) if index != 0 and index != -1: raise IndexError("%s index out of range: %s" % (self.__class__.__name__, index)) return self #--- End: def def __len__(self): ''' Called by the :py:obj:`len` built-in function. x.__len__() <==> len(x) Always returns 1. :Examples: >>> len(f) 1 ''' return 1 #--- End: def def __deepcopy__(self, memo): ''' Called by the :py:obj:`copy.deepcopy` standard library function. ''' return self.copy() #--- End: def def __add__(self, y): ''' The binary arithmetic operation ``+`` x.__add__(y) <==> x+y ''' return self._binary_operation(y, '__add__') #--- End: def def __iadd__(self, y): ''' The augmented arithmetic assignment ``+=`` x.__iadd__(y) <==> x+=y ''' return self._binary_operation(y, '__iadd__') #--- End: def def __radd__(self, y): ''' The binary arithmetic operation ``+`` with reflected operands x.__radd__(y) <==> y+x ''' return self._binary_operation(y, '__radd__') #--- End: def def __sub__(self, y): ''' The binary arithmetic operation ``-`` x.__sub__(y) <==> x-y ''' return self._binary_operation(y, '__sub__') #--- End: def def __isub__(self, y): ''' The augmented arithmetic assignment ``-=`` x.__isub__(y) <==> x-=y ''' return self._binary_operation(y, '__isub__') #--- End: def def __rsub__(self, y): ''' The binary arithmetic operation ``-`` with reflected operands x.__rsub__(y) <==> y-x ''' return self._binary_operation(y, '__rsub__') #--- End: def def __mul__(self, y): ''' The binary arithmetic operation ``*`` x.__mul__(y) <==> x*y ''' return self._binary_operation(y, '__mul__') #--- End: def def __imul__(self, y): ''' The augmented arithmetic assignment ``*=`` x.__imul__(y) <==> x*=y ''' return self._binary_operation(y, '__imul__') #--- End: def def __rmul__(self, y): ''' The binary arithmetic operation ``*`` with reflected operands x.__rmul__(y) <==> y*x ''' return self._binary_operation(y, '__rmul__') #--- End: def def __div__(self, y): ''' The binary arithmetic operation ``/`` x.__div__(y) <==> x/y ''' return self._binary_operation(y, '__div__') #--- End: def def __idiv__(self, y): ''' The augmented arithmetic assignment ``/=`` x.__idiv__(y) <==> x/=y ''' return self._binary_operation(y, '__idiv__') #--- End: def def __rdiv__(self, y): ''' The binary arithmetic operation ``/`` with reflected operands x.__rdiv__(y) <==> y/x ''' return self._binary_operation(y, '__rdiv__') #--- End: def def __floordiv__(self, y): ''' The binary arithmetic operation ``//`` x.__floordiv__(y) <==> x//y ''' return self._binary_operation(y, '__floordiv__') #--- End: def def __ifloordiv__(self, y): ''' The augmented arithmetic assignment ``//=`` x.__ifloordiv__(y) <==> x//=y ''' return self._binary_operation(y, '__ifloordiv__') #--- End: def def __rfloordiv__(self, y): ''' The binary arithmetic operation ``//`` with reflected operands x.__rfloordiv__(y) <==> y//x ''' return self._binary_operation(y, '__rfloordiv__') #--- End: def def __truediv__(self, y): ''' The binary arithmetic operation ``/`` (true division) x.__truediv__(y) <==> x/y ''' return self._binary_operation(y, '__truediv__') #--- End: def def __itruediv__(self, y): ''' The augmented arithmetic assignment ``/=`` (true division) x.__itruediv__(y) <==> x/=y ''' return self._binary_operation(y, '__itruediv__') #--- End: def def __rtruediv__(self, y): ''' The binary arithmetic operation ``/`` (true division) with reflected operands x.__rtruediv__(y) <==> y/x ''' return self._binary_operation(y, '__rtruediv__') #--- End: def def __pow__(self, y, modulo=None): ''' The binary arithmetic operations ``**`` and ``pow`` x.__pow__(y) <==> x**y ''' if modulo is not None: raise NotImplementedError("3-argument power not supported for %r" % self.__class__.__name__) return self._binary_operation(y, '__pow__') #--- End: def def __ipow__(self, y, modulo=None): ''' The augmented arithmetic assignment ``**=`` x.__ipow__(y) <==> x**=y ''' if modulo is not None: raise NotImplementedError("3-argument power not supported for %r" % self.__class__.__name__) return self._binary_operation(y, '__ipow__') #--- End: def def __rpow__(self, y, modulo=None): ''' The binary arithmetic operations ``**`` and ``pow`` with reflected operands x.__rpow__(y) <==> y**x ''' if modulo is not None: raise NotImplementedError("3-argument power not supported for %r" % self.__class__.__name__) return self._binary_operation(y, '__rpow__') #--- End: def def __mod__(self, y): ''' The binary arithmetic operation ``%`` x.__mod__(y) <==> x % y .. versionadded:: 1.0 ''' return self._binary_operation(y, '__mod__') #--- End: def def __imod__(self, y): ''' The binary arithmetic operation ``%=`` x.__imod__(y) <==> x %= y .. versionadded:: 1.0 ''' return self._binary_operation(y, '__imod__') #--- End: def def __rmod__(self, y): ''' The binary arithmetic operation ``%`` with reflected operands x.__rmod__(y) <==> y % x .. versionadded:: 1.0 ''' return self._binary_operation(y, '__rmod__') #--- End: def def __eq__(self, y): ''' The rich comparison operator ``==`` x.__eq__(y) <==> x==y ''' return self._binary_operation(y, '__eq__') #--- End: def def __ne__(self, y): ''' The rich comparison operator ``!=`` x.__ne__(y) <==> x!=y ''' return self._binary_operation(y, '__ne__') #--- End: def def __ge__(self, y): ''' The rich comparison operator ``>=`` x.__ge__(y) <==> x>=y ''' return self._binary_operation(y, '__ge__') #--- End: def def __gt__(self, y): ''' The rich comparison operator ``>`` x.__gt__(y) <==> x>y ''' return self._binary_operation(y, '__gt__') #--- End: def def __le__(self, y): ''' The rich comparison operator ``<=`` x.__le__(y) <==> x<=y ''' return self._binary_operation(y, '__le__') #--- End: def def __lt__(self, y): ''' The rich comparison operator ``<`` x.__lt__(y) <==> x x&y ''' return self._binary_operation(y, '__and__') #--- End: def def __iand__(self, y): ''' The augmented bitwise assignment ``&=`` x.__iand__(y) <==> x&=y ''' return self._binary_operation(y, '__iand__') #--- End: def def __rand__(self, y): ''' The binary bitwise operation ``&`` with reflected operands x.__rand__(y) <==> y&x ''' return self._binary_operation(y, '__rand__') #--- End: def def __or__(self, y): ''' The binary bitwise operation ``|`` x.__or__(y) <==> x|y ''' return self._binary_operation(y, '__or__') #--- End: def def __ior__(self, y): ''' The augmented bitwise assignment ``|=`` x.__ior__(y) <==> x|=y ''' return self._binary_operation(y, '__ior__') #--- End: def def __ror__(self, y): ''' The binary bitwise operation ``|`` with reflected operands x.__ror__(y) <==> y|x ''' return self._binary_operation(y, '__ror__') #--- End: def def __xor__(self, y): ''' The binary bitwise operation ``^`` x.__xor__(y) <==> x^y ''' return self._binary_operation(y, '__xor__') #--- End: def def __ixor__(self, y): ''' The augmented bitwise assignment ``^=`` x.__ixor__(y) <==> x^=y ''' return self._binary_operation(y, '__ixor__') #--- End: def def __rxor__(self, y): ''' The binary bitwise operation ``^`` with reflected operands x.__rxor__(y) <==> y^x ''' return self._binary_operation(y, '__rxor__') #--- End: def def __lshift__(self, y): ''' The binary bitwise operation ``<<`` x.__lshift__(y) <==> x< x<<=y ''' return self._binary_operation(y, '__ilshift__') #--- End: def def __rlshift__(self, y): ''' The binary bitwise operation ``<<`` with reflected operands x.__rlshift__(y) <==> y<>`` x.__lshift__(y) <==> x>>y ''' return self._binary_operation(y, '__rshift__') #--- End: def def __irshift__(self, y): ''' The augmented bitwise assignment ``>>=`` x.__irshift__(y) <==> x>>=y ''' return self._binary_operation(y, '__irshift__') #--- End: def def __rrshift__(self, y): ''' The binary bitwise operation ``>>`` with reflected operands x.__rrshift__(y) <==> y>>x ''' return self._binary_operation(y, '__rrshift__') #--- End: def def __abs__(self): ''' The unary arithmetic operation ``abs`` x.__abs__() <==> abs(x) ''' return self._unary_operation('__abs__') #--- End: def def __neg__(self): ''' The unary arithmetic operation ``-`` x.__neg__() <==> -x ''' return self._unary_operation('__neg__') #--- End: def def __invert__(self): ''' The unary bitwise operation ``~`` x.__invert__() <==> ~x ''' return self._unary_operation('__invert__') #--- End: def def __pos__(self): ''' The unary arithmetic operation ``+`` x.__pos__() <==> +x ''' return self._unary_operation('__pos__') #--- End: def def __repr__(self): ''' Called by the :py:obj:`repr` built-in function. x.__repr__() <==> repr(x) ''' name = self.name('') if self._hasData: dims = ', '.join([str(x) for x in self.shape]) else: dims = [] dims = '(%s)' % dims # Units if self.Units._calendar: units = self.Units._calendar else: units = getattr(self, 'units', '') return '' % (self.__class__.__name__, self.name(''), dims, units) #--- End: def def __str__(self): ''' Called by the :py:obj:`str` built-in function. x.__str__() <==> str(x) ''' return self.__repr__() #--- End: def # ================================================================ # Private methods # ================================================================ def _binary_operation(self, y, method): ''' Implement binary arithmetic and comparison operations on the {+variable}'s Data with the numpy broadcasting rules. It is intended to be called by the binary arithmetic and comparison methods, such as `!__sub__` and `!__lt__`. :Parameters: operation: `str` The binary arithmetic or comparison method name (such as ``'__imul__'`` or ``'__ge__'``). :Returns: new: `cf.+{Variable}` A new {+variable}, or the same {+variable} if the operation was in-place. :Examples: >>> u = cf.{+Variable}(data=cf.Data([0, 1, 2, 3])) >>> v = cf.{+Variable}(data=cf.Data([1, 1, 3, 4])) >>> w = u._binary_operation(u, '__add__') >>> print w.array [1 2 5 7] >>> w = u._binary_operation(v, '__lt__') >>> print w.array [ True False True True] >>> u._binary_operation(2, '__imul__') >>> print u.array [0 2 4 6] ''' if not self._hasData: raise ValueError( "Can't apply operator %s to a %s with no Data" % (method, self.__class__.__name__)) inplace = method[2] == 'i' xsn = self.getprop('standard_name', None) ysn = getattr(y, 'standard_name', None) x_Units = self.Units y_Units = getattr(y, 'Units', _units_None) if isinstance(y, self.__class__): y = y.Data if not inplace: new = self.copy(_omit_Data=True) new.Data = self.Data._binary_operation(y, method) #if not new.Data.Units.equivalent(original_units): # # this is coarse! # new.delprop('standard_name') # # if hasattr(new, 'history'): # history = [new.getprop('history')] # else: # history = [] # # history.append(new.getprop('standard_name')) # history.append(method) # # new.setprop('history', ' '.join(history)) ##--- End: if # return new else: new = self new.Data._binary_operation(y, method) #--- End: def new_Units = new.Data.Units if (not (new_Units.equivalent(x_Units) or new_Units.equivalent(y_Units)) or xsn is not None and ysn is not None and xsn != ysn): try: new.delprop('standard_name') except AttributeError: pass try: new.delprop('long_name') except AttributeError: pass try: del new.ncvar except AttributeError: pass try: del new.id except AttributeError: pass #--- End: if return new #--- End: def def _change_axis_names(self, dim_name_map): '''Change the axis names of the Data object. :Parameters: dim_name_map: `dict` :Returns: `None` :Examples: >>> f._change_axis_names({'0': 'dim1', '1': 'dim2'}) ''' if self._hasData: self.Data.change_axis_names(dim_name_map) #--- End: def def _conform_for_assignment(self, other): return other def _del_special_attr(self, attr): ''' ''' d = self._private['special_attributes'] if attr in d: del d[attr] return raise AttributeError("Can't delete non-existent %s attribute %r" % (self.__class__.__name__, attr)) #--- End: def def _dump_simple_properties(self, omit=(), _level=0): ''' :Parameters: omit: sequence of strs, optional Omit the given CF properties from the description. _level: int, optional :Returns: out: `str` :Examples: ''' indent1 = ' ' * _level string = [] # Simple properties simple = self._simple_properties() attrs = sorted(set(simple) - set(omit)) for attr in attrs: name = '%s%s = ' % (indent1, attr) value = repr(simple[attr]) indent = ' ' * (len(name)) if value.startswith("'") or value.startswith('"'): indent = '%(indent)s ' % locals() string.append(textwrap_fill(name+value, 79, subsequent_indent=indent)) #--- End: for return '\n'.join(string) #--- End: def def _equivalent_data(self, other, atol=None, rtol=None, copy=True): ''' :Parameters: transpose: dict, optional {+atol} {+rtol} copy: `bool`, optional If False then the *other* coordinate construct might get change in place. :Returns: out: `bool` Whether or not the two variables have equivalent data arrays. ''' if self._hasData != other._hasData: # add traceback return False if not self._hasData: return True data0 = self.data data1 = other.data units = data0.Units if not units.equivalent(data1.Units): # add traceback return if data0._shape != data1.shape: # add traceback return False if not units.equals(data1.Units): if copy: data1 = data1.copy() copy = False data1.Units = units #--- End: if if not data0.equals(data1, rtol=rtol, atol=atol, ignore_fill_value=True): # add traceback return False return True #--- End: def def _get_special_attr(self, attr): ''' ''' d = self._private['special_attributes'] if attr in d: return d[attr] raise AttributeError("%s doesn't have attribute %r" % (self.__class__.__name__, attr)) #--- End: def def _list_attribute(self, attr): return type(self)([getattr(f, attr) for f in self._list]) #--- End: def def _list_method(self, method, kwargs={}): if 'i' in kwargs and kwargs['i']: # In-place for f in self: getattr(f, method)(**kwargs) return self else: # New instance return type(self)([getattr(f, method)(**kwargs) for f in self]) #--- End: def def _parameters(self, d): del d['self'] if 'kwargs' in d: d.update(d.pop('kwargs')) return d #--- End: def def _parse_match(self, match): '''Called by `match` :Parameters: match: As for the *match* parameter of `match` method. :Returns: out: `list` ''' if not match: return () if isinstance(match, (basestring, dict, Query)): match = (match,) matches = [] for m in match: if isinstance(m, basestring): if ':' in m: # CF property (string-valued) m = m.split(':') matches.append({m[0]: ':'.join(m[1:])}) else: # Identity (string-valued) or python attribute # (string-valued) or axis type matches.append({None: m}) elif isinstance(m, dict): # Dictionary matches.append(m) else: # Identity (not string-valued, e.g. cf.Query). matches.append({None: m}) #--- End: for return matches #--- End: def def _query_set(self, values, exact=True): ''' ''' kwargs2 = self._parameters(locals()) if self._list: return self._list_method('_query_set', kwargs2) new = self.copy(_omit_Data=True) new.Data = self.Data._query_set(**kwargs2) return new #--- End: def def _query_contain(self, value): ''' ''' kwargs2 = self._parameters(locals()) if self._list: return self._list_method('_query_contain', kwargs2) new = self.copy(_omit_Data=True) new.Data = self.Data._query_contain(**kwargs2) return new #--- End: def def _query_wi(self, value0, value1): ''' ''' kwargs2 = self._parameters(locals()) if self._list: return self._list_method('_query_wi', kwargs2) new = self.copy(_omit_Data=True) new.Data = self.Data._query_wi(value0, value1) return new #--- End: def def _query_wo(self, value0, value1): ''' ''' kwargs2 = self._parameters(locals()) if self._list: return self._list_method('_query_wo', kwargs2) new = self.copy(_omit_Data=True) new.Data = self.Data._query_wo(value0, value1) return new #--- End: def def _simple_properties(self): return self._private['simple_properties'] #--- End: def def _set_special_attr(self, attr, value): self._private['special_attributes'][attr] = value #--- End: def def _unary_operation(self, method): ''' Implement unary arithmetic operations on the data array. :Parameters: method: `str` The unary arithmetic method name (such as "__abs__"). :Returns: new: `cf.{+Variable}` A new {+variable}. :Examples: >>> print v.array [1 2 -3 -4 -5] >>> w = v._unary_operation('__abs__') >>> print w.array [1 2 3 4 5] >>> w = v.__abs__() >>> print w.array [1 2 3 4 5] >>> w = abs(v) >>> print w.array [1 2 3 4 5] ''' if not self._hasData: raise ValueError( "Can't apply operator %s to a %s with no Data" % (method, self.__class__.__name__)) new = self.copy(_omit_Data=True) new.Data = self.Data._unary_operation(method) return new #--- End: def def _YMDhms(self, attr): ''' ''' if self._hasData: out = self.copy(_omit_Data=True) out.insert_data(getattr(self.data, attr), copy=False) try: del out.standard_name except AttributeError: pass out.long_name = attr return out #--- End: if raise ValueError( "ERROR: Can't get {0}s when there is no data array".format(attr)) #--- End: def def _hmmm(self, method): if self._hasData: out = self.copy(_omit_Data=True) out.insert_data(getattr(self.data, method)(), copy=False) try: del out.standard_name except AttributeError: pass out.long_name = method return out #--- End: if raise ValueError( "ERROR: Can't get {0} when there is no data array".format(method)) #--- End: def def _forbidden(self, x, name): raise AttributeError( "{0} has no {1} {2!r}.".format(self.__class__.__name__, x, name)) #--- End: def # ================================================================ # Forbidden methods # ================================================================ def append(self, *args, **kwargs): self._forbidden('method', 'append') # def count(self, *args, **kwargs): self._forbidden('method', 'count') def extend(self, *args, **kwargs): self._forbidden('method', 'extend') def index(self, *args, **kwargs): self._forbidden('method', 'index') def insert(self, *args, **kwargs): self._forbidden('method', 'insert') def pop(self, *args, **kwargs): self._forbidden('method', 'pop') def remove(self, *args, **kwargs): self._forbidden('method', 'remove') # ================================================================ # Attributes # ================================================================ @property def Data(self): ''' The `cf.Data` object containing the data array. The use of this attribute does not guarantee that any missing data value that has been set is passed on to the `cf.Data` object. Use the `data` attribute to ensure that this is the case. :Examples: >>> f.Data ''' if self._hasData: return self._private['Data'] raise AttributeError("%s doesn't have attribute 'Data'" % self.__class__.__name__) #--- End: def @Data.setter def Data(self, value): private = self._private private['Data'] = value # Delete Units from the variable private['special_attributes'].pop('Units', None) self._hasData = True #--- End: def @Data.deleter def Data(self): private = self._private data = private.pop('Data', None) if data is None: raise AttributeError("Can't delete non-existent %s attribute 'Data'" % self.__class__.__name__) # Save the Units to the variable private['special_attributes']['Units'] = data.Units self._hasData = False #--- End: def # ---------------------------------------------------------------- # Attribute # ---------------------------------------------------------------- @property def data(self): ''' The `cf.Data` object containing the data array. .. seealso:: `array`, `cf.Data`, `hasdata`, `varray` :Examples: >>> f.hasdata True >>> f.data ''' if self._hasData: data = self.Data data.fill_value = self._fill_value return data raise AttributeError("%s object doesn't have attribute 'data'" % self.__class__.__name__) #--- End: def @data.setter def data(self, value): self.Data = value @data.deleter def data(self): del self.Data # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def hasbounds(self): ''' True if there are cell bounds. If present, cell bounds are stored in the `!bounds` attribute. :Examples: >>> if c.hasbounds: ... b = c.bounds ''' return self._hasbounds #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def hasdata(self): ''' True if there is a data array. If present, the data array is stored in the `data` attribute. .. seealso:: `data`, `hasbounds` :Examples: >>> if f.hasdata: ... print f.data ''' return self._hasData #--- End: def # ---------------------------------------------------------------- # Attribute # ---------------------------------------------------------------- @property def reference_datetime(self): units = self.Units if not units.isreftime: raise AttributeError( "{0} doesn't have attribute 'reference_datetime'".format( self.__class__.__name__)) return units.reftime @reference_datetime.setter def reference_datetime(self, value): units = self.Units if not units.isreftime: raise AttributeError( "Can't set 'reference_datetime' for non reference date-time units".format( self.__class__.__name__)) units = units.units.split(' since ') try: self.units = "{0} since {1}".format(units[0], value) except (ValueError, TypeError): raise ValueError( "Can't override reference date-time {0!r} with {1!r}".format( units[1], value)) #--- End: def # ---------------------------------------------------------------- # Attribute # ---------------------------------------------------------------- @property def Units(self): '''The `cf.Units` object containing the units of the data array. Stores the units and calendar CF properties in an internally consistent manner. These are mirrored by the `units` and `calendar` CF properties respectively. :Examples: >>> f.Units >>> f.Units ''' if self._hasData: return self.Data.Units try: return self._get_special_attr('Units') except AttributeError: self._set_special_attr('Units', _units_None) return _units_None #--- End: def @Units.setter def Units(self, value): if self._hasData: self.Data.Units = value else: self._set_special_attr('Units', value) #--- End: def @Units.deleter def Units(self): raise AttributeError( "Can't delete %s attribute 'Units'. Use the override_units method." % self.__class__.__name__) @property def year(self): ''' The year of each date-time data array element. Only applicable to data arrays with reference time units. .. seealso:: `month`, `day`, `hour`, `minunte`, second` :Examples: >>> f.dtarray [ 450-11-15 00:00:00 450-12-16 12:30:00 451-01-16 12:00:45] >>> f.year.array [450 450 451] ''' return self._YMDhms('year') #--- End: def @property def month(self): ''' The month of each date-time data array element. Only applicable to data arrays with reference time units. .. seealso:: `year`, `day`, `hour`, `minunte`, second` :Examples: >>> f.dtarray [ 450-11-15 00:00:00 450-12-16 12:30:00 451-01-16 12:00:45] >>> f.month.array [11 12 1] ''' return self._YMDhms('month') #--- End: def @property def day(self): ''' The day of each date-time data array element. Only applicable to data arrays with reference time units. .. seealso:: `year`, `month`, `hour`, `minute`, second` :Examples: >>> f.dtarray [ 450-11-15 00:00:00 450-12-16 12:30:00 451-01-16 12:00:45] >>> f.day.array [15 16 16] ''' return self._YMDhms('day') #--- End: def @property def hour(self): ''' The hour of each date-time data array element. Only applicable to data arrays with reference time units. .. seealso:: `year`, `month`, `day`, `minute`, second` :Examples: >>> f.dtarray [ 450-11-15 00:00:00 450-12-16 12:30:00 451-01-16 12:00:45] >>> f.hour.array [ 0 12 12] ''' return self._YMDhms('hour') #--- End: def @property def minute(self): ''' The minute of each date-time data array element. Only applicable to data arrays with reference time units. .. seealso:: `year`, `month`, `day`, `hour`, second` :Examples: >>> f.dtarray [ 450-11-15 00:00:00 450-12-16 12:30:00 451-01-16 12:00:45] >>> f.minute.array [ 0 30 0] ''' return self._YMDhms('minute') #--- End: def @property def second(self): ''' The second of each date-time data array element. Only applicable to data arrays with reference time units. .. seealso:: `year`, `month`, `day`, `hour`, `minute` :Examples: >>> f.dtarray [ 450-11-15 00:00:00 450-12-16 12:30:00 451-01-16 12:00:45] >>> f.second.array [ 0 0 45] ''' return self._YMDhms('second') #--- End: def def mask_invalid(self, i=False): '''{+Fef,}Mask the array where invalid values occur (NaN or inf). Note that: * Invalid values in the results of arithmetic operations only occur if the raising of `FloatingPointError` exceptions has been suppressed by `cf.Data.seterr`. * If the raising of `FloatingPointError` exceptions has been allowed then invalid values in the results of arithmetic operations it is possible for them to be automatically converted to masked values, depending on the setting of `cf.Data.mask_fpe`. In this case, such automatic conversion might be faster than calling `mask_invalid`. .. seealso:: `cf.Data.mask_fpe`, `cf.Data.seterr` :Examples 1: >>> g = f.mask_invalid() :Parameters: {+i} :Returns: out: `cf.{+Variable}` :Examples: >>> print f[+0].array [ 0. 1.] >>> print g[+0].array [ 1. 2.] >>> old = cf.Data.seterr('ignore') >>> h = g/f >>> print h[+0].array [ inf 2.] >>> h.mask_invalid(i=True) >>> print h[+0].array [-- 2.] >>> h = g**12345 >>> print h[+0].array [ 1. inf] >>> h = h.mask_invalid() >>> print h[+0].array [1. --] >>> old = cf.Data.seterr('raise') >>> old = cf.Data.mask_fpe(True) >>> print (g/f)[+0].array [ -- 2] >>> print (g**12345)[+0].array [1. -- ] ''' # List functionality if self._list: kwargs2 = self._parameters(locals()) return self._list_method('mask_invalid', kwargs2) if i: v = self else: v = self.copy() if self._hasData: v.Data = v.Data.mask_invalid(i=True) return v #--- End: def def max(self): '''The maximum of the data array. .. seealso:: `collapse`, `mean`, `mid_range`, `min`, `range`, `sample_size`, `sd`, `sum`, `var` :Examples 1: >>> d = f.{+name}() :Returns: out: `cf.Data` The maximum of the data array. :Examples 2: >>> f.data >>> f.max().data ''' if self._hasData: return self.data.max(squeeze=True) raise ValueError( "ERROR: Can't get the maximum when there is no data array") #--- End: def def mean(self): '''The unweighted mean the data array. .. seealso:: `collapse`, `max`, `mid_range`, `min`, `range`, `sample_size`, `sd`, `sum`, `var` :Examples 1: >>> d = f.{+name}() :Returns: out: `cf.Data` The unweighted mean the data array. :Examples 2: >>> f.data >>> f.mean() ''' if self._hasData: return self.data.mean(squeeze=True) raise ValueError( "ERROR: Can't get the mean when there is no data array") #--- End: def def mid_range(self): '''The unweighted average of the maximum and minimum of the data array. .. seealso:: `collapse`, `max`, `mean`, `min`, `range`, `sample_size`, `sd`, `sum`, `var` :Examples 1: >>> d = f.{+name}() :Returns: out: `cf.Data` The unweighted average of the maximum and minimum of the data array. :Examples 2: >>> f.data >>> f.mid_range() ''' if self._hasData: return self.data.mid_range(squeeze=True) raise ValueError( "ERROR: Can't get the mid-range when there is no data array") #--- End: def def min(self): '''The minimum of the data array. .. seealso:: `collapse`, `max`, `mean`, `mid_range`, `range`, `sample_size`, `sd`, `sum`, `var` :Examples 1: >>> d = f.{+name}() :Returns: out: `cf.Data` The minimum of the data array. :Examples 2: >>> f.data >>> f.min() ''' if self._hasData: return self.data.min(squeeze=True) raise ValueError( "ERROR: Can't get the minimum when there is no data array") #--- End: def def range(self): ''' The absolute difference between the maximum and minimum of the data array. .. seealso:: `collapse`, `max`, `mean`, `mid_range`, `min`, `sample_size`, `sd`, `sum`, `var` :Examples 1: >>> d = f.{+name}() :Returns: out: `cf.Data` The absolute difference between the maximum and minimum of the data array. :Examples 2: >>> f.data >>> f.range() ''' if self._hasData: return self.data.range(squeeze=True) raise ValueError( "ERROR: Can't get the range when there is no data array") #--- End: def remove_data(self): ''' Remove and return the data array. :Returns: out: `cf.Data` or `None` The removed data array, or `None` if there isn't one. :Examples: >>> f._hasData True >>> f.data >>> f.remove_data() >>> f._hasData False >>> print f.remove_data() None ''' if not self._hasData: return data = self.data del self.Data return data #--- End: def def sample_size(self): '''The number of non-missing data elements in the data array. .. seealso:: `collapse`, `max`, `mean`, `mid_range`, `min`, `range`, `sd`, `sum`, `var` :Examples 1: >>> d = f.{+name}() :Returns: out: `cf.Data` The number of non-missing data elements in the data array. :Examples 2: >>> f.data >>> f.sample_size() ''' if self._hasData: return self.data.sample_size(squeeze=True) raise ValueError( "ERROR: Can't get the sample size when there is no data array") #--- End: def def sd(self): '''The unweighted sample standard deviation of the data array. .. seealso:: `collapse`, `max`, `mean`, `mid_range`, `min`, `range`, `sample_size`, `sum`, `var` :Examples 1: >>> d = f.{+name}() :Returns: out: `cf.Data` The unweighted sample standard deviation of the data array. :Examples 2: >>> f.data >>> f.sd() ''' if self._hasData: return self.data.sd(squeeze=True) raise ValueError( "ERROR: Can't get the standard deviation when there is no data array") #--- End: def def sum(self): '''The sum of the data array. .. seealso:: `collapse`, `max`, `mean`, `mid_range`, `min`, `range`, `sample_size`, `sd`, `var` :Examples 1: >>> d = f.{+name}() :Returns: out: `cf.Data` The sum of the data array. :Examples 2: >>> f.data >>> f.sum() ''' if self._hasData: return self.data.sum(squeeze=True) raise ValueError( "ERROR: Can't get the sum when there is no data array") #--- End: def def var(self): '''The unweighted sample variance of the data array. .. seealso:: `collapse`, `max`, `mean`, `mid_range`, `min`, `range`, `sample_size`, `sd`, `sum` :Examples 1: >>> d = f.{+name}() :Returns: out: `cf.Data` The unweighted sample variance of the data array. :Examples 2: >>> f.data >>> f.var() ''' if self._hasData: return self.data.var(squeeze=True) raise ValueError( "ERROR: Can't get the variance when there is no data array") #--- End: def # ---------------------------------------------------------------- # Attribute: ancillary_variables # ---------------------------------------------------------------- @property def ancillary_variables(self): '''An object containing one or more CF ancillary variables. :Examples: >>> f.ancillary_variables [] ''' return self._get_special_attr('ancillary_variables') #--- End: def @ancillary_variables.setter def ancillary_variables(self, value): self._set_special_attr('ancillary_variables', value) @ancillary_variables.deleter def ancillary_variables(self): self._del_special_attr('ancillary_variables') # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def T(self): ''' Always False. .. seealso:: `X`, `Y`, `Z` :Examples: >>> print f.T False ''' return False #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def X(self): ''' Always False. .. seealso:: `T`, `Y`, `Z` :Examples: >>> print f.X False ''' return False #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def Y(self): ''' Always False. .. seealso:: `T`, `X`, `Z` :Examples: >>> print f.Y False ''' return False #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def Z(self): ''' Always False. .. seealso:: `T`, `X`, `Y` :Examples: >>> print f.Z False ''' return False #--- End: def # ---------------------------------------------------------------- # CF property # ---------------------------------------------------------------- @property def add_offset(self): ''' The add_offset CF property. This property is only used when writing to a file on disk. :Examples: >>> f.add_offset = -4.0 >>> f.add_offset -4.0 >>> del f.add_offset >>> f.setprop('add_offset', 10.5) >>> f.getprop('add_offset') 10.5 >>> f.delprop('add_offset') ''' return self.getprop('add_offset') #--- End: def @add_offset.setter def add_offset(self, value): self.setprop('add_offset', value) self.dtype = numpy_result_type(self.dtype, numpy_array(value).dtype) #--- End: def @add_offset.deleter def add_offset(self): self.delprop('add_offset') if not self.hasprop('scale_factor'): del self.dtype #--- End: def # ---------------------------------------------------------------- # CF property: calendar # ---------------------------------------------------------------- @property def calendar(self): ''' The calendar CF property. :Examples: >>> f.calendar = 'noleap' >>> f.calendar 'noleap' >>> del f.calendar >>> f.setprop('calendar', 'proleptic_gregorian') >>> f.getprop('calendar') 'proleptic_gregorian' >>> f.delprop('calendar') ''' value = getattr(self.Units, 'calendar', None) if value is None: raise AttributeError("%s doesn't have CF property 'calendar'" % self.__class__.__name__) return value #--- End: def @calendar.setter def calendar(self, value): self.Units = Units(getattr(self, 'units', None), value) #--- End: def @calendar.deleter def calendar(self): if getattr(self, 'calendar', None) is None: raise AttributeError("Can't delete non-existent %s CF property 'calendar'" % self.__class__.__name__) self.Units = Units(getattr(self, 'units', None)) #--- End: def # ---------------------------------------------------------------- # CF property # ---------------------------------------------------------------- @property def comment(self): ''' The comment CF property. :Examples: >>> f.comment = 'This simulation was done on an HP-35 calculator' >>> f.comment 'This simulation was done on an HP-35 calculator' >>> del f.comment >>> f.setprop('comment', 'a comment') >>> f.getprop('comment') 'a comment' >>> f.delprop('comment') ''' return self.getprop('comment') #--- End: def @comment.setter def comment(self, value): self.setprop('comment', value) @comment.deleter def comment(self): self.delprop('comment') # ---------------------------------------------------------------- # CF property # ---------------------------------------------------------------- @property def _FillValue(self): ''' The _FillValue CF property. Note that this attribute is primarily for writing data to disk and is independent of the missing data mask. It may, however, get used when unmasking data array elements. The recommended way of retrieving the missing data value is with the `fill_value` method. .. seealso:: `fill_value`, `missing_value` :Examples: >>> f._FillValue = -1.0e30 >>> f._FillValue -1e+30 >>> del f._FillValue Mask the data array where it equals a missing data value: >>> f.setitem(cf.masked, condition=f.fill_value()) DCH ''' d = self._private['simple_properties'] if '_FillValue' in d: return d['_FillValue'] raise AttributeError("%s doesn't have CF property '_FillValue'" % self.__class__.__name__) #--- End: def @_FillValue.setter def _FillValue(self, value): # self.setprop('_FillValue', value) self._private['simple_properties']['_FillValue'] = value self._fill_value = self.getprop('missing_value', value) #--- End: def @_FillValue.deleter def _FillValue(self): self._private['simple_properties'].pop('_FillValue', None) self._fill_value = getattr(self, 'missing_value', None) #--- End: def # ---------------------------------------------------------------- # CF property # ---------------------------------------------------------------- @property def history(self): ''' The history CF property. :Examples: >>> f.history = 'created on 2012/10/01' >>> f.history 'created on 2012/10/01' >>> del f.history >>> f.setprop('history', 'created on 2012/10/01') >>> f.getprop('history') 'created on 2012/10/01' >>> f.delprop('history') ''' return self.getprop('history') #--- End: def @history.setter def history(self, value): self.setprop('history', value) @history.deleter def history(self): self.delprop('history') # ---------------------------------------------------------------- # CF property # ---------------------------------------------------------------- @property def leap_month(self): ''' The leap_month CF property. :Examples: >>> f.leap_month = 2 >>> f.leap_month 2 >>> del f.leap_month >>> f.setprop('leap_month', 11) >>> f.getprop('leap_month') 11 >>> f.delprop('leap_month') ''' return self.getprop('leap_month') #--- End: def @leap_month.setter def leap_month(self, value): self.setprop('leap_month', value) @leap_month.deleter def leap_month(self): self.delprop('leap_month') # ---------------------------------------------------------------- # CF property # ---------------------------------------------------------------- @property def leap_year(self): ''' The leap_year CF property. :Examples: >>> f.leap_year = 1984 >>> f.leap_year 1984 >>> del f.leap_year >>> f.setprop('leap_year', 1984) >>> f.getprop('leap_year') 1984 >>> f.delprop('leap_year') ''' return self.getprop('leap_year') #--- End: def @leap_year.setter def leap_year(self, value): self.setprop('leap_year', value) @leap_year.deleter def leap_year(self): self.delprop('leap_year') # ---------------------------------------------------------------- # CF property # ---------------------------------------------------------------- @property def long_name(self): ''' The long_name CF property. :Examples: >>> f.long_name = 'zonal_wind' >>> f.long_name 'zonal_wind' >>> del f.long_name >>> f.setprop('long_name', 'surface air temperature') >>> f.getprop('long_name') 'surface air temperature' >>> f.delprop('long_name') ''' return self.getprop('long_name') #--- End: def @long_name.setter def long_name(self, value): self.setprop('long_name', value) @long_name.deleter def long_name(self): self.delprop('long_name') # ---------------------------------------------------------------- # CF property # ---------------------------------------------------------------- @property def missing_value(self): ''' The missing_value CF property. Note that this attribute is used primarily for writing data to disk and is independent of the missing data mask. It may, however, be used when unmasking data array elements. The recommended way of retrieving the missing data value is with the `fill_value` method. .. seealso:: `_FillValue`, `fill_value` :Examples: >>> f.missing_value = 1.0e30 >>> f.missing_value 1e+30 >>> del f.missing_value Mask the data array where it equals a missing data value: >>> f.setitem(cf.masked, condition=f.fill_value()) DCH ''' d = self._private['simple_properties'] if 'missing_value' in d: return d['missing_value'] raise AttributeError("%s doesn't have CF property 'missing_value'" % self.__class__.__name__) #--- End: def @missing_value.setter def missing_value(self, value): self._private['simple_properties']['missing_value'] = value self._fill_value = value #--- End: def @missing_value.deleter def missing_value(self): self._private['simple_properties'].pop('missing_value', None) self._fill_value = getattr(self, '_FillValue', None) #--- End: def # ---------------------------------------------------------------- # CF property # ---------------------------------------------------------------- @property def month_lengths(self): ''' The month_lengths CF property. Stored as a tuple but may be set as any array-like object. :Examples: >>> f.month_lengths = numpy.array([34, 31, 32, 30, 29, 27, 28, 28, 28, 32, 32, 34]) >>> f.month_lengths (34, 31, 32, 30, 29, 27, 28, 28, 28, 32, 32, 34) >>> del f.month_lengths >>> f.setprop('month_lengths', [34, 31, 32, 30, 29, 27, 28, 28, 28, 32, 32, 34]) >>> f.getprop('month_lengths') (34, 31, 32, 30, 29, 27, 28, 28, 28, 32, 32, 34) >>> f.delprop('month_lengths') ''' return self.getprop('month_lengths') #--- End: def @month_lengths.setter def month_lengths(self, value): self.setprop('month_lengths', tuple(value)) @month_lengths.deleter def month_lengths(self): self.delprop('month_lengths') # ---------------------------------------------------------------- # CF property # ---------------------------------------------------------------- @property def scale_factor(self): ''' The scale_factor CF property. This property is only used when writing to a file on disk. :Examples: >>> f.scale_factor = 10.0 >>> f.scale_factor 10.0 >>> del f.scale_factor >>> f.setprop('scale_factor', 10.0) >>> f.getprop('scale_factor') 10.0 >>> f.delprop('scale_factor') ''' return self.getprop('scale_factor') #--- End: def @scale_factor.setter def scale_factor(self, value): self.setprop('scale_factor', value) @scale_factor.deleter def scale_factor(self): self.delprop('scale_factor') # ---------------------------------------------------------------- # CF property # ---------------------------------------------------------------- @property def standard_name(self): ''' The standard_name CF property. :Examples: >>> f.standard_name = 'time' >>> f.standard_name 'time' >>> del f.standard_name >>> f.setprop('standard_name', 'time') >>> f.getprop('standard_name') 'time' >>> f.delprop('standard_name') ''' return self.getprop('standard_name') #--- End: def @standard_name.setter def standard_name(self, value): self.setprop('standard_name', value) @standard_name.deleter def standard_name(self): self.delprop('standard_name') # ---------------------------------------------------------------- # CF property # ---------------------------------------------------------------- @property def units(self): ''' The units CF property. :Examples: >>> f.units = 'K' >>> f.units 'K' >>> del f.units >>> f.setprop('units', 'm.s-1') >>> f.getprop('units') 'm.s-1' >>> f.delprop('units') ''' value = getattr(self.Units, 'units', None) if value is None: raise AttributeError("%s doesn't have CF property 'units'" % self.__class__.__name__) return value #--- End: def @units.setter def units(self, value): self.Units = Units(value, getattr(self, 'calendar', None)) #--- End: def @units.deleter def units(self): if getattr(self, 'units', None) is None: self.Units = Units(None, getattr(self, 'calendar', None)) #--- End: def # ---------------------------------------------------------------- # CF property # ---------------------------------------------------------------- @property def valid_max(self): ''' The valid_max CF property. :Examples: >>> f.valid_max = 100.0 >>> f.valid_max 100.0 >>> del f.valid_max >>> f.setprop('valid_max', 100.0) >>> f.getprop('valid_max') 100.0 >>> f.delprop('valid_max') ''' return self.getprop('valid_max') #--- End: def @valid_max.setter def valid_max(self, value): self.setprop('valid_max', value) @valid_max.deleter def valid_max(self): self.delprop('valid_max') # ---------------------------------------------------------------- # CF property # ---------------------------------------------------------------- @property def valid_min(self): ''' The valid_min CF property. :Examples: >>> f.valid_min = 8.0 >>> f.valid_min 8.0 >>> del f.valid_min >>> f.setprop('valid_min', 8.0) >>> f.getprop('valid_min') 8.0 >>> f.delprop('valid_min') ''' return self.getprop('valid_min') #--- End: def @valid_min.setter def valid_min(self, value): self.setprop('valid_min', value) @valid_min.deleter def valid_min(self): self.delprop('valid_min') # ---------------------------------------------------------------- # CF property # ---------------------------------------------------------------- @property def valid_range(self): ''' The valid_range CF property. Stored as a tuple but may be set as any array-like object. :Examples: >>> f.valid_range = numpy.array([100., 400.]) >>> f.valid_range (100.0, 400.0) >>> del f.valid_range >>> f.setprop('valid_range', [100.0, 400.0]) >>> f.getprop('valid_range') (100.0, 400.0) >>> f.delprop('valid_range') ''' return tuple(self.getprop('valid_range')) #--- End: def @valid_range.setter def valid_range(self, value): self.setprop('valid_range', tuple(value)) @valid_range.deleter def valid_range(self): self.delprop('valid_range') # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def subspace(self): ''' Return a new variable whose data is subspaced. This attribute may be indexed to select a subspace from dimension index values. **Subspacing by indexing** Subspacing by dimension indices uses an extended Python slicing syntax, which is similar numpy array indexing. There are two extensions to the numpy indexing functionality: * Size 1 dimensions are never removed. An integer index i takes the i-th element but does not reduce the rank of the output array by one. * When advanced indexing is used on more than one dimension, the advanced indices work independently. When more than one dimension's slice is a 1-d boolean array or 1-d sequence of integers, then these indices work independently along each dimension (similar to the way vector subscripts work in Fortran), rather than by their elements. :Examples: ''' return SubspaceVariable(self) #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def shape(self): ''' A tuple of the data array's dimension sizes. .. seealso:: `data`, `hasdata`, `ndim`, `size` :Examples: >>> f.shape (73, 96) >>> f.ndim 2 >>> f.ndim 0 >>> f.shape () >>> f.hasdata True >>> len(f.shape) == f.dnim True >>> reduce(lambda x, y: x*y, f.shape, 1) == f.size True ''' if self._hasData: return tuple(self.Data.shape) raise AttributeError("%s doesn't have attribute 'shape'" % self.__class__.__name__) #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def ndim(self): ''' The number of dimensions in the data array. .. seealso:: `data`, `hasdata`, `isscalar`, `shape` :Examples: >>> f.hasdata True >>> f.shape (73, 96) >>> f.ndim 2 >>> f.shape () >>> f.ndim 0 ''' if self._hasData: return self.Data.ndim raise AttributeError("%s doesn't have attribute 'ndim'" % self.__class__.__name__) #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def size(self): ''' The number of elements in the data array. .. seealso:: `data`, `hasdata`, `ndim`, `shape` :Examples: >>> f.shape (73, 96) >>> f.size 7008 >>> f.shape () >>> f.ndim 0 >>> f.size 1 >>> f.shape (1, 1, 1) >>> f.ndim 3 >>> f.size 1 >>> f.hasdata True >>> f.size == reduce(lambda x, y: x*y, f.shape, 1) True ''' if self._hasData: return self.Data.size raise AttributeError("%s doesn't have attribute 'size'" % self.__class__.__name__) #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def dtarray(self): ''' An independent numpy array of date-time objects. Only applicable for reference time units. If the calendar has not been set then the CF default calendar will be used and the units will be updated accordingly. The data type of the data array is unchanged. .. seealso:: `array`, `asdatetime`, `asreftime`, `dtvarray`, `varray` :Examples: ''' if self._hasData: return self.data.dtarray raise AttributeError("%s has no data array" % self.__class__.__name__) #--- End: def # ---------------------------------------------------------------- # Attribute # ---------------------------------------------------------------- @property def dtype(self): ''' The `numpy` data type of the data array. By default this is the data type with the smallest size and smallest scalar kind to which all sub-arrays of the master data array may be safely cast without loss of information. For example, if the sub-arrays have data types 'int64' and 'float32' then the master data array's data type will be 'float64'; or if the sub-arrays have data types 'int64' and 'int32' then the master data array's data type will be 'int64'. Setting the data type to a `numpy.dtype` object, or any object convertible to a `numpy.dtype` object, will cause the master data array elements to be recast to the specified type at the time that they are next accessed, and not before. This does not immediately change the master data array elements, so, for example, reinstating the original data type prior to data access results in no loss of information. Deleting the data type forces the default behaviour. Note that if the data type of any sub-arrays has changed after `dtype` has been set (which could occur if the data array is accessed) then the reinstated default data type may be different to the data type prior to `dtype` being set. :Examples: >>> f.dtype dtype('float64') >>> type(f.dtype) >>> print f.array [0.5 1.5 2.5] >>> import numpy >>> f.dtype = numpy.dtype(int) >>> print f.array [0 1 2] >>> f.dtype = bool >>> print f.array [False True True] >>> f.dtype = 'float64' >>> print f.array [ 0. 1. 1.] >>> print f.array [0.5 1.5 2.5] >>> f.dtype = int >>> f.dtype = bool >>> f.dtype = float >>> print f.array [ 0.5 1.5 2.5] ''' if self._hasData: return self.Data.dtype raise AttributeError("%s doesn't have attribute 'dtype'" % self.__class__.__name__) #--- End: def @dtype.setter def dtype(self, value): # DCH - allow dtype to be set before data c.f. Units if self._hasData: self.Data.dtype = value #--- End: def @dtype.deleter def dtype(self): if self._hasData: del self.Data.dtype #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def dtvarray(self): ''' A numpy array view the data array converted to date-time objects. Only applicable for reference time units. If the calendar has not been set then the CF default calendar will be used and the units will be updated accordingly. .. seealso:: `array`, `asdatetime`, `asreftime`, `dtarray`, `varray` :Examples: ''' if self._hasData: return self.data.dtvarray raise AttributeError("%s has no data array" % self.__class__.__name__) #--- End: def # ---------------------------------------------------------------- # Attribute (read/write only) # ---------------------------------------------------------------- @property def hardmask(self): ''' Whether the mask is hard (True) or soft (False). When the mask is hard, masked elements of the data array can not be unmasked by assignment, but unmasked elements may be still be masked. When the mask is soft, masked entries of the data array may be unmasked by assignment and unmasked entries may be masked. By default, the mask is hard. .. seealso:: `where`, `subspace` :Examples: >>> f.hardmask = False >>> f.hardmask False ''' if self._hasData: return self.Data.hardmask raise AttributeError("%s doesn't have attribute 'hardmask'" % self.__class__.__name__) #--- End: def @hardmask.setter def hardmask(self, value): if self._hasData: self.Data.hardmask = value else: raise AttributeError("%s doesn't have attribute 'hardmask'" % self.__class__.__name__) #--- End: def @hardmask.deleter def hardmask(self): raise AttributeError("Won't delete %s attribute 'hardmask'" % self.__class__.__name__) #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def array(self): ''' A numpy array deep copy of the data array. Changing the returned numpy array does not change the data array. .. seealso:: `data`, `dtarray`, `dtvarray`, `varray` :Examples 1: >>> f.data >>> a = f.array >>> type(a) >>> print a [0 1 2 3 4] >>> a[0] = 999 >>> print a [999 1 2 3 4] >>> print f.array [0 1 2 3 4] >>> f.data ''' if self._hasData: return self.data.array raise AttributeError("%s has no data array" % self.__class__.__name__) #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def unsafe_array(self): ''' ''' if self._hasData: return self.data.unsafe_array raise AttributeError("%s has no data array" % self.__class__.__name__) #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def varray(self): ''' A numpy array view of the data array. Changing the elements of the returned view changes the data array. .. seealso:: `array`, `data`, `dtarray`, `dtvarray` :Examples 1: >>> f.data >>> a = f.array >>> type(a) >>> print a [0 1 2 3 4] >>> a[0] = 999 >>> print a [999 1 2 3 4] >>> print f.array [999 1 2 3 4] >>> f.data ''' if self._hasData: return self.data.varray raise AttributeError("%s has no data array" % self.__class__.__name__) #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def isauxiliary(self): ''' True if the variable is an auxiliary coordinate object. .. seealso:: `ismeasure`, `isdimension` :Examples: >>> f.isauxiliary False ''' return False #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def ismeasure(self): '''True if the variable is a cell measure object. .. seealso:: `isauxiliary`, `isdimension` :Examples: >>> f.ismeasure False ''' return False #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def isdimension(self): '''True if the variable is a dimension coordinate object. .. seealso:: `isauxiliary`, `isdimension` :Examples: >>> f.isdimension False ''' return False #--- End: def @property def isscalar(self): '''True if the data array is scalar. .. seealso:: `hasdata`, `ndim` :Examples: >>> f.ndim 0 >>> f.isscalar True >>> f.ndim >= 1 True >>> f.isscalar False >>> f.hasdata False >>> f.isscalar False ''' if not self._hasData: return False return self.Data.isscalar #--- End: def def ceil(self, i=False): '''{+Fef,}The ceiling of the data array. The ceiling of the scalar ``x`` is the smallest integer ``i``, such that ``i >= x``. .. versionadded:: 1.0 .. seealso:: `floor`, `rint`, `trunc` :Examples 1: Create a new {+variable} with the ceiling of the data: >>> g = f.ceil() :Parameters: {+i} :Returns: out: `cf.{+Variable}` {+Fef,}The {+variable} with the ceiling of data array values. :Examples 2: >>> print f.array [-1.9 -1.5 -1.1 -1. 0. 1. 1.1 1.5 1.9] >>> print f.ceil().array [-1. -1. -1. -1. 0. 1. 2. 2. 2.] >>> print f.array [-1.9 -1.5 -1.1 -1. 0. 1. 1.1 1.5 1.9] >>> print f.ceil(i=True).array [-1. -1. -1. -1. 0. 1. 2. 2. 2.] >>> print f.array [-1. -1. -1. -1. 0. 1. 2. 2. 2.] ''' # List functionality if self._list: kwargs2 = self._parameters(locals()) return self._list_method('ceil', kwargs2) if not self._hasData: raise ValueError("Can't ceil %r" % self.__class__.__name__) if i: v = self else: v = self.copy() v.Data.ceil(i=True) return v #--- End: def def chunk(self, chunksize=None): ''' Partition the data array. :Parameters: chunksize: `int` :Returns: `None` ''' if self._hasData: self.Data.chunk(chunksize) #--- End: def def clip(self, a_min, a_max, units=None, i=False): ''' Clip (limit) the values in the data array in place. Given an interval, values outside the interval are clipped to the interval edges. Parameters : a_min: scalar a_max: scalar units: `str` or `cf.Units` {+i} :Returns: `None` :Examples: ''' if i: v = self else: v = self.copy() if self._hasData: v.Data.clip( a_min, a_max, units=units, i=True) return v #--- End: def def close(self): ''' Close all files referenced by the variable. Note that a closed file will be automatically reopened if its contents are subsequently required. :Returns: `None` :Examples: >>> v.close() ''' # List functionality if self._list: for f in self: f.close() return if self._hasData: self.Data.close() #--- End: def @classmethod def concatenate(cls, variables, axis=0, _preserve=True): ''' Join a sequence of variables together. :Parameters: variables: sequence of `cf.{+Variable}` axis: `int`, optional _preserve: `bool`, optional :Returns: out: `cf.{+Variable}` ''' variable0 = variables[0] if len(variables) == 1: return variable0.copy() out = variable0.copy(_omit_Data=True) out.Data = Data.concatenate([v.Data for v in variables], axis=axis, _preserve=_preserve) return out #--- End: def def copy(self, _omit_Data=False, _only_Data=False, _omit_special=None, _omit_properties=False, _omit_attributes=False): ''' Return a deep copy. ``f.copy()`` is equivalent to ``copy.deepcopy(f)``. :Examples 1: >>> g = f.copy() :Returns: out: The deep copy. :Examples 2: >>> g = f.copy() >>> g is f False >>> f.equals(g) True >>> import copy >>> h = copy.deepcopy(f) >>> h is f False >>> f.equals(g) True ''' if self._list: kwargs2 = self._parameters(locals()) return self._list_method('copy', kwargs2) new = type(self)() # ts = type(self) # new = ts.__new__(ts) if _only_Data: if self._hasData: new.Data = self.Data.copy() return new #--- End: if self_dict = self.__dict__.copy() self_private = self_dict.pop('_private') del self_dict['_hasData'] new.__dict__['_fill_value'] = self_dict.pop('_fill_value') new.__dict__['_hasbounds'] = self_dict.pop('_hasbounds') if self_dict and not _omit_attributes: try: new.__dict__.update(loads(dumps(self_dict, -1))) except PicklingError: new.__dict__.update(deepcopy(self_dict)) private = {} if not _omit_Data and self._hasData: private['Data'] = self_private['Data'].copy() new._hasData = True special = self_private['special_attributes'].copy() if _omit_special: for prop in _omit_special: special.pop(prop, None) #--- End: if for prop, value in special.iteritems(): special[prop] = value.copy() private['special_attributes'] = special if not _omit_properties: try: private['simple_properties'] = loads(dumps(self_private['simple_properties'], -1)) except PicklingError: private['simple_properties'] = deepcopy(self_private['simple_properties']) else: private['simple_properties'] = {} new._private = private return new #--- End: def def cos(self, i=False): ''' {+Fef,}Take the trigonometric cosine of the data array. Units are accounted for in the calculation, so that the the cosine of 90 degrees_east is 0.0, as is the cosine of 1.57079632 radians. If the units are not equivalent to radians (such as Kelvin) then they are treated as if they were radians. The output units are '1' (nondimensionsal). .. seealso:: `sin`, `tan` :Examples 1: >>> g = f.cos() :Parameters: {+i} :Returns: out: `cf.{+Variable}` {+Fef,}The {+variable} with the cosine of data array values. :Examples 2: >>> f.Units >>> print f.array [[-90 0 90 --]] >>> f.cos() >>> f.Units >>> print f.array [[0.0 1.0 0.0 --]] >>> f.Units >>> print f.array [[1 2 3 --]] >>> f.cos() >>> f.Units >>> print f.array [[0.540302305868 -0.416146836547 -0.9899924966 --]] ''' if i: v = self else: v = self.copy() if v._hasData: v.Data.cos(i=True) return v #--- End: def def count(self, x): ''' Emulate f.count(x) Equality is tested with the {+variable}'s `cf.{+Variable}.equals` method (as opposed to the ``==`` operator). Note that ``f.count(x)`` is equivalent to ``1 if f.equals(x) else 0``. ''' return int(self.equals(x)) #--- End: def def cyclic(self, axes=None, iscyclic=True): ''' Set the cyclicity of axes of the data array. .. seealso:: `iscyclic` :Parameters: axes: (sequence of) `int` The axes to be set. Each axis is identified by its integer position. By default no axes are set. iscyclic: `bool`, optional If False then the axis is set to be non-cyclic. By default the axis is set to be cyclic. :Returns: out: `set` :Examples: >>> f.cyclic() {} >>> f.cyclic(1) {} >>> f.cyclic() {1} ''' if self._hasData: return self.Data.cyclic(axes, iscyclic) else: return {} #--- End: def def datum(self, *index): ''' Return an element of the data array as a standard Python scalar. The first and last elements are always returned with ``f.datum(0)`` and ``f.datum(-1)`` respectively, even if the data array is a scalar array or has two or more dimensions. :Parameters: index: optional Specify which element to return. When no positional arguments are provided, the method only works for data arrays with one element (but any number of dimensions), and the single element is returned. If positional arguments are given then they must be one of the following: * An integer. This argument is interpreted as a flat index into the array, specifying which element to copy and return. Example: If the data aray shape is ``(2, 3, 6)`` then: * ``f.datum(0)`` is equivalent to ``f.datum(0, 0, 0)``. * ``f.datum(-1)`` is equivalent to ``f.datum(1, 2, 5)``. * ``f.datum(16)`` is equivalent to ``f.datum(0, 2, 4)``. If *index* is ``0`` or ``-1`` then the first or last data array element respecitively will be returned, even if the data array is a scalar array or has two or more dimensions. .. * Two or more integers. These arguments are interpreted as a multidimensionsal index to the array. There must be the same number of integers as data array dimensions. .. * A tuple of integers. This argument is interpreted as a multidimensionsal index to the array. There must be the same number of integers as data array dimensions. Example: ``f.datum((0, 2, 4))`` is equivalent to ``f.datum(0, 2, 4)``; and ``f.datum(())`` is equivalent to ``f.datum()``. :Returns: out: A copy of the specified element of the array as a suitable Python scalar. :Examples: >>> print f.array 2 >>> f.datum() 2 >>> 2 == f.datum(0) == f.datum(-1) == f.datum(()) True >>> print f.array [[2]] >>> 2 == f.datum() == f.datum(0) == f.datum(-1) True >>> 2 == f.datum(0, 0) == f.datum((-1, -1)) == f.datum(-1, 0) True >>> print f.array [[4 -- 6] [1 2 3]] >>> f.datum(0) 4 >>> f.datum(-1) 3 >>> f.datum(1) masked >>> f.datum(4) 2 >>> f.datum(-2) 2 >>> f.datum(0, 0) 4 >>> f.datum(-2, -1) 6 >>> f.datum(1, 2) 3 >>> f.datum((0, 2)) 6 ''' if not self._hasData: raise ValueError( "ERROR: Can't return an element when there is no data array") return self.Data.datum(*index) #--- End: def def dump(self, display=True, prefix=None, omit=()): ''' Return a string containing a full description of the instance. :Parameters: display: `bool`, optional If False then return the description as a string. By default the description is printed, i.e. ``f.dump()`` is equivalent to ``print f.dump(display=False)``. omit: sequence of `str`, optional Omit the given CF properties from the description. prefix: optional Ignored. :Returns: out: `None` or `str` A string containing the description. :Examples: >>> f.dump() Data(1, 2) = [[2999-12-01 00:00:00, 3000-12-01 00:00:00]] 360_day axis = 'T' standard_name = 'time' >>> f.dump(omit=('axis',)) Data(1, 2) = [[2999-12-01 00:00:00, 3000-12-01 00:00:00]] 360_day standard_name = 'time' ''' string = [] if self._hasData: data = self.Data string.append('Data%s = %s' % (data.shape, data)) string.append(self._dump_simple_properties(omit=omit)) string = '\n'.join(string) if display: print string else: return string #--- End: def def equals(self, other, rtol=None, atol=None, ignore_fill_value=False, traceback=False, ignore=(), _set=False): ''' True if two {+variable}s are equal, False otherwise. :Parameters: other: The object to compare for equality. {+atol} {+rtol} ignore_fill_value: `bool`, optional If True then data arrays with different fill values are considered equal. By default they are considered unequal. traceback: `bool`, optional If True then print a traceback highlighting where the two {+variable}s differ. ignore: `tuple`, optional The names of CF properties to omit from the comparison. :Returns: out: `bool` Whether or not the two {+variable}s are equal. :Examples: >>> f.equals(f) True >>> g = f + 1 >>> f.equals(g) False >>> g -= 1 >>> f.equals(g) True >>> f.setprop('name', 'name0') >>> g.setprop('name', 'name1') >>> f.equals(g) False >>> f.equals(g, ignore=['name']) True ''' # Check for object identity if self is other: return True # Check that each instance is of the same type if not isinstance(other, self.__class__): if traceback: print("{0}: Incompatible types: {0}, {1}".format( self.__class__.__name__, other.__class__.__name__)) return False #--- End: if # Check that there are equal numbers of variables len_self = len(self) if len_self != len(other): if traceback: print("{0}: Different numbers of ppp: {1}, {2}".format( self.__class__.__name__, len_self, len(other))) return False #--- End: if if len_self != 1: if not _set: # ---------------------------------------------------- # Two lists, each with more than one element: Check # the lists pair-wise. # ---------------------------------------------------- for i, (f, g) in enumerate(zip(self, other)): if not f.equals(g, rtol=rtol, atol=atol, ignore_fill_value=ignore_fill_value, traceback=traceback, ignore=ignore): if traceback: print("{0}: Different element {1}: {2!r}, {3!r}".format( self.__class__.__name__, i, f, g)) return False else: # ---------------------------------------------------- # Two lists, each with more than one element: Check # the lists set-wise. # ---------------------------------------------------- # Group the variables by identity self_identity = {} for f in self: self_identity.setdefault(f.identity(), []).append(f) other_identity = {} for f in other: other_identity.setdefault(f.identity(), []).append(f) # Check that there are the same identities if set(self_identity) != set(other_identity): if traceback: print("{0}: Different sets of identities: {1}, {2}".format( self.__class__.__name__, set(self_identity), set(other_identity))) return False #--- End: if # Check that there are the same number of variables # for each identity for identity, fl in self_identity.iteritems(): gl = other_identity[identity] if len(fl) != len(gl): if traceback: print("{0}: Different numbers of {1!r} {2}s: {3}, {4}".format( self.__class__.__name__, identity, fl[0].__class__.__name__, len(fl), len(gl))) return False #--- End: fo # For each identity, check that there are matching # pairs of equal fields. for identity, fl in self_identity.iteritems(): gl = other_identity[identity] for f in fl: found_match = False for i, g in enumerate(gl): if f.equals(g, rtol=rtol, atol=atol, ignore_fill_value=ignore_fill_value, ignore=ignore, traceback=False): found_match = True del gl[i] break #--- End: for if not found_match: if traceback: print("{0}: No {1} equal to: {2!r}".format( self.__class__.__name__, g.__class__.__name__, f)) return False #--- End: if # -------------------------------------------------------- # Lists are equal # -------------------------------------------------------- return True #--- End: if # Still here? if self._list: self = self[0] if other._list: other = other[0] # ------------------------------------------------------------ # Check the simple properties # ------------------------------------------------------------ if ignore_fill_value: ignore += ('_FillValue', 'missing_value') self_simple = self._private['simple_properties'] other_simple = other._private['simple_properties'] if (set(self_simple).difference(ignore) != set(other_simple).difference(ignore)): if traceback: print("%s: Different properties: %s, %s" % (self.__class__.__name__, self_simple, other_simple)) return False #--- End: if if rtol is None: rtol = RTOL() if atol is None: atol = ATOL() for attr, x in self_simple.iteritems(): if attr in ignore: continue y = other_simple[attr] if not equals(x, y, rtol=rtol, atol=atol, ignore_fill_value=ignore_fill_value, traceback=traceback): if traceback: print("%s: Different %s properties: %r, %r" % (self.__class__.__name__, attr, x, y)) return False #--- End: for # ------------------------------------------------------------ # Check the special attributes # ------------------------------------------------------------ self_special = self._private['special_attributes'] other_special = other._private['special_attributes'] if set(self_special) != set(other_special): if traceback: print("%s: Different attributes: %s" % (self.__class__.__name__, set(self_special).symmetric_difference(other_special))) return False #--- End: if for attr, x in self_special.iteritems(): y = other_special[attr] if attr == 'ancillary_variables': result = set_equals(x, y, rtol=rtol, atol=atol, ignore_fill_value=ignore_fill_value, traceback=traceback) else: result = equals(x, y, rtol=rtol, atol=atol, ignore_fill_value=ignore_fill_value, traceback=traceback) if not result: if traceback: print("%s: Different %s properties: %r, %r" % (self.__class__.__name__, attr, x, y)) return False #--- End: for # ------------------------------------------------------------ # Check the data # ------------------------------------------------------------ self_hasData = self._hasData if self_hasData != other._hasData: if traceback: print("%s: Different data" % self.__class__.__name__) return False if self_hasData: if not self.data.equals(other.data, rtol=rtol, atol=atol, ignore_fill_value=ignore_fill_value, traceback=traceback): if traceback: print("%s: Different data" % self.__class__.__name__) return False #--- End: if return True #--- End: def def convert_reference_time(self, units=None, calendar_months=False, calendar_years=False, i=False): '''Convert reference time data values to have new units. Conversion is done by decoding the reference times to date-time objects and then re-encoding them for the new units. Any conversions are possible, but this method is primarily for conversions which require a change in the date-times originally encoded. For example, use this method to reinterpret data values in units of "months" since a reference time to data values in "calendar months" since a reference time. This is often necessary when when units of "calendar months" were intended but encoded as "months", which have special definition. See the note and examples below for more details. For conversions which do not require a change in the date-times implied by the data values, this method will be considerably slower than a simple reassignment of the units. For example, if the original units are ``'days since 2000-12-1'`` then ``c.Units = cf.Units('days since 1901-1-1')`` will give the same result and be considerably faster than ``c.convert_reference_time(cf.Units('days since 1901-1-1'))`` .. note:: It is recommended that the units "year" and "month" be used with caution, as explained in the following excerpt from the CF conventions: "The Udunits package defines a year to be exactly 365.242198781 days (the interval between 2 successive passages of the sun through vernal equinox). It is not a calendar year. Udunits includes the following definitions for years: a common_year is 365 days, a leap_year is 366 days, a Julian_year is 365.25 days, and a Gregorian_year is 365.2425 days. For similar reasons the unit ``month``, which is defined to be exactly year/12, should also be used with caution. :Examples 1: >>> g = f.convert_reference_time() :Parameters: units: `cf.Units`, optional The reference time units to convert to. By default the units days since the original reference time in the the original calendar. *Example:* If the original units are ``'months since 2000-1-1'`` in the Gregorian calendar then the default units to convert to are ``'days since 2000-1-1'`` in the Gregorian calendar. calendar_months: `bool`, optional If True then treat units of ``'months'`` as if they were calendar months (in whichever calendar is originally specified), rather than a 12th of the interval between 2 successive passages of the sun through vernal equinox (i.e. 365.242198781/12 days). calendar_years: `bool`, optional If True then treat units of ``'years'`` as if they were calendar years (in whichever calendar is originally specified), rather than the interval between 2 successive passages of the sun through vernal equinox (i.e. 365.242198781 days). {+i} :Returns: out: `cf.{+Variable}` The {+variable} with converted reference time data values. :Examples 2: >>> print f.array [1 2 3 4] >>> print f.Units months since 2000-1-1 >>> print f.dtarray [datetime.datetime(2000, 1, 31, 10, 29, 3, 831197) datetime.datetime(2000, 3, 1, 20, 58, 7, 662441) datetime.datetime(2000, 4, 1, 7, 27, 11, 493645) datetime.datetime(2000, 5, 1, 17, 56, 15, 324889)] >>> f.convert_reference_time(calendar_months=True, i=True) >>> print f.dtarray [datetime.datetime(2000, 2, 1, 0, 0) datetime.datetime(2000, 3, 1, 0, 0) datetime.datetime(2000, 4, 1, 0, 0) datetime.datetime(2000, 5, 1, 0, 0)] >>> print f.array [ 31. 60. 91. 121.] >>> print f.Units days since 2000-1-1 ''' def _convert_reftime_units(value, units, reftime, calendar): '''sads :Parameters: value: number units: `cf.Units` :Returns: out: `datetime.datetime` or `cf.Datetime` ''' t = TimeDuration(value, units=units) if value > 0: return t.interval(*reftime, calendar=calendar, end=False)[1] else: return t.interval(*reftime, calendar=calendar, end=True)[0] #--- End: def # List functionality if self._list: kwargs2 = self._parameters(locals()) return self._list_method('convert_reference_time', kwargs2) if not self.Units.isreftime: raise ValueError( "{0} must have reference time units, not {1!r}".format( self.__class__.__name__, self.Units)) if i: v = self else: v = self.copy() units0 = self.Units if units is None: # By default, set the target units to "days since # , # calendar=" units = Units('days since '+units0.units.split(' since ')[1], calendar=units0._calendar) elif not getattr(units, 'isreftime', False): raise ValueError( "New units must be reference time units, not {0!r}".format(units)) if units0._utime.units in ('month', 'months'): if calendar_months: units0 = Units('calendar_'+units0.units, calendar=units0._calendar) else: units0 = Units('days since '+units0.units.split(' since ')[1], calendar=units0._calendar) v.Units = units0 elif units0._utime.units in ('year', 'years', 'yr'): if calendar_years: units0 = Units('calendar_'+units0.units, calendar=units0._calendar) else: units0 = Units('days since '+units0.units.split(' since ')[1], calendar=units0._calendar) v.Units = units0 #--- End: def # Not LAMAed! v.Data = Data( numpy_vectorize( functools_partial(_convert_reftime_units, units=units0._utime.units, reftime=units0.reftime.timetuple()[:6], calendar=units0._calendar), otypes=[object])(v), units=units) return v #--- End: def def floor(self, i=False): '''{+Fef,}Floor the data array. The floor of the scalar ``x`` is the largest integer ``i``, such that ``i <= x``. .. versionadded:: 1.0 .. seealso:: `ceil`, `rint`, `trunc` :Examples 1: Create a new {+variable} with the floor of the data: >>> g = f.floor() :Parameters: {+i} :Returns: out: `cf.{+Variable}` {+Fef,}The {+variable} with the floor of data array values. :Examples 2: >>> print f.array [-1.9 -1.5 -1.1 -1. 0. 1. 1.1 1.5 1.9] >>> print f.floor().array [-2. -2. -2. -1. 0. 1. 1. 1. 1.] >>> print f.array [-1.9 -1.5 -1.1 -1. 0. 1. 1.1 1.5 1.9] >>> print f.floor(i=True).array [-2. -2. -2. -1. 0. 1. 1. 1. 1.] >>> print f.array [-2. -2. -2. -1. 0. 1. 1. 1. 1.] ''' # List functionality if self._list: kwargs2 = self._parameters(locals()) return self._list_method('floor', kwargs2) if not self._hasData: raise ValueError("Can't floor %r" % self.__class__.__name__) if i: v = self else: v = self.copy() v.Data.floor(i=True) return v #--- End: def def match(self, match=None, ndim=None, exact=False, match_and=True, inverse=False, _Flags=False, _CellMethods=False): ''' Determine whether or not a variable satisfies conditions. Conditions may be specified on the variable's attributes and CF properties. :Parameters: :Returns: out: `bool` Whether or not the variable matches the given criteria. :Examples: ''' conditions_have_been_set = False something_has_matched = False if ndim is not None: conditions_have_been_set = True try: found_match = self.ndim == ndim except AttributeError: found_match = False if match_and and not found_match: return bool(inverse) something_has_matched = True #--- End: if matches = self._parse_match(match) if matches: conditions_have_been_set = True found_match = True for match in matches: found_match = True # ---------------------------------------------------- # Try to match cf.Units # ---------------------------------------------------- if 'units' in match or 'calendar' in match: match = match.copy() units = Units(match.pop('units', None), match.pop('calendar', None)) if not exact: found_match = self.Units.equivalent(units) else: found_match = self.Units.equals(units) if not found_match: continue #--- End: if # ---------------------------------------------------- # Try to match cell methods # ---------------------------------------------------- if _CellMethods and 'cell_methods' in match: f_cell_methods = self.getprop('cell_methods', None) if not f_cell_methods: found_match = False continue match = match.copy() cell_methods = match.pop('cell_methods') if not exact: n = len(cell_methods) if n > len(f_cell_methods): found_match = False else: found_match = f_cell_methods[-n:].equivalent(cell_methods) else: found_match = f_cell_methods.equals(cell_methods) if not found_match: continue #--- End: if # --------------------------------------------------- # Try to match cf.Flags # --------------------------------------------------- if _Flags and ('flag_masks' in match or 'flag_meanings' in match or 'flag_values' in match): f_flags = getattr(self, Flags, None) if not f_flags: found_match = False continue match = match.copy() found_match = f_flags.equals( Flags(flag_masks=match.pop('flag_masks', None), flag_meanings=match.pop('flag_meanings', None), flag_values=match.pop('flag_values', None))) if not found_match: continue #--- End: if for prop, value in match.iteritems(): if prop is None: if value is None: continue if isinstance(value, basestring): if value in ('T', 'X', 'Y', 'Z'): # Axis type x = getattr(self, value) value = True else: value = value.split('%') if len(value) == 1: value = value[0].split(':') if len(value) == 1: # Identity (string-valued) x = self.identity(None) value = value[0] else: # CF property (string-valued) x = self.getprop(value[0], None) value = ':'.join(value[1:]) else: # Python attribute (string-valued) x = getattr(self, value[0], None) value = '%'.join(value[1:]) else: # Identity (not string-valued, e.g. cf.Query) x = self.identity(None) else: # CF property x = self.getprop(prop, None) if x is None: found_match = False elif isinstance(x, basestring) and isinstance(value, basestring): if exact: found_match = (value == x) else: found_match = re_match(value, x) else: found_match = (value == x) try: found_match == True except ValueError: found_match = False #--- End: if if not found_match: break #--- End: for if found_match: something_has_matched = True break #--- End: for if match_and and not found_match: return bool(inverse) if conditions_have_been_set: if something_has_matched: return not bool(inverse) else: return bool(inverse) else: return not bool(inverse) #--- End: def @property def mask(self): '''The mask of the data array. Values of True indicate masked elements. .. seealso:: `binary_mask` :Examples: >>> f.shape (12, 73, 96) >>> m = f.mask >>> m.long_name 'mask' >>> m.shape (12, 73, 96) >>> m.dtype dtype('bool') >>> m.data ''' if not self._hasData: raise ValueError( "ERROR: Can't get mask when there is no data array") out = self.copy(_omit_Data=True, _omit_properties=True, _omit_attributes=True) out.insert_data(self.data.mask, copy=False) out.long_name = 'mask' return out #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def attributes(self): ''' A dictionary of the attributes which are not CF properties. :Examples: >>> f.attributes {} >>> f.foo = 'bar' >>> f.attributes {'foo': 'bar'} >>> f.attributes.pop('foo') 'bar' >>> f.attributes {'foo': 'bar'} ''' attributes = self.__dict__.copy() del attributes['_hasbounds'] del attributes['_hasData'] del attributes['_private'] return attributes #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def properties(self): ''' A dictionary of the CF properties. :Examples: >>> f.properties {'_FillValue': 1e+20, 'foo': 'bar', 'long_name': 'Surface Air Temperature', 'standard_name': 'air_temperature', 'units': 'K'} ''' return self._simple_properties().copy() #--- End: def # ================================================================ # Methods # ================================================================ def all(self): '''Test whether all data array elements evaluate to True. Performs a logical and over the data array and returns the result. Masked values are considered as True during computation. .. seealso:: `any` :Examples 1: >>> b = f.all() :Returns: out: `bool` Whether ot not all data array elements evaluate to True. :Examples: >>> print f.array [[0 3 0]] >>> f.all() False >>> print f.array [[1 3 --]] >>> f.all() True ''' if self._hasData: return self.Data.all() return False #--- End: def def allclose(self, y, atol=None, rtol=None): '''Returns True if two broadcastable {+variable}s have equal array values to within numerical tolerance. For numeric data arrays ``f.allclose(y, atol, rtol)`` is equivalent to ``(abs(f - y) <= atol + rtol*abs(y)).all()``; for other data types it is equivalent to ``(f == y).all()``. .. seealso:: `~cf.{+Variable}.equals` :Examples 1: >>> b = f.allclose(y) :Parameters: y: data-like object The object to be compared with the data array. *y* must be broadcastable to the data array and if *y* has units then they must be compatible. {+data-like} {+atol} {+rtol} :Returns: out: `bool` Whether or not the two data arrays are equivalent. :Examples 2: ''' if not self._hasData: return False if isinstance(y, self.__class__): if not y._hasData: return False y = self._conform_for_assignment(y) #-- End: if y = getattr(y, 'Data', y) return self.Data.allclose(y, rtol=rtol, atol=atol) #--- End: def def any(self): '''Return True if any data array elements evaluate to True. Performs a logical or over the data array and returns the result. Masked values are considered as False during computation. .. seealso:: `all` :Examples 1: >>> b = f.any() :Returns: out: `bool` Whether ot not any data array elements evaluate to True. :Examples 2: >>> print f.array [[0 0 0]] >>> f.any() False >>> print f.array [[-- 0 0]] >>> d.any() False >>> print f.array [[-- 3 0]] >>> f.any() True ''' if self._hasData: return self.Data.any() return False #--- End: def def asdatetime(self, i=False): '''{+Fef,}Convert the internal representation of data array elements to date-time objects. Only applicable to {+variable}s with reference time units. If the calendar has not been set then the CF default calendar will be used and the units will be updated accordingly. .. seealso:: `asreftime` :Examples 1: >>> g = f.asdatetime() :Parameters: {+i} :Returns: out: `cf.{+Variable}` :Examples 2: >>> t.asreftime().dtype dtype('float64') >>> t.asdatetime().dtype dtype('O') ''' raise NotImplementedError("asdatetime is dead. Consider {0}.dtarray instead".format(self.__class__.__name__)) # # List functionality # if self._list: # kwargs2 = self._parameters(locals()) # return self._list_method('asdatetime', kwargs2) # # if not self._hasData: # raise AttributeError( # "{0} has no data array".format(self.__class__.__name__)) # # if i: # v = self # else: # v = self.copy() # # v.data.asdatetime(i=True) # return v # #--- End: def def asreftime(self, i=False): '''{+Fef,}Convert the internal representation of data array elements to numeric reference times. Only applicable to {+variable}s with reference time units. If the calendar has not been set then the CF default calendar will be used and the units will be updated accordingly. .. seealso:: `asdatetime` :Examples 1: >>> g = f.asreftime() :Parameters: {+i} :Returns: out: `cf.{+Variable}` :Examples 2: >>> t.asdatetime().dtype dtype('O') >>> t.asreftime().dtype dtype('float64') ''' raise NotImplementedError("asreftime is dead. Consider {0}.array instead".format(self.__class__.__name__)) # # List functionality # if self._list: # kwargs2 = self._parameters(locals()) # return self._list_method('asreftime', kwargs2) # # if not self._hasData: # raise AttributeError( # "{0} has no data array".format(self.__class__.__name__)) # # if i: # v = self # else: # v = self.copy() # # v.data.asreftime(i=True) # return v # #--- End: def def files(self): ''' Return the names of any files containing parts of the data array. :Returns: out: `set` The file names in normalized, absolute form. :Examples: >>> f = cf.read('../file*') >>> f[0].files() {'/data/user/file1', '/data/user/file2', '/data/user/file3'} >>> a = f[0].array >>> f[0].files() set() ''' if not self._hasData: return set() return self.Data.files() #--- End: def def fill_value(self, default=None): ''' Return the data array missing data value. This is the value of the `missing_value` CF property, or if that is not set, the value of the `_FillValue` CF property, else if that is not set, ``None``. In the last case the default `numpy` missing data value for the array's data type is assumed if a missing data value is required. :Parameters: default: optional If the missing value is unset then return this value. By default, *default* is `None`. If *default* is the special value ``'netCDF'`` then return the netCDF default value appropriate to the data array's data type is used. These may be found as follows: >>> import netCDF4 >>> print netCDF4.default_fillvals :Returns: out: The missing data value, or the value specified by *default* if one has not been set. :Examples: >>> f.fill_value() None >>> f._FillValue = -1e30 >>> f.fill_value() -1e30 >>> f.missing_value = 1073741824 >>> f.fill_value() 1073741824 >>> del f.missing_value >>> f.fill_value() -1e30 >>> del f._FillValue >>> f.fill_value() None >>> f,dtype dtype('float64') >>> f.fill_value(default='netCDF') 9.969209968386869e+36 >>> f._FillValue = -999 >>> f.fill_value(default='netCDF') -999 ''' fillval = self._fill_value if fillval is None: if default == 'netCDF': d = self.dtype fillval = _netCDF4_default_fillvals[d.kind + str(d.itemsize)] else: fillval = default #--- End: if return fillval # return self._fill_value #--- End: def def flip(self, axes=None, i=False): ''' {+Fef,}Flip dimensions of the data array in place. .. seealso:: `expand_dims`, `squeeze`, `transpose` :Parameters: axes: (sequence of) `int` Flip the dimensions whose positions are given. By default all dimensions are flipped. :Returns: out: `cf.{+Variable}` :Examples: >>> f.flip() >>> f.flip(1) >>> f.flip([0, 1]) >>> g = f[::-1, :, ::-1] >>> f.flip([2, 0]).equals(g) True ''' kwargs2 = self._parameters(locals()) # List functionality if self._list: return self._list_method('flip', kwargs2) if not self._hasData and (axes or axes == 0): raise ValueError("Can't flip %r" % self.__class__.__name__) if i: v = self else: v = self.copy() if v._hasData: kwargs2['i'] = True v.Data.flip(**kwargs2) return v #--- End: def def select(self, *args, **kwargs): ''' Return the instance if it matches the given conditions. ``v.select(*args, **kwargs)`` is equivalent to ``v if v.match(*args, **kwargs) else cf.List()``. See `cf.Variable.match` for details. :Parameters: args, kwargs: optional See `cf.Variable.match`. :Returns: out: `cf.{+Variable}` or `list` If the variable matches the given conditions then it is returned as an object identity. Otherwise an empty list is returned. ''' if self.match(*args, **kwargs): return self else: return [] #--- End: def @property def binary_mask(self): ''' A binary (0 and 1) missing data mask of the data array. The binary mask's data array comprises dimensionless 32-bit integers and has 0 where the data array has missing data and 1 otherwise. :Examples: >>> print f.mask.array [[ True False True False]] >>> b = f.binary_mask() >>> print b.array [[0 1 0 1]] ''' return type(self)(properties={'long_name': 'binary_mask'}, data=self.Data.binary_mask(), copy=False) #--- End: def def exp(self, i=False): '''{+Fef,}The exponential of the data array. .. seealso:: `log` :Examples 1: >>> g = f.exp() :Parameters: {+i} :Returns: out: `cf.{+Variable}` {+Fef,}The {+variable} with the exponential of data array values. :Examples 2: >>> f[+0].data >>> f.exp()[+0].data >>> f[+0].data >>> f.exp()[+0].data >>> g = f.exp(i=True) >>> g is f True >>> f[+0].data >>> f.exp() ValueError: Can't take exponential of dimensional quantities: ''' # List functionality if self._list: kwargs2 = self._parameters(locals()) return self._list_method('exp', kwargs2) if i: v = self else: v = self.copy() if v._hasData: v.Data.exp(i=True) return v #--- End: def def expand_dims(self, position=0, i=False): ''' Insert a size 1 axis into the data array. .. seealso:: `flip`, `squeeze`, `transpose` :Parameters: position: `int`, optional Specify the position amongst the data array axes where the new axis is to be inserted. By default the new axis is inserted at position 0, the slowest varying position. {+i} :Returns: `None` :Examples: >>> v.expand_dims(2) >>> v.expand_dims(-1) ''' # List functionality if self._list: kwargs2 = self._parameters(locals()) return self._list_method('expand_dims', kwargs2) if not self._hasData: raise ValueError( "Can't insert axis into %r" % self.__class__.__name__) if i: v = self else: v = self.copy() v.Data.expand_dims(position, i=True) return v #--- End: def def set_equals(self, other, rtol=None, atol=None, ignore_fill_value=False, traceback=False, ignore=()): ''' ''' kwargs2 = self._parameters(locals()) return self.equals(_set=True, **kwargs2) #--- End: def def sin(self, i=False): ''' {+Fef,}Take the trigonometric sine of the data array. Units are accounted for in the calculation. For example, the the sine of 90 degrees_east is 1.0, as is the sine of 1.57079632 radians. If the units are not equivalent to radians (such as Kelvin) then they are treated as if they were radians. The Units are changed to '1' (nondimensionsal). .. seealso:: `cos`, `tan` :Examples 1: >>> g = f.sin() :Parameters: {+i} :Returns: out: `cf.{+Variable}` {+Fef,}The {+variable} with the sine of data array values. :Examples 2: >>> f.Units >>> print f.array [[-90 0 90 --]] >>> f.sin() >>> f.Units >>> print f.array [[-1.0 0.0 1.0 --]] >>> f.Units >>> print f.array [[1 2 3 --]] >>> f.sin() >>> f.Units >>> print f.array [[0.841470984808 0.909297426826 0.14112000806 --]] ''' # List functionality if self._list: kwargs2 = self._parameters(locals()) return self._list_method('sin', kwargs2) if i: v = self else: v = self.copy() if v._hasData: v.Data.sin(i=True) return v #--- End: def def tan(self, i=False): ''' Take the trigonometric tangent of the data array. Units are accounted for in the calculation, so that the the tangent of 180 degrees_east is 0.0, as is the sine of 3.141592653589793 radians. If the units are not equivalent to radians (such as Kelvin) then they are treated as if they were radians. The Units are changed to '1' (nondimensionsal). :Parameters: {+i} :Returns: out: `cf.{+Variable}` {+Fef,}The {+variable} with the tangent of data array values. :Examples: ''' # List functionality if self._list: kwargs2 = self._parameters(locals()) return self._list_method('tan', kwargs2) if i: v = self else: v = self.copy() if v._hasData: v.Data.tan(i=True) return v #--- End: def def log(self, base=10, i=False): '''{+Fef,}The logarithm of the data array. By default the natural logarithm is taken, but any base may be specified. .. seealso:: `exp` :Examples 1: >>> g = f.log() :Parameters: base: number, optional The base of the logiarthm. By default a natural logiarithm is taken. {+i} :Returns: out: `cf.{+Variable}` {+Fef,}The {+variable} with the logarithm of data array values. :Examples: :Examples 2: >>> f[+0].data >>> f.log()[+0].data >>> f[+0].data >>> f.log()[+0].data >>> f[+0].data >>> f.log()[+0].data >>> g = f.log(i=True) >>> g is f True >>> f[+0].Units >>> f.log() ValueError: Can't take the logarithm to the base 2.718281828459045 of ''' # List functionality if self._list: kwargs2 = self._parameters(locals()) return self._list_method('log', kwargs2) if i: v = self else: v = self.copy() if v._hasData: v.Data.log(base, i=True) return v #--- End: def def squeeze(self, axes=None, i=False): ''' Remove size 1 dimensions from the data array in place. .. seealso:: `expand_dims`, `flip`, `transpose` :Parameters: axes: (sequence of) `int`, optional The size 1 axes to remove. By default, all size 1 axes are removed. Size 1 axes for removal are identified by their integer positions in the data array. {+i} :Returns: out: `cf.Variable` :Examples: >>> v.squeeze() >>> v.squeeze(1) >>> v.squeeze([1, 2]) ''' # List functionality if self._list: kwargs2 = self._parameters(locals()) return self._list_method('squeeze', kwargs2) if not self._hasData and (axes or axes == 0): raise ValueError("Can't squeeze %r" % self.__class__.__name__) if i: v = self else: v = self.copy() if v._hasData: v.Data.squeeze(axes, i=True) return v #--- End: def def transpose(self, axes=None, i=False): ''' {+Fef,}Permute the dimensions of the data array. .. seealso:: `expand_dims`, `flip`, `squeeze` :Parameters: axes: (sequence of) `int` The new axis order of the data array. By default the order is reversed. Each axis of the new order is identified by its original integer position. {+i} :Returns: out: `cf.{+Variable}` :Examples: >>> f.shape (2, 3, 4) >>> f.transpose() >>> f.shape (4, 3, 2) >>> f.transpose([1, 2, 0]) >>> f.shape (3, 2, 4) >>> f.transpose((1, 0, 2)) >>> f.shape (2, 3, 4) ''' # List functionality if self._list: kwargs2 = self._parameters(locals()) return self._list_method('transpose', kwargs2) if not self._hasData and (axes or axes == 0): raise ValueError( "Can't transpose %r with no data" % self.__class__.__name__) if i: v = self else: v = self.copy() if v._hasData: v.Data.transpose(axes, i=True) return v #--- End: def def trunc(self, i=False): '''{+Fef,}Truncate the data array. The truncated value of the scalar ``x``, is the nearest integer ``i`` which is closer to zero than ``x`` is. I.e. the fractional part of the signed number ``x`` is discarded. .. versionadded:: 1.0 .. seealso:: `ceil`, `floor`, `rint` :Examples 1: >>> g = f.trunc() :Parameters: {+i} :Returns: out: `cf.{+Variable}` {+Fef,}The {+variable} with truncated data array values. :Examples 2: >>> print f.array [-1.9 -1.5 -1.1 -1. 0. 1. 1.1 1.5 1.9] >>> print f.trunc().array [-1. -1. -1. -1. 0. 1. 1. 1. 1.] >>> print f.array [-1.9 -1.5 -1.1 -1. 0. 1. 1.1 1.5 1.9] >>> print f.trunc(i=True).array [-1. -1. -1. -1. 0. 1. 1. 1. 1.] >>> print f.array [-1. -1. -1. -1. 0. 1. 1. 1. 1.] ''' # List functionality if self._list: kwargs2 = self._parameters(locals()) return self._list_method('trunc', kwargs2) if not self._hasData: raise ValueError("Can't trunc %r" % self.__class__.__name__) if i: v = self else: v = self.copy() v.Data.trunc(i=True) return v #--- End: def def unique(self): '''The unique elements of the data array. :Examples 1: >>> f.unique() :Returns: out: `cf.Data` Returns the unique data array values in a one dimensional `cf.Data` object. :Examples 2: >>> print f.array [[4 2 1] [1 2 3]] >>> print f.unique().array [1 2 3 4] >>> f.subspace[1, -1] = cf.masked >>> print f.array [[4 2 1] [1 2 --]] >>> print f.unique().array [1 2 4] ''' if self._hasData: return self.data.unique() raise ValueError( "ERROR: Can't get unique values when there is no data array") #--- End: def def setprop(self, prop, value): ''' {+Fef,}Set a CF property. .. seealso:: `delprop`, `getprop`, `hasprop` :Examples 1: >>> f.setprop('standard_name', 'time') >>> f.setprop('foo', 12.5) :Parameters: prop: `str` The name of the CF property. value : The value for the property. :Returns: `None` ''' # List functionality if self._list: for f in self: f.setprop(prop, value) return # Set a special attribute if prop in self._special_properties: setattr(self, prop, value) return # Still here? Then set a simple property self._private['simple_properties'][prop] = value #--- End: def def hasprop(self, prop): ''' Return True if a CF property exists, otherise False. .. seealso:: `delprop`, `getprop`, `setprop` :Examples 1: >>> x = f.hasprop('standard_name') :Parameters: prop: `str` The name of the property. :Returns: out: `bool` True if the CF property exists, otherwise False. ''' # Has a special property? # DCH if prop in self._special_properties: return hasattr(self, prop) # Still here? Then has a simple property? return prop in self._private['simple_properties'] #--- End: def def identity(self, default=None): '''Return the identity. The identity is the first found of the following: * The `standard_name` CF property. * The `!id` attribute. * The value of the *default* parameter. .. seealso:: `name` :Parameters: default: optional The identity if one could not otherwise be found. By default, *default* is `None`. :Returns: out: The identity. :Examples: >>> f.standard_name = 'Kelvin' >>> f.id = 'foo' >>> f.identity() 'Kelvin' >>> del f.standard_name >>> f.identity() 'foo' >>> del f.id >>> f.identity() None >>> f.identity('bar') 'bar' >>> print f.identity() None ''' return self.name(default, identity=True) #--- End: def def index(self, x, start=0, stop=None): ''' L.index(value, [start, [stop]]) -- return first index of value. Each field in the {+variable} is compared with the field's `~cf.Field.equals` method (as aopposed to the ``==`` operator). It is an error if there is no such field. .. seealso:: :py:obj:`list.index` :Examples: >>> ''' try: if stop is None: (None,).index(x, start) else: (None,).index(x, start, stop) except ValueError: raise ValueError("{0} is not equal to {1!r}".format( self.__class__.__name__, x)) if not self.equals(x): raise ValueError("{0} is not equal to {1!r}".format( self.__class__.__name__, x)) return 0 #--- End: def def insert_data(self, data, copy=True): ''' Insert a new data array into the variable in place. :Parameters: data: `cf.Data` copy: `bool`, optional :Returns: `None` ''' # List functionality if self._list: for f in self: f.insert_data(data, copy=copy) return if not copy: self.Data = data else: self.Data = data.copy() #--- End: def def inspect(self): ''' Inspect the object for debugging. .. seealso:: `cf.inspect` :Returns: `None` :Examples: >>> f.inspect() ''' print cf_inspect(self) #--- End: def # def getattr(self, attr, *default): # ''' # #Get a named attribute. # #``f.getattr(attr, *default)`` is equivalent to ``getattr(f, attr, #*default)``. # #.. seealso:: `delattr`, `hasattr`, `setattr` # #:Parameters: # # attr: `str` # The attribute's name. # # default: optional # When a default argument is given, it is returned when the # attribute doesn't exist; without it, an exception is raised in # that case. # #:Returns: # # out: # The attribute's value. # #:Examples: # #>>> f.foo = -99 #>>> fl.getattr('foo') #-99 #>>> del f.foo #>>> fl.getattr('foo', 'bar') #'bar' # #''' # return getattr(self, attr, *default) # #--- End: def # # def hasattr(self, attr): # ''' # #Return whether an attribute exists. # #``f.hasattr(attr)`` is equivalent to ``hasattr(f, attr)``. # #.. seealso:: `delattr`, `getattr`, `setattr` # #:Parameters: # # attr: `str` # The attribute's name. # #:Returns: # # out: `bool` # Whether the object has the attribute. # #:Examples: # #>>> f.foo = -99 #>>> fl.hasattr('foo') #True #>>> del f.foo #>>> fl.hasattr('foo') #False # #''' # return hasattr(self, attr) # #--- End: def def getprop(self, prop, *default): ''' Get a CF property. When a default argument is given, it is returned when the attribute doesn't exist; without it, an exception is raised in that case. .. seealso:: `delprop`, `hasprop`, `setprop` :Parameters: prop: `str` The name of the CF property. default: optional Return *default* if and only if the variable does not have the named property. :Returns: out: The value of the named property, or the default value. :Raises: AttributeError : If the variable does not have the named property and a default value has not been set. :Examples: >>> f.getprop('standard_name') >>> f.getprop('standard_name', None) >>> f.getprop('foo') AttributeError: Field doesn't have CF property 'foo' >>> f.getprop('foo', 'bar') 'bar' ''' # Get a special attribute if prop in self._special_properties: return getattr(self, prop, *default) # Still here? Then get a simple attribute d = self._private['simple_properties'] if default: return d.get(prop, default[0]) elif prop in d: return d[prop] raise AttributeError("%s doesn't have CF property %r" % (self.__class__.__name__, prop)) #--- End: def # def delattr(self, attr): # ''' # #Delete an attribute. # #[+1]Note that ``f.delattr(attr)`` is equivalent to ``delattr(f, attr)``. # #.. seealso:: `getattr`, `hasattr`, `setattr` # #:Examples 1: # #>>> f.delattr('foo') # #:Parameters: # # attr: `str` # The attribute's name. # #:Returns: # # `None` # #:Examples 2: # #>>> f.getattr('foo') #'bar' # #''' # # List functionality # if self._list: # for f in self: # f.delattr(attr) # return # # delattr(self, attr) # #--- End: def def delprop(self, prop): ''' Delete a CF property. .. seealso:: `getprop`, `hasprop`, `setprop` :Examples 1: >>> f.delprop('standard_name') :Parameters: prop: `str` The name of the CF property. :Returns: `None` :Examples 2: >>> f.foo = 'bar' >>> f.delprop('foo') >>> f.delprop('foo') AttributeError: Can't delete non-existent Field CF property 'foo' ''' # List functionality if self._list: for f in self: f.delprop(prop) return # Delete a special attribute if prop in self._special_properties: delattr(self, prop) return # Still here? Then delete a simple attribute d = self._private['simple_properties'] if prop in d: del d[prop] else: raise AttributeError("Can't delete non-existent %s CF property %r" % (self.__class__.__name__, prop)) #--- End: def def name(self, default=None, identity=False, ncvar=False): '''Return a name. By default the name is the first found of the following: 1. The `standard_name` CF property. 2. The `long_name` CF property, preceeded by the string ``'long_name:'``. 3. The `!id` attribute. 4. The `!ncvar` attribute, preceeded by the string ``'ncvar%'``. 5. The value of the *default* parameter. Note that ``f.name(identity=True)`` is equivalent to ``f.identity()``. .. seealso:: `identity` :Examples 1: >>> n = f.name() >>> n = f.name(default='NO NAME')) :Parameters: default: optional If no name can be found then return the value of the *default* parameter. By default the default is `None`. identity: `bool`, optional If True then only 1., 3. and 5. are considered as possible names. ncvar: `bool`, optional If True then only 4. and 5. are considered as possible names. :Returns: out: The name. :Examples 2: >>> f.standard_name = 'air_temperature' >>> f.long_name = 'temperature of the air' >>> f.ncvar = 'tas' >>> f.name() 'air_temperature' >>> del f.standard_name >>> f.name() 'long_name:temperature of the air' >>> del f.long_name >>> f.name() 'ncvar:tas' >>> del f.ncvar >>> f.name() None >>> f.name('no_name') 'no_name' >>> f.standard_name = 'air_temperature' >>> f.name('no_name') 'air_temperature' ''' if ncvar: if identity: raise ValueError( "Can't find identity/name: ncvar and identity parameters can't both be True") n = getattr(self, 'ncvar', None) if n is not None: return 'ncvar%%%s' % n return default #--- End: if n = self.getprop('standard_name', None) if n is not None: return n if identity: n = getattr(self, 'id', None) if n is not None: return n return default n = self.getprop('long_name', None) if n is not None: return 'long_name:%s' % n n = getattr(self, 'id', None) if n is not None: return n n = getattr(self, 'ncvar', None) if n is not None: return 'ncvar%%%s' % n return default #--- End: def def HDF_chunks(self, *chunksizes): '''{+HDF_chunks} .. versionadded:: 1.1.13 :Examples 1: To define chunks which are the full size for each axis except for the first axis which is to have a chunk size of 12: >>> old_chunks = f.HDF_chunks({0: 12}) :Parameters: {+chunksizes} :Returns: out: `dict` The chunk sizes prior to the new setting, or the current current sizes if no new values are specified. ''' if self._hasData: return self.Data.HDF_chunks(*chunksizes) else: return None #--- End: def def override_calendar(self, calendar, i=False): '''{+Fef,}Override the calendar of date-time units. The new calendar **need not** be equivalent to the original one and the data array elements will not be changed to reflect the new units. Therefore, this method should only be used when it is known that the data array values are correct but the calendar has been incorrectly encoded. Not to be confused with setting `cf.Field.calendar` or `cf.Field.Units` attributes to a calendar which is equivalent to the original calendar .. seealso:: `cf.Field.calendar`, `cf.Field.override_calendar`, `cf.Field.units`, `cf.Field.Units` :Examples 1: >>> g = f.override_calendar('noleap') :Parameters: calendar: `str` The new calendar. {+i} :Returns: out: `cf.{+Variable}` :Examples 2: ''' # List functionality if self._list: kwargs2 = self._parameters(locals()) return self._list_method('override_calendar', kwargs2) if i: v = self else: v = self.copy() if v._hasData: v.Data.override_calendar(calendar, i=True) else: if not v.Units.isreftime: raise ValueError( "Can't override the calender of non-reference-time units: {0!r}".format( self.Units)) v.Units = Units(getattr(v.Units, 'units', None), calendar=calendar) return v #--- End: def def override_units(self, units, i=False): '''{+Fef,}Override the units. The new units **need not** be equivalent to the original ones and the data array elements will not be changed to reflect the new units. Therefore, this method should only be used when it is known that the data array values are correct but the units have incorrectly encoded. Not to be confused with setting `cf.Field.units` or `cf.Field.Units` attributes to units which are equivalent to the original units. .. seealso:: `cf.Field.calendar`, `cf.Field.override_units`, `cf.Field.units`, `cf.Field.Units` :Examples 1: >>> g = f.override_units('m') :Parameters: units: `str` or `cf.Units` The new units for the data array. {+i} :Returns: out: `cf.{+Variable}` :Examples 2: >>> f[+0].Units >>> f[+0].datum(0) 100000.0 >>> f.override_units('km') >>> f[+0].Units >>> f[+0].datum(0) 100000.0 >>> f.override_units(cf.Units('watts')) >>> f[+0].Units >>> f[+0].datum(0) 100000.0 ''' # List functionality if self._list: kwargs2 = self._parameters(locals()) return self._list_method('override_units', kwargs2) if i: v = self else: v = self.copy() if v._hasData: v.Data.override_units(units, i=True) else: v.Units = Units(units) return v #--- End: def def rint(self, i=False): ''' {+Fef,} round data array. The scalar ``x`` is rounded to the nearest integer ``i``. .. versionadded:: 1.0 .. seealso:: `ceil`, `floor`, `trunc` :Examples 1: Create a new {+variable} with rounded data: >>> g = f.rint() :Parameters: {+i} :Returns: out: `cf.{+Variable}` {+Fef,}The {+variable} with rounded data array values. :Examples 2: >>> print f.array [-1.9 -1.5 -1.1 -1. 0. 1. 1.1 1.5 1.9] >>> print f.rint().array [-2. -2. -1. -1. 0. 1. 1. 2. 2.] >>> print f.array [-1.9 -1.5 -1.1 -1. 0. 1. 1.1 1.5 1.9] >>> print f.rint(i=True).array [-2. -2. -1. -1. 0. 1. 1. 2. 2.] >>> print f.array [-2. -2. -1. -1. 0. 1. 1. 2. 2.] ''' # List functionality if self._list: kwargs2 = self._parameters(locals()) return self._list_method('rint', kwargs2) if not self._hasData: raise ValueError("Can't rint %r" % self.__class__.__name__) if i: v = self else: v = self.copy() v.Data.rint(i=True) return v #--- End: def def round(self, decimals=0, i=False): '''{+Fef,} evenly round elements of the data array to the given number of decimals. .. versionadded:: 1.1.4 .. seealso:: `ceil`, `floor`, `rint`, `trunc` :Parameters: decimals: `int`, optional Number of decimal places to round to (default: 0). If decimals is negative, it specifies the number of positions to the left of the decimal point. {+i} :Returns: out: `cf.{+Variable}` {+Fef,}The {+variable} with rounded data array values. :Examples: >>> print f.array [-1.81, -1.41, -1.01, -0.91, 0.09, 1.09, 1.19, 1.59, 1.99]) >>> print f.round().array [-2., -1., -1., -1., 0., 1., 1., 2., 2.] >>> print f.round(1).array [-1.8, -1.4, -1. , -0.9, 0.1, 1.1, 1.2, 1.6, 2. ] >>> print f.round(-1).array [-0., -0., -0., -0., 0., 0., 0., 0., 0.] ''' # List functionality if self._list: kwargs2 = self._parameters(locals()) return self._list_method('round', kwargs2) if not self._hasData: raise ValueError("Can't round %r" % self.__class__.__name__) if i: v = self else: v = self.copy() v.Data.round(decimals=decimals, i=True) return v #--- End: def def roll(self, iaxis, shift, i=False): ''' .. seealso:: `expand_dims`, `flip`, `squeeze`, `transpose` :Parameters: iaxis: `int` {+i} :Returns: out: `cf.{+Variable}` :Examples: ''' if not self._hasData: raise ValueError("Can't roll %r" % self.__class__.__name__) if i: v = self else: v = self.copy() v.Data.roll(iaxis, shift, i=True) return v #--- End: def # def setattr(self, attr, value): # ''' # #Set a named attribute. # #``f.setattr(attr, value)`` is equivalent to ``setattr(f, attr, #value)``. # #.. seealso:: `delattr`, `hasattr`, `getattr` # #:Parameters: # # attr: str # The attribute's name. # # value: # The value to set the attribute. # #:Returns: # # `None` # #:Examples: # #>>> f.setattr('foo', -99) #>>> f.foo #-99 # #''' # # setattr(self, attr, value) # #--- End: def def where(self, condition, x=None, y=None, i=False): ''' Set data array elements depending on a condition. .. seealso:: `cf.masked`, `hardmask`, `subspace` :Returns: out: `cf.{+Variable}` ''' if not self._hasData: raise ValueError( "ERROR: Can't set data in nonexistent data array") if isinstance(condition, Variable): if not condition._hasData: raise ValueError( "ERROR: Can't set data when %r condition has no data array" % condition.__class__.__name__) condition = condition.Data #--- End: if if x is not None and isinstance(x, Variable): if not x._hasData: raise ValueError( "ERROR: Can't set data from %r with no data array" % x.__class__.__name__) x = x.Data #--- End: if if y is not None and isinstance(y, Variable): if not y._hasData: raise ValueError( "ERROR: Can't set data from %r with no data array" % y.__class__.__name__) y = y.Data #--- End: if if i: v = self else: v = self.copy() v.Data.where(condition, x, y, i=True) return v #--- End: def #--- End: class # ==================================================================== # # SubspaceVariable object # # ==================================================================== class SubspaceVariable(object): __slots__ = ('variable',) def __init__(self, variable): ''' Set the contained variable. ''' self.variable = variable #--- End: def def __getitem__(self, indices): ''' Called to implement evaluation of x[indices]. x.__getitem__(indices) <==> x[indices] ''' variable = self.variable new = variable.copy(_omit_Data=True) if variable._hasData: new.Data = variable.Data[indices] return new #--- End: def def __setitem__(self, indices, value): ''' Called to implement assignment to x[indices] x.__setitem__(indices, value) <==> x[indices] ''' if isinstance(value, Variable): value = value.Data self.variable.Data[indices] = value #--- End: def #--- End: class