cfdm.core.constructs

Classes

Constructs([auxiliary_coordinate, ...])

A container for metadata constructs.
class cfdm.core.constructs.Constructs(auxiliary_coordinate=None, dimension_coordinate=None, domain_ancillary=None, field_ancillary=None, cell_measure=None, coordinate_reference=None, domain_axis=None, domain_topology=None, cell_connectivity=None, cell_method=None, source=None, copy=True, _use_data=True, _view=False, _ignore=())[source]

Bases: Container

A container for metadata constructs.

The following metadata constructs can be included:

  • domain axis constructs

  • dimension coordinate constructs

  • auxiliary coordinate constructs

  • coordinate reference constructs

  • domain ancillary constructs

  • cell measure constructs

  • domain topology constructs

  • cell connectivity constructs

  • cell method constructs

  • field ancillary constructs

The container is used by used by Field and Domain instances.

The container is like a dictionary in many ways, in that it stores key/value pairs where the key is the unique construct key with corresponding metadata construct value, and provides some of the usual dictionary methods.

Added in version (cfdm): 1.7.0

Initialisation

Parameters:
auxiliary_coordinate: str, optional

The base name for keys of auxiliary coordinate constructs.

Parameter example:

auxiliary_coordinate='auxiliarycoordinate'

dimension_coordinate: str, optional

The base name for keys of dimension coordinate constructs.

Parameter example:

dimension_coordinate='dimensioncoordinate'

domain_ancillary: str, optional

The base name for keys of domain ancillary constructs.

Parameter example:

domain_ancillary='domainancillary'

field_ancillary: str, optional

The base name for keys of field ancillary constructs.

Parameter example:

field_ancillary='fieldancillary'

cell_measure: str, optional

The base name for keys of cell measure constructs.

Parameter example:

cell_measure='cellmeasure'

coordinate_reference: str, optional

The base name for keys of coordinate reference constructs.

Parameter example:

coordinate_reference='coordinatereference'

domain_axis: str, optional

The base name for keys of domain axis constructs.

Parameter example:

domain_axis='domainaxis'

domain_topology: str, optional

The base name for keys of domain topology constructs.

Parameter example:

'domaintopology'

Added in version (cfdm): 1.11.0.0

cell_connectivity: str, optional

The base name for keys of cell connectivity constructs.

Parameter example:

'cellconnectivity'

Added in version (cfdm): 1.11.0.0

cell_method: str, optional

The base name for keys of cell method constructs.

Parameter example:

cell_method='cellmethod'

source: optional

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

All other parameters, apart from copy, are ignored and their values are instead inferred from source by assuming that it has the Constructs 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 Constructs instance then cfdm.core.Constructs(source=x) is equivalent to x.copy().

copy: bool, optional

If True (the default) then deep copy metadata constructs from those of source prior to initialisation, else they are not deep copied.

_ignore: sequence of str, optional

Ignores the given construct types.

Parameter example:

_ignore=('cell_method', 'field_ancillary')

construct_type(key)[source]

Return the type of a construct for a given key.

Added in version (cfdm): 1.7.0

See also

construct_types

Parameters:
key: str

A construct identifier.

Returns:
str or None

The construct type, or None if the key is not present.

construct_types()[source]

Return all of the construct types for all keys.

Added in version (cfdm): 1.7.0

See also

construct_type

copy(data=True)[source]

Return a deep copy.

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

Added in version (cfdm): 1.7.0

Parameters:
data: bool, optional

If True (the default) then copy data contained in the metadata construct(s), else the data is not copied.

Returns:
Constructs

The deep copy.

Examples

>>> f = cfdm.core.example_field(0)
>>> c = f.constructs
>>> k = c.copy()
>>> k = c.copy(data=False)
data_axes()[source]

Returns the axes spanned by the data.

Specifically, returns the domain axis constructs spanned by metadata construct data.

Added in version (cfdm): 1.7.0

Returns:
dict

The keys of the domain axes constructs spanned by metadata construct data.

Examples

>>> f = cfdm.core.example_field(0)
>>> c = f.constructs
>>> print(c)
Constructs:
{'cellmethod0': <CellMethod: area: mean>,
 'dimensioncoordinate0': <DimensionCoordinate: latitude(5) degrees_north>,
 'dimensioncoordinate1': <DimensionCoordinate: longitude(8) degrees_east>,
 'dimensioncoordinate2': <DimensionCoordinate: time(1) days since 2018-12-01 >,
 'domainaxis0': <DomainAxis: size(5)>,
 'domainaxis1': <DomainAxis: size(8)>,
 'domainaxis2': <DomainAxis: size(1)>}
>>> c.data_axes()
{'dimensioncoordinate0': ('domainaxis0',),
 'dimensioncoordinate1': ('domainaxis1',),
 'dimensioncoordinate2': ('domainaxis2',)}
filter_by_type(*types, todict=True, cached=None)[source]

Select metadata constructs by type.

Added in version (cfdm): 1.7.0

Parameters:
types: optional

Select constructs that have are of any of the given types.

A type is specified by one of the following strings:

type

Construct selected

'domain_ancillary'

Domain ancillary

'dimension_coordinate'

Dimension coordinate

'domain_axis'

Domain axis

'auxiliary_coordinate'

Auxiliary coordinate

'cell_measure'

Cell measure

'coordinate_reference'

Coordinate reference

'domain_topology'

Domain topology

'cell_connectivity'

Cell connectivity

'cell_method'

Cell method

'field_ancillary'

Field ancillary

If no types are provided then all constructs are selected.

Parameters:
todict: bool, optional

If True then return a dictionary of constructs keyed by their construct identifiers, instead of a Constructs object. This is a faster option.

cached: optional

If any value other than None then return cached without selecting any constructs.

Returns:
Constructs or dict

The selected constructs and their construct keys.

Examples

Select dimension coordinate constructs:

>>> f = cfdm.core.example_field(1)
>>> c = f.constructs
>>> d = c.filter_by_type('dimension_coordinate')
>>> d
<Constructs: dimension_coordinate(4)>

Select dimension coordinate and field ancillary constructs:

>>> k = c.filter_by_type(
...     'dimension_coordinate', 'field_ancillary')
>>> k
<Constructs: dimension_coordinate(4), field_ancillary(1)>
get(key, default=None)[source]

Returns the construct for the key, else default.

Added in version (cfdm): 1.7.0

See also

items, keys, values

get_data_axes(key, default=ValueError())[source]

Return the keys of the axes spanned by a construct’s data.

Specifically, returns the keys of the domain axis constructs spanned by the data of a metadata construct.

Added in version (cfdm): 1.8.9.0

Parameters:
key: str

Specify a metadata construct.

Parameter example:

key='auxiliarycoordinate0'

default: optional

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

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

Returns:
tuple

The keys of the domain axis constructs spanned by the data.

items()[source]

Return the items as (construct key, construct) pairs.

Added in version (cfdm): 1.7.0

See also

get, keys, values

Returns:
dict_items

The construct key and constructs respectively as key-value pairs in a Python dict_items iterator.

Examples

>>> f = cfdm.core.example_field(0)
>>> c = f.constructs
>>> c_items = c.items()
>>> print(c_items)
dict_items([('dimensioncoordinate0', <DimensionCoordinate: latitude(5) degrees_north>),
            ('dimensioncoordinate1', <DimensionCoordinate: longitude(8) degrees_east>),
            ('dimensioncoordinate2', <DimensionCoordinate: time(1) days since 2018-12-01 >),
            ('domainaxis0', <DomainAxis: size(5)>),
            ('domainaxis1', <DomainAxis: size(8)>),
            ('domainaxis2', <DomainAxis: size(1)>),
            ('cellmethod0', <CellMethod: area: mean>)])
>>> type(c_items)
<class 'dict_items'>
>>> dict(c_items)
{'dimensioncoordinate0': <DimensionCoordinate: latitude(5) degrees_north>,
 'dimensioncoordinate1': <DimensionCoordinate: longitude(8) degrees_east>,
 'dimensioncoordinate2': <DimensionCoordinate: time(1) days since 2018-12-01 >,
 'cellmethod0': <CellMethod: area: mean>,
 'domainaxis0': <DomainAxis: size(5)>,
 'domainaxis1': <DomainAxis: size(8)>,
 'domainaxis2': <DomainAxis: size(1)>}
key(default=ValueError())[source]

Return the construct key of the sole metadata construct.

Added in version (cfdm): 1.7.0

See also

get, keys, value

Parameters:
default: optional

Return the value of the default parameter if there is not exactly one construct.

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

Returns:
str

The construct key.

Examples

>>> f = cfdm.core.Field()
>>> c = f.constructs
>>> d = cfdm.core.DimensionCoordinate(
...     properties={
...         'standard_name': 'latitude', 'units': 'degrees_north'},
...     data=cfdm.core.Data(range(5))
... )
>>> c._set_construct(d)
'dimensioncoordinate0'
>>> print(c)
Constructs:
{'dimensioncoordinate0': <DimensionCoordinate: latitude(5) degrees_north>}
>>> c.key()
'dimensioncoordinate0'
>>> c.value()
<DimensionCoordinate: latitude(5) degrees_north>
keys()[source]

Return all of the construct keys, in arbitrary order.

Added in version (cfdm): 1.7.0

See also

get, items, values

Returns:
dict_keys

The construct keys as a Python dict_keys iterator.

Examples

>>> f = cfdm.core.example_field(0)
>>> c = f.constructs
>>> c_keys = c.keys()
>>> print(c_keys)
dict_keys(['domainaxis0',
           'domainaxis1',
           'domainaxis2',
           'dimensioncoordinate0',
           'dimensioncoordinate1',
           'dimensioncoordinate2',
           'cellmethod0'])
>>> type(c_keys)
<class 'dict_keys'>
>>> list(c_keys)
['domainaxis0',
 'domainaxis1',
 'domainaxis2',
 'dimensioncoordinate0',
 'dimensioncoordinate1',
 'dimensioncoordinate2',
 'cellmethod0']
new_identifier(construct_type)[source]

Return a new, unused construct key.

Added in version (cfdm): 1.7.0

Parameters:
construct_type: str

The construct type for which the identifier is being created.

Parameter example:

construct_type='dimension_coordinate'

Returns:
str

The new construct identifier.

Examples

>>> f = cfdm.core.example_field(0)
>>> c = f.constructs
>>> c.keys()
['domainaxis0',
 'domainaxis1',
 'domainaxis2',
 'dimensioncoordinate0',
 'dimensioncoordinate1',
 'dimensioncoordinate2',
 'cellmethod0']
>>> c.new_identifier('domain_axis')
'domainaxis3'
>>> c.new_identifier('cell_method')
'cellmethod1'
replace(key, construct, axes=None, copy=True)[source]

Replace one metadata construct with another.

Note

No checks on the axes are done.

shallow_copy(_ignore=None)[source]

Return a shallow copy.

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

Any in-place changes to the actual constructs of the copy will not be seen in the original Constructs object, and vice versa, but the copy and filter history are otherwise independent.

Added in version (cfdm): 1.8.9.0

See also

view

Returns:
Constructs

The shallow copy.

Examples

>>> f = cfdm.core.example_field(0)
>>> c = f.constructs
>>> k = c.shallow_copy()
todict(copy=False)[source]

Return a dictionary of the metadata constructs.

Added in version (cfdm): 1.8.9.0

Parameters:
copy: bool, optional

If True then deep copy the metadata construct values.

Returns:
dict

The dictionary representation, keyed by construct identifiers with metadata construct values.

value(default=ValueError())[source]

Return the sole metadata construct.

Added in version (cfdm): 1.7.0

See also

get, key, values

Parameters:
default: optional

Return the value of the default parameter if there is not exactly one construct.

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

Returns:

The metadata construct.

Examples

>>> f = cfdm.core.Field()
>>> c = f.constructs
>>> d = cfdm.core.DimensionCoordinate(
...     properties={
...         'standard_name': 'latitude', 'units': 'degrees_north'},
...     data=cfdm.core.Data(range(5))
... )
>>> c._set_construct(d)
'dimensioncoordinate0'
>>> print(c)
Constructs:
{'dimensioncoordinate0': <DimensionCoordinate: latitude(5) degrees_north>}
>>> c.key()
'dimensioncoordinate0'
>>> c.value()
<DimensionCoordinate: latitude(5) degrees_north>
values()[source]

Return all of the metadata constructs, in arbitrary order.

Added in version (cfdm): 1.7.0

See also

get, items, keys

Returns:
dict_values

The constructs as a Python dict_values iterator.

Examples

>>> f = cfdm.core.example_field(0)
>>> c = f.constructs
>>> c_values = c.values()
>>> print(c_values)
dict_values([<DimensionCoordinate: latitude(5) degrees_north>,
             <DimensionCoordinate: longitude(8) degrees_east>,
             <DimensionCoordinate: time(1) days since 2018-12-01 >,
             <DomainAxis: size(5)>,
             <DomainAxis: size(8)>,
             <DomainAxis: size(1)>,
             <CellMethod: area: mean>])
>>> type(c_values)
<class 'dict_values'>
>>> list(c_values)
[<DimensionCoordinate: latitude(5) degrees_north>,
 <DimensionCoordinate: longitude(8) degrees_east>,
 <DimensionCoordinate: time(1) days since 2018-12-01 >,
 <DomainAxis: size(5)>,
 <DomainAxis: size(8)>,
 <DomainAxis: size(1)>,
 <CellMethod: area: mean>]