cfdm.core.bounds

Classes

Bounds(*args, **kwargs)

A cell bounds component.

class cfdm.core.bounds.Bounds(*args, **kwargs)

Bases: PropertiesData

A cell bounds component.

That is, a cell bounds component of a coordinate or domain ancillary construct of the CF data model.

An array of cell bounds spans the same domain axes as its coordinate array, with the addition of an extra dimension whose size is that of the number of vertices of each cell. This extra dimension does not correspond to a domain axis construct since it does not relate to an independent axis of the domain. Note that, for climatological time axes, the bounds are interpreted in a special way indicated by the cell method constructs.

Added in version (cfdm): 1.7.0

Initialisation

Parameters:

properties: dict, optional

Set descriptive properties. The dictionary keys are property names, with corresponding values.

Properties may also be set after initialisation with the set_properties and set_property methods.

Parameter example:

properties={'standard_name': 'longitude'}

data: data_like, optional

Set the data.

A data_like object is any object that can be converted to a Data object, i.e. numpy array_like objects, Data objects, and cfdm.core instances that contain Data objects.

The data also may be set after initialisation with the set_data method.

source: optional

Convert source, which can be any type of object, to a Bounds instance.

All other parameters, apart from copy, are ignored and their values are instead inferred from source by assuming that it has the Bounds API. Any parameters that can not be retrieved from source in this way are assumed to have their default value.

Note that if x is also a Bounds instance then cfdm.core.Bounds(source=x) is equivalent to x.copy().

copy: bool, optional

If True (the default) then deep copy the input parameters prior to initialisation. By default the parameters are not deep copied.

clear_properties()

Remove all properties.

Added in version (cfdm): 1.7.0

See also

del_properties, del_property, properties, set_properties

Returns:

dict

The properties that have been removed.

Examples

>>> f = cfdm.core.Bounds()
>>> f.properties()
{}
>>> f.set_properties({'standard_name': 'air_pressure',
...                   'long_name': 'Air Pressure'})
>>> f.properties()
{'standard_name': 'air_pressure',
 'long_name': 'Air Pressure'}
>>> f.set_properties({'standard_name': 'air_pressure', 'foo': 'bar'})
>>> f.properties()
{'standard_name': 'air_pressure',
 'long_name': 'Air Pressure',
 'foo': 'bar'}
>>> f.clear_properties()
{'standard_name': 'air_pressure',
 'long_name': 'Air Pressure',
 'foo': 'bar'}
>>> f.properties()
{}

copy(data=True)

Return a deep copy.

f.copy() is equivalent to copy.deepcopy(f).

Arrays within Data instances are copied with a copy-on-write technique. This means that a copy takes up very little extra memory, even when the original contains very large data arrays, and the copy operation is fast.

Added in version (cfdm): 1.7.0

Parameters:

data: bool, optional

If True (the default) then copy data, else the data is not copied.

Returns:

Bounds

The deep copy.

Examples

>>> g = f.copy()
>>> g = f.copy(data=False)
>>> g.has_data()
False

del_data(default=ValueError())

Remove the data.

Added in version (cfdm): 1.7.0

See also

data, get_data, has_data, set_data

Parameters:

default: optional

Return the value of the default parameter if data have not been set.

If set to an Exception instance then it will be raised instead.

Returns:

Data

The removed data.

Examples

>>> f = cfdm.core.Bounds()
>>> f.set_data([1, 2, 3])
>>> f.has_data()
True
>>> f.get_data()
<Data(3): [1, 2, 3]>
>>> f.data
<Data(3): [1, 2, 3]>
>>> f.del_data()
<Data(3): [1, 2, 3]>
>>> g = f.set_data([4, 5, 6], inplace=False)
>>> g.data
<Data(3): [4, 5, 6]>
>>> f.has_data()
False
>>> print(f.get_data(None))
None
>>> print(f.del_data(None))
None

del_properties(properties)

Remove properties.

Added in version (cfdm): 1.10.0.3

See also

clear_properties, del_property, properties, set_properties

Parameters:

properties: (sequence of) str

The names of the properties to be removed. If the Bounds does not have a particular property then that property is ignored. No properties are removed if properties is an empty sequence.

Parameter example:

'long_name'

Parameter example:

['long_name', 'comment']

Returns:

dict

The removed property values, keyed by property name.

Examples

>>> f = cfdm.core.Bounds()
>>> f.set_properties({'project': 'CMIP7', 'comment': 'model'})
>>> removed_properties = f.del_properties('project')
>>> removed_properties
{'project': 'CMIP7'}
>>> f.properties()
{'comment': 'model'}
>>> f.set_properties(removed_properties)
>>> f.properties()
{'comment': 'model', 'project': 'CMIP7'}
>>> f.del_properties('foo')
{}

del_property(prop, default=ValueError())

Remove a property.

Added in version (cfdm): 1.7.0

See also

clear_properties, get_property, has_property, properties, set_property

Parameters:

prop: str

The name of the property to be removed.

Parameter example:

prop='long_name'

default: optional

Return the value of the default parameter if the property has not been set.

If set to an Exception instance then it will be raised instead.

Returns:

The removed property value.

Examples

>>> f = cfdm.core.Bounds()
>>> f.set_property('project', 'CMIP7')
>>> f.has_property('project')
True
>>> f.get_property('project')
'CMIP7'
>>> f.del_property('project')
'CMIP7'
>>> f.has_property('project')
False
>>> print(f.del_property('project', None))
None
>>> print(f.get_property('project', None))
None

get_data(default=ValueError(), _units=True, _fill_value=True)

Return the data.

Note that a Data instance is returned. Use its array attribute to return the data as an independent numpy array.

The units, calendar and fill value properties are, if set, inserted into the data.

Added in version (cfdm): 1.7.0

See also

cfdm.core.Data.array, data, del_data, has_data, set_data

Parameters:

default: optional

Return the value of the default parameter if data have not been set.

If set to an Exception instance then it will be raised instead.

Returns:

Data

The data.

Examples

>>> f = cfdm.core.Bounds()
>>> f.set_data([1, 2, 3])
>>> f.has_data()
True
>>> f.get_data()
<Data(3): [1, 2, 3]>
>>> f.data
<Data(3): [1, 2, 3]>
>>> f.del_data()
<Data(3): [1, 2, 3]>
>>> g = f.set_data([4, 5, 6], inplace=False)
>>> g.data
<Data(3): [4, 5, 6]>
>>> f.has_data()
False
>>> print(f.get_data(None))
None
>>> print(f.del_data(None))
None

get_property(prop, default=ValueError())

Return a property.

Added in version (cfdm): 1.7.0

See also

del_property, has_property, properties, set_property

Parameters:

prop: str

The name of the property to be returned.

Parameter example:

prop='standard_name'

default: optional

Return the value of the default parameter if the property has not been set.

If set to an Exception instance then it will be raised instead.

Returns:

The value of the property.

Examples

>>> f = cfdm.core.Bounds()
>>> f.set_property('project', 'CMIP7')
>>> f.has_property('project')
True
>>> f.get_property('project')
'CMIP7'
>>> f.del_property('project')
'CMIP7'
>>> f.has_property('project')
False
>>> print(f.del_property('project', None))
None
>>> print(f.get_property('project', None))
None

has_bounds()

Whether or not there are cell bounds.

This is always False.

Added in version (cfdm): 1.7.4

See also

has_data

Returns:

bool

Always False.

Examples

>>> f = cfdm.core.Bounds()
>>> f.has_bounds()
False

has_data()

Whether or not the construct has data.

Added in version (cfdm): 1.7.0

See also

data, del_data, get_data, set_data

Returns:

bool

True if data have been set, otherwise False.

Examples

>>> f = cfdm.core.Bounds()
>>> f.set_data([1, 2, 3])
>>> f.has_data()
True
>>> f.get_data()
<Data(3): [1, 2, 3]>
>>> f.data
<Data(3): [1, 2, 3]>
>>> f.del_data()
<Data(3): [1, 2, 3]>
>>> g = f.set_data([4, 5, 6], inplace=False)
>>> g.data
<Data(3): [4, 5, 6]>
>>> f.has_data()
False
>>> print(f.get_data(None))
None
>>> print(f.del_data(None))
None

has_property(prop)

Whether a property has been set.

Added in version (cfdm): 1.7.0

See also

del_property, get_property, properties, set_property

Parameters:

prop: str

The name of the property.

Parameter example:

prop='long_name'

Returns:

bool

True if the property has been set, otherwise False.

Examples

>>> f = cfdm.core.Bounds()
>>> f.set_property('project', 'CMIP7')
>>> f.has_property('project')
True
>>> f.get_property('project')
'CMIP7'
>>> f.del_property('project')
'CMIP7'
>>> f.has_property('project')
False
>>> print(f.del_property('project', None))
None
>>> print(f.get_property('project', None))
None

properties()

Return all properties.

Added in version (cfdm): 1.7.0

See also

clear_properties, get_property, has_property set_properties

Returns:

dict

The properties.

Examples

>>> f = cfdm.core.Bounds()
>>> f.properties()
{}
>>> f.set_properties({'standard_name': 'air_pressure',
...                   'long_name': 'Air Pressure'})
>>> f.properties()
{'standard_name': 'air_pressure',
 'long_name': 'Air Pressure'}
>>> f.set_properties({'standard_name': 'air_pressure', 'foo': 'bar'})
>>> f.properties()
{'standard_name': 'air_pressure',
 'long_name': 'Air Pressure',
 'foo': 'bar'}
>>> f.clear_properties()
{'standard_name': 'air_pressure',
 'long_name': 'Air Pressure',
 'foo': 'bar'}
>>> f.properties()
{}

set_data(data, copy=True, inplace=True)

Set the data.

The units, calendar and fill value of the incoming Data instance are removed prior to insertion.

Added in version (cfdm): 1.7.0

See also

data, del_data, get_data, has_data

Parameters:

data: data_like

The data to be inserted.

A data_like object is any object that can be converted to a Data object, i.e. numpy array_like objects, Data objects, and cfdm.core instances that contain Data objects.

copy: bool, optional

If True (the default) then copy the data prior to insertion, else the data is not copied.

inplace: bool, optional:

If True (the default) then do the operation in-place and return None. If False a new, modified Bounds instance is returned.

Added in version (cfdm): 1.8.7.0

Returns:

None or Bounds

If the operation was in-place then None is returned, otherwise return a new Bounds instance containing the new data.

Examples

>>> f = cfdm.core.Bounds()
>>> f.set_data([1, 2, 3])
>>> f.has_data()
True
>>> f.get_data()
<Data(3): [1, 2, 3]>
>>> f.data
<Data(3): [1, 2, 3]>
>>> f.del_data()
<Data(3): [1, 2, 3]>
>>> g = f.set_data([4, 5, 6], inplace=False)
>>> g.data
<Data(3): [4, 5, 6]>
>>> f.has_data()
False
>>> print(f.get_data(None))
None
>>> print(f.del_data(None))
None

set_properties(properties, copy=True)

Set properties.

Added in version (cfdm): 1.7.0

See also

clear_properties, properties, set_property

Parameters:

properties: dict

Store the properties from the dictionary supplied.

Parameter example:

properties={'standard_name': 'altitude', 'foo': 'bar'}

copy: bool, optional

If False then any property values provided by the properties parameter are not copied before insertion. By default they are deep copied.

Returns:

None

Examples

>>> f = cfdm.core.Bounds()
>>> f.properties()
{}
>>> f.set_properties({'standard_name': 'air_pressure',
...                   'long_name': 'Air Pressure'})
>>> f.properties()
{'standard_name': 'air_pressure',
 'long_name': 'Air Pressure'}
>>> f.set_properties({'standard_name': 'air_pressure', 'foo': 'bar'})
>>> f.properties()
{'standard_name': 'air_pressure',
 'long_name': 'Air Pressure',
 'foo': 'bar'}
>>> f.clear_properties()
{'standard_name': 'air_pressure',
 'long_name': 'Air Pressure',
 'foo': 'bar'}
>>> f.properties()
{}

set_property(prop, value, copy=True)

Set a property.

Added in version (cfdm): 1.7.0

See also

del_property, get_property, has_property, properties, set_properties

Parameters:

prop: str

The name of the property to be set.

value:

The value for the property.

copy: bool, optional

If True then set a deep copy of value.

Returns:

None

Examples

>>> f = cfdm.core.Bounds()
>>> f.set_property('project', 'CMIP7')
>>> f.has_property('project')
True
>>> f.get_property('project')
'CMIP7'
>>> f.del_property('project')
'CMIP7'
>>> f.has_property('project')
False
>>> print(f.del_property('project', None))
None
>>> print(f.get_property('project', None))
None

property data

The data.

f.data is equivalent to f.get_data().

Note that a Data instance is returned. Use the array attribute to get the data as a numpy array.

The units, calendar and fill value properties are, if set, inserted into the data.

Added in version (cfdm): 1.7.0

See also

cfdm.core.Data.array, del_data, get_data, has_data, set_data

Returns:

Data

The data.

Examples

>>> f = cfdm.core.Bounds()
>>> f.set_data(cfdm.core.Data(numpy.arange(10.)))
>>> f.has_data()
True
>>> d = f.data
>>> d
<Data(10): [0.0, ..., 9.0]>
>>> f.data.shape
(10,)

property dtype

Data-type of the data elements.

Examples

>>> d.dtype
dtype('float64')
>>> type(d.dtype)
<type 'numpy.dtype'>

property ndim

The number of data dimensions.

Only dimensions that correspond to domain axis constructs are included.

See also

data, has_data, isscalar, shape, size

Examples

>>> f.shape
(73, 96)
>>> f.ndim
2
>>> f.size
7008

>>> f.shape
(73, 1, 96)
>>> f.ndim
3
>>> f.size
7008

>>> f.shape
(73,)
>>> f.ndim
1
>>> f.size
73

>>> f.shape
()
>>> f.ndim
0
>>> f.size
1

property shape

A tuple of the data array’s dimension sizes.

Only dimensions that correspond to domain axis constructs are included.

See also

data, has_data, ndim, size

Examples

>>> f.shape
(73, 96)
>>> f.ndim
2
>>> f.size
7008

>>> f.shape
(73, 1, 96)
>>> f.ndim
3
>>> f.size
7008

>>> f.shape
(73,)
>>> f.ndim
1
>>> f.size
73

>>> f.shape
()
>>> f.ndim
0
>>> f.size
1

property size

The number elements in the data.

size is equal to the product of shape, that only includes the sizes of dimensions that correspond to domain axis constructs.

See also

data, has_data, ndim, shape

Examples

>>> f.shape
(73, 96)
>>> f.ndim
2
>>> f.size
7008

>>> f.shape
(73, 1, 96)
>>> f.ndim
3
>>> f.size
7008

>>> f.shape
(73,)
>>> f.ndim
1
>>> f.size
73

>>> f.shape
()
>>> f.ndim
0
>>> f.size
1