cfdm.index¶

Classes

Index(*args, **kwargs)

An index variable required to uncompress a ragged array.

class cfdm.index.Index(*args, **kwargs)[source]¶

Bases: NetCDFVariable, NetCDFDimension, NetCDFSampleDimension, PropertiesData, Files, PropertiesData

An index variable required to uncompress a ragged array.

A collection of features stored using an indexed ragged array combines all features along a single dimension (the sample dimension) such that the values of each feature in the collection are interleaved.

The information needed to uncompress the data is stored in an index variable that specifies the feature that each element of the sample dimension belongs to.

NetCDF interface

The netCDF variable name may be accessed with the nc_set_variable, nc_get_variable, nc_del_variable, and nc_has_variable methods.

The netCDF variable group structure may be accessed with the nc_set_variable, nc_get_variable, nc_variable_groups, nc_clear_variable_groups, and nc_set_variable_groups methods.

The dataset chunks may be accessed with the nc_dataset_chunksizes, nc_set_dataset_chunksizes, and nc_clear_datset_chunksizes methods.

The name of the netCDF dimension spanned by the index variable’s data (which does not correspond to a domain axis construct) may be accessed with the nc_set_dimension, nc_get_dimension, nc_del_dimension, and nc_has_dimension methods.

The name of the netCDF sample dimension spanned by the compressed data (which does not correspond to a domain axis contract) may be accessed with the nc_set_sample_dimension, nc_get_sample_dimension, nc_del_sample_dimension, and nc_has_sample_dimension methods.

Note

The netCDF sample dimension and the netCDF dimension spanned by the index variable’s data are should be the same, unless the compressed data is an indexed contiguous ragged array, in which case they must be different.

The name of the netCDF instance dimension (that is stored in the “instance_dimension” netCDF attribute) is accessed via the corresponding domain axis construct.

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': 'altitude'}

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 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 Index instance.

All other parameters, apart from copy, are ignored and their values are instead inferred from source by assuming that it has the Index 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 Index instance then cfdm.Index(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.

apply_masking(*args, **kwargs)[source]¶

Apply masking as defined by the CF conventions.

Masking is applied according to any of the following criteria that are applicable:

where data elements are equal to the value of the missing_value property;
where data elements are equal to the value of the _FillValue property;
where data elements are strictly less than the value of the valid_min property;
where data elements are strictly greater than the value of the valid_max property;
where data elements are within the inclusive range specified by the two values of valid_range property.

If any of the above properties have not been set the no masking is applied for that method.

Elements that are already masked remain so.

Note

If using the apply_masking method on a construct that has been read from a dataset with the mask=False parameter to the read function, then the mask defined in the dataset can only be recreated if the missing_value, _FillValue, valid_min, valid_max, and valid_range properties have not been updated.

Added in version (cfdm): 1.8.2

See also

Data.apply_masking, read, write

Parameters:

inplace: bool, optional: If True then do the operation in-place and return None.

Returns:

A new instance with masked values, or None if the operation was in-place.

Examples

>>> print(v.data.array)
[9.96920997e+36, 9.96920997e+36, 9.96920997e+36, 9.96920997e+36,
 9.96920997e+36, 9.96920997e+36, 9.96920997e+36, 9.96920997e+36],
 [0.023 0.036 0.045 0.062 0.046 0.073 0.006 0.066]
 [0.11  0.131 0.124 0.146 0.087 0.103 0.057 0.011]
 [0.029 0.059 0.039 0.07  0.058 0.072 0.009 0.017]
[9.96920997e+36, 9.96920997e+36, 9.96920997e+36, 9.96920997e+36,
 9.96920997e+36, 9.96920997e+36, 9.96920997e+36, 9.96920997e+36]])
>>> masked_v = v.apply_masking()
>>> print(masked_v.data.array)
[[   --    --    --    --    --    --    --    --]
 [0.023 0.036 0.045 0.062 0.046 0.073 0.006 0.066]
 [0.11  0.131 0.124 0.146 0.087 0.103 0.057 0.011]
 [0.029 0.059 0.039 0.07  0.058 0.072 0.009 0.017]
 [   --    --    --    --    --    --    --    --]]

clear_properties()[source]¶

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.Index()
>>> 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()
{}

classmethod concatenate(variables, axis=0, cull_graph=False, relaxed_units=False, copy=True)[source]¶

Join a together sequence of Index.

Added in version (cfdm): 1.12.0.0

See also

Data.concatenate, Data.cull_graph

Parameters:

variables: sequence of constructs.

axis: int, optional: Select the axis along which to concatenate, defined by its position in the data array. By default concatenation is along the axis in position 0.
cull_graph: bool, optional: If True then unnecessary tasks are removed (culled) from each array’s dask graph before concatenation. This process can have a considerable overhead but can sometimes improve the overall performance of a workflow. If False (the default) then dask graphs are not culled. See dask.optimization.cull for details.
relaxed_units: bool, optional: If True then allow the concatenation of data with invalid but otherwise equal units. By default, if any data array has invalid units then the concatenation will fail. A Units object is considered to be invalid if its !isvalid attribute is False.
copy: bool, optional: If True (the default) then make copies of the Index objects prior to the concatenation, thereby ensuring that the input constructs are not changed by the concatenation process. If False then some or all input constructs might be changed in-place, but the concatenation process will be faster.

Returns:

Index: The concatenated construct.

copy(data=True)[source]¶

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:

Index: The deep copy.

Examples

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

creation_commands(representative_data=False, namespace=None, indent=0, string=True, name='c', data_name='data', quantization_name='q', header=True)[source]¶

Return the commands that would create the construct.

Added in version (cfdm): 1.8.7.0

See also

cfdm.Data.creation_commands, cfdm.Field.creation_commands

Parameters:

representative_data: bool, optional

Return one-line representations of Data instances, which are not executable code but prevent the data being converted in its entirety to a string representation.

namespace: str, optional

The name space containing classes of the cfdm package. This is prefixed to the class name in commands that instantiate instances of cfdm objects. By default, or if None, the name space is assumed to be consistent with cfdm being imported as import cfdm.

Parameter example:: If cfdm was imported as import cfdm as xyz then set namespace='xyz'
Parameter example:: If cfdm was imported as from cfdm import * then set namespace=''

indent: int, optional

Indent each line by this many spaces. By default no indentation is applied. Ignored if string is False.

string: bool, optional

If False then return each command as an element of a list. By default the commands are concatenated into a string, with a new line inserted between each command.

name: str, optional

The name of the Index instance created by the returned commands.

data_name: str, optional

The name of the construct’s Data instance created by the returned commands.

quantization_name: str, optional

The name of the construct’s Quantization instance created by the returned commands.

Added in version (cfdm): 1.12.2.0

header: bool, optional

If True (the default) output a comment describing the components. If False no such comment is returned.

Returns:

str or list: The commands in a string, with a new line inserted between each command. If string is False then the separate commands are returned as each element of a list.

Examples

>>> x = cfdm.Index(
...     properties={'units': 'Kelvin',
...                 'standard_name': 'air_temperature'}
... )
>>> x.set_data([271.15, 274.15, 280])
>>> print(x.creation_commands(header=False))
c = cfdm.Index()
c.set_properties({'units': 'Kelvin', 'standard_name': 'air_temperature'})
data = cfdm.Data([271.15, 274.15, 280.0], units='Kelvin', dtype='f8')
c.set_data(data)

del_data(default=ValueError())[source]¶

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.Index()
>>> 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)[source]¶

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 Index 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.Index()
>>> 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())[source]¶

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.Index()
>>> 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

dump(display=True, _key=None, _title=None, _create_title=True, _prefix='', _level=0, _omit_properties=None, _axes=None, _axis_names=None)[source]¶

A full description of the index variable.

Returns a description of all properties, including those of components, and provides selected values of all data arrays.

Added in version (cfdm): 1.7.0

Parameters:

display: bool, optional: If False then return the description as a string. By default the description is printed.

Returns:

str or None: The description. If display is True then the description is printed and None is returned. Otherwise the description is returned as a string.

equals(**kwargs)[source]¶

Whether two instances are the same.

Equality is strict by default. This means that:

the same descriptive properties must be present, with the same values and data types, and vector-valued properties must also have same the size and be element-wise equal (see the ignore_properties and ignore_data_type parameters), and

if there are data arrays then they must have same shape and data type, the same missing data mask, and be element-wise equal (see the ignore_data_type parameter).

Two real numbers x and y are considered equal if |x-y|<=atol+rtol|y|, where atol (the tolerance on absolute differences) and rtol (the tolerance on relative differences) are positive, typically very small numbers. See the atol and rtol parameters.

Any type of object may be tested but, in general, equality is only possible with another object of the same type, or a subclass of one. See the ignore_type parameter.

Any compression is ignored by default, with only the arrays in their uncompressed forms being compared. See the ignore_compression parameter.

NetCDF elements, such as netCDF variable and dimension names, do not constitute part of the CF data model and so are not checked.

Added in version (cfdm): 1.7.0

Parameters:

other:

The object to compare for equality.

atol: number, optional

The tolerance on absolute differences between real numbers. The default value is set by the cfdm.atol function.

rtol: number, optional

The tolerance on relative differences between real numbers. The default value is set by the cfdm.rtol function.

ignore_fill_value: bool, optional

If True then all _FillValue and missing_value properties are omitted from the comparison.

verbose: int or str or None, optional

If an integer from -1 to 3, or an equivalent string equal ignoring case to one of:

'DISABLE' (0)
'WARNING' (1)
'INFO' (2)
'DETAIL' (3)
'DEBUG' (-1)

set for the duration of the method call only as the minimum cut-off for the verboseness level of displayed output (log) messages, regardless of the globally-configured cfdm.log_level. Note that increasing numerical value corresponds to increasing verbosity, with the exception of -1 as a special case of maximal and extreme verbosity.

Otherwise, if None (the default value), output messages will be shown according to the value of the cfdm.log_level setting.

Overall, the higher a non-negative integer or equivalent string that is set (up to a maximum of 3/'DETAIL') for increasing verbosity, the more description that is printed to convey information about the operation.

ignore_properties: (sequence of) str, optional

The names of properties to omit from the comparison.

ignore_data_type: bool, optional

If True then ignore the data types in all numerical comparisons. By default different numerical data types imply inequality, regardless of whether the elements are within the tolerance for equality.

ignore_compression: bool, optional

If False then the compression type and, if applicable, the underlying compressed arrays must be the same, as well as the arrays in their uncompressed forms. By default only the the arrays in their uncompressed forms are compared.

ignore_type: bool, optional

Any type of object may be tested but, in general, equality is only possible with another Index instance, or a subclass of one. If ignore_type is True then cfdm.Index(source=other) is tested, rather than the other defined by the other parameter.

Returns:

bool: Whether the two instances are equal.

Examples

>>> x.equals(x)
True
>>> x.equals(x.copy())
True
>>> x.equals('something else')
False

file_directories()[source]¶

The directories of files containing parts of the data.

Returns the locations of any files referenced by the data.

Added in version (cfdm): 1.12.0.0

See also

get_filenames, replace_directory

Returns:

set: The unique set of file directories as absolute paths.

Examples

>>> d.file_directories()
{'/home/data1', 'file:///data2'}

get_data(default=ValueError(), _units=True, _fill_value=True)[source]¶

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.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.Index()
>>> 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_filenames(normalise=True)[source]¶

Return the name of the file or files containing the data.

Parameters:

normalise: bool, optional: If True then normalise to an absolute path. If False (the default) then no normalisation is done.

Added in version (cfdm): 1.12.0.0

Returns:

set The file names in normalised, absolute form. If the: data are in memory then an empty set is returned.

get_original_filenames()[source]¶

The names of files containing the original data and metadata.

The original files are those that contain some or all of the data and metadata when it was first instantiated, and are necessary (but perhaps not sufficient) to recreate the Index should the need arise. The cfdm.read function automatically records the original file names on all data that it creates.

The original files of any constituent components are also included.

In-place changes to the Index will not generally change the collection of original files. However if the Index was produced by combining other objects that also store their original file names, then the returned files will be the collection of original files from all contributing sources.

Added in version (cfdm): 1.10.0.1

Returns:

set: The original file names in normalised absolute form. If there are no original files then an empty set will be returned.

get_property(prop, default=ValueError())[source]¶

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.Index()
>>> 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_quantization(default=ValueError())[source]¶

Get quantization metadata.

Quantization eliminates false precision, usually by rounding the least significant bits of floating-point mantissas to zeros, so that a subsequent compression on disk is more efficient.

Index data can not be quantized, so the default is always returned.

Added in version (cfdm): 1.12.2.0

See also

get_quantize_on_write

Parameters:

default: optional

Return the value of the default keyword, because there is no quantization metadata.

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

Returns:

The default.

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

get_quantize_on_write(default=ValueError())[source]¶

Get a quantize-on-write instruction.

Quantization eliminates false precision, usually by rounding the least significant bits of floating-point mantissas to zeros, so that a subsequent compression on disk is more efficient.

Index data can not be quantized, so the default is always returned.

Added in version (cfdm): 1.12.2.0

See also

get_quantization

Parameters:

default: optional

Return the value of the default keyword, because there is no quantize-on-write instruction.

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

Returns:

The default.

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

has_bounds()[source]¶

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.Index()
>>> f.has_bounds()
False

has_data()[source]¶

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.Index()
>>> 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)[source]¶

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.Index()
>>> 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

identities(generator=False, **kwargs)[source]¶

Return all possible identities.

The identities comprise:

The standard_name property.
All properties, preceded by the property name and an equals e.g. 'long_name=Air temperature'.
The netCDF variable name, preceded by 'ncvar%'.

Added in version (cfdm): 1.7.0

See also

identity

Parameters:

generator: bool, optional: If True then return a generator for the identities, rather than a list.

Added in version (cfdm): 1.8.9.0
kwargs: optional: Additional configuration parameters that may be used by subclasses.

Added in version (cfdm): 1.8.9.0

Returns:

list or generator: The identities.

Examples

>>> f.properties()
{'foo': 'bar',
 'long_name': 'Air Temperature',
 'standard_name': 'air_temperature'}
>>> f.nc_get_variable()
'tas'
>>> f.identities()
['air_temperature',
 'long_name=Air Temperature',
 'foo=bar',
 'standard_name=air_temperature',
 'ncvar%tas']
>>> for i in f.identities(generator=True):
...     print(i)
...
air_temperature
long_name=Air Temperature
foo=bar
standard_name=air_temperature
ncvar%tas

identity(default='')[source]¶

Return the canonical identity.

By default the identity is the first found of the following:

The standard_name property.
The cf_role property, preceded by 'cf_role='.
The axis property, preceded by 'axis='.
The long_name property, preceded by 'long_name='.
The netCDF variable name, preceded by 'ncvar%'.
The value of the default parameter.

Added in version (cfdm): 1.7.0

See also

identities

Parameters:

default: optional: If no identity can be found then return the value of the default parameter.

Returns:

The identity.

Examples

>>> f = cfdm.Index()
>>> f.set_properties({'foo': 'bar',
...                   'long_name': 'Air Temperature',
...                   'standard_name': 'air_temperature'})
>>> f.nc_set_variable('tas')
>>> f.identity()
'air_temperature'
>>> f.del_property('standard_name')
'air_temperature'
>>> f.identity(default='no identity')
'air_temperature'
>>> f.identity()
'long_name=Air Temperature'
>>> f.del_property('long_name')
>>> f.identity()
'ncvar%tas'
>>> f.nc_del_variable()
'tas'
>>> f.identity()
'ncvar%tas'
>>> f.identity()
''
>>> f.identity(default='no identity')
'no identity'

insert_dimension(*args, **kwargs)[source]¶

Expand the shape of the data array.

Inserts a new size 1 axis into the data array.

Added in version (cfdm): 1.7.0

See also

squeeze, transpose

Parameters:

position: int, optional

Specify the position that the new axis will have in the data array. By default the new axis has position 0, the slowest varying position. Negative integers counting from the last position are allowed.

Parameter example:: position=2
Parameter example:: position=-1

inplace: bool, optional

If True then do the operation in-place and return None.

Returns:

Index or None: A new instance with expanded data axes. If the operation was in-place then None is returned.

Examples

>>> f.shape
(19, 73, 96)
>>> f.insert_dimension(position=3).shape
(19, 73, 96, 1)
>>> f.insert_dimension(position=-1).shape
(19, 73, 1, 96)

nc_clear_dataset_chunksizes()[source]¶

Clear the dataset chunking strategy for the data.

Added in version (cfdm): 1.12.2.0

See also

nc_dataset_chunksizes, nc_set_dataset_chunksizes, cfdm.read, cfdm.write

Returns:

None or str or int or tuple of int: The chunking strategy prior to being cleared, as would be returned by nc_dataset_chunksizes.

nc_clear_dimension_groups()[source]¶

Remove the netCDF dimension group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

An alternative technique for removing the group structure is to set the netCDF dimension name, with nc_set_dimension, with no / characters.

Added in version (cfdm): 1.8.6

See also

nc_dimension_groups, nc_set_dimension_groups

Returns:

tuple of str: The removed group structure.

Examples

>>> f.nc_set_dimension('time')
>>> f.nc_dimension_groups()
()
>>> f.nc_set_dimension_groups(['forecast', 'model'])
>>> f.nc_dimension_groups()
('forecast', 'model')
>>> f.nc_get_dimension()
'/forecast/model/time'
>>> f.nc_clear_dimension_groups()
('forecast', 'model')
>>> f.nc_get_dimension()
'time'

>>> f.nc_set_dimension('/forecast/model/time')
>>> f.nc_dimension_groups()
('forecast', 'model')
>>> f.nc_del_dimension('/forecast/model/time')
'/forecast/model/time'
>>> f.nc_dimension_groups()
()

nc_clear_hdf5_chunksizes()[source]¶

Clear the HDF5 chunking strategy for the data.

Deprecated at version 1.12.2.0 and is no longer available. Use nc_clear_dataset_chunksizes instead.

Added in version (cfdm): 1.12.0.0

nc_clear_sample_dimension_groups()[source]¶

Remove the netCDF sample dimension group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

An alternative technique for removing the group structure is to set the netCDF dimension name, with nc_set_sample_dimension, with no / characters.

Added in version (cfdm): 1.8.6

See also

nc_sample_dimension_groups, nc_set_sample_dimension_groups

Returns:

tuple of str: The removed group structure.

Examples

>>> f.nc_set_sample_dimension('element')
>>> f.nc_sample_dimension_groups()
()
>>> f.nc_set_sample_dimension_groups(['forecast', 'model'])
>>> f.nc_sample_dimension_groups()
('forecast', 'model')
>>> f.nc_get_sample_dimension()
'/forecast/model/element'
>>> f.nc_clear_sample_dimension_groups()
('forecast', 'model')
>>> f.nc_get_sample_dimension()
'element'

>>> f.nc_set_sample_dimension('/forecast/model/element')
>>> f.nc_sample_dimension_groups()
('forecast', 'model')
>>> f.nc_del_sample_dimension('/forecast/model/element')
'/forecast/model/element'
>>> f.nc_sample_dimension_groups()
()

nc_clear_variable_groups()[source]¶

Remove the netCDF variable group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

An alternative technique for removing the group structure is to set the netCDF variable name, with nc_set_variable, with no / characters.

Added in version (cfdm): 1.8.6

See also

nc_variable_groups, nc_set_variable_groups

Returns:

tuple of str: The removed group structure.

Examples

>>> f.nc_set_variable('time')
>>> f.nc_variable_groups()
()
>>> f.nc_set_variable_groups(['forecast', 'model'])
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'/forecast/model/time'
>>> f.nc_clear_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'time'

>>> f.nc_set_variable('/forecast/model/time')
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_del_variable('/forecast/model/time')
'/forecast/model/time'
>>> f.nc_variable_groups()
()

nc_dataset_chunksizes(todict=False)[source]¶

Get the dataset chunking strategy for the data.

Added in version (cfdm): 1.12.2.0

See also

nc_clear_dataset_chunksizes, nc_set_dataset_chunksizes, cfdm.read, cfdm.write

Parameters:

todict: bool, optional: If True then the dataset chunk sizes are returned in a dict keyed by their axis positions. If False (the default) then the dataset chunking strategy is returned in the same form that it was set (i.e. as None, int, str, or tuple).

Returns:

None or str or int or dict or tuple of int

The current chunking strategy when writing to a netCDF4 file. One of:

None: No dataset chunking strategy has been defined. The chunking strategy will be determined at write time by cfdm.write.
'contiguous': The data will be written to the file contiguously, i.e. no chunking.
int or str: The size in bytes of the dataset chunks. A string represents a quantity of byte units. “Square-like” chunk shapes are preferred, maximising the amount of chunks that are completely filled with data values (see the cfdm.write dataset_chunks parameter for details). For instance a chunksize of 1024 bytes may be specified with any of 1024, '1024', '1024 B', '1 KiB', '0.0009765625 MiB', etc. Recognised byte units are (case insensitive): B, KiB, MiB, GiB, TiB, PiB, KB, MB, GB, TB, and PB.
tuple of int: The maximum number of array elements in a chunk along each data axis. This chunking strategy may get automatically modified by methods that change the data shape (such as insert_dimension).
dict: If todict is True, the maximum number of array elements in a chunk along each axis. This chunking strategy may get automatically modified by methods that change the data shape (such as insert_dimension).

nc_del_dimension(default=ValueError())[source]¶

Remove the netCDF dimension name.

Added in version (cfdm): 1.7.0

See also

nc_get_dimension, nc_has_dimension, nc_set_dimension

Parameters:

default: optional: Return the value of the default parameter if the netCDF dimension name has not been set. If set to an Exception instance then it will be raised instead.

Returns:

str: The removed netCDF dimension name.

Examples

>>> f.nc_set_dimension('time')
>>> f.nc_has_dimension()
True
>>> f.nc_get_dimension()
'time'
>>> f.nc_del_dimension()
'time'
>>> f.nc_has_dimension()
False
>>> print(f.nc_get_dimension(None))
None
>>> print(f.nc_del_dimension(None))
None

nc_del_sample_dimension(default=ValueError())[source]¶

Remove the netCDF sample dimension name.

Added in version (cfdm): 1.7.0

See also

nc_get_sample_dimension, nc_has_sample_dimension, nc_set_sample_dimension

Parameters:

default: optional: Return the value of the default parameter if the netCDF sample dimension name has not been set. If set to an Exception instance then it will be raised instead.

Returns:

str: The removed netCDF sample dimension name.

Examples

>>> f.nc_set_sample_dimension('time')
>>> f.nc_has_sample_dimension()
True
>>> f.nc_get_sample_dimension()
'time'
>>> f.nc_del_sample_dimension()
'time'
>>> f.nc_has_sample_dimension()
False
>>> print(f.nc_get_sample_dimension(None))
None
>>> print(f.nc_del_sample_dimension(None))
None

nc_del_variable(default=ValueError())[source]¶

Remove the netCDF variable name.

Added in version (cfdm): 1.7.0

See also

nc_get_variable, nc_has_variable, nc_set_variable

Parameters:

default: optional: Return the value of the default parameter if the netCDF variable name has not been set. If set to an Exception instance then it will be raised instead.

Returns:

str: The removed netCDF variable name.

Examples

>>> f.nc_set_variable('tas')
>>> f.nc_has_variable()
True
>>> f.nc_get_variable()
'tas'
>>> f.nc_del_variable()
'tas'
>>> f.nc_has_variable()
False
>>> print(f.nc_get_variable(None))
None
>>> print(f.nc_del_variable(None))
None

nc_dimension_groups()[source]¶

Return the netCDF dimension group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

Added in version (cfdm): 1.8.6

See also

nc_clear_dimension_groups, nc_set_dimension_groups

Returns:

tuple of str: The group structure.

Examples

>>> f.nc_set_dimension('time')
>>> f.nc_dimension_groups()
()
>>> f.nc_set_dimension_groups(['forecast', 'model'])
>>> f.nc_dimension_groups()
('forecast', 'model')
>>> f.nc_get_dimension()
'/forecast/model/time'
>>> f.nc_clear_dimension_groups()
('forecast', 'model')
>>> f.nc_get_dimension()
'time'

>>> f.nc_set_dimension('/forecast/model/time')
>>> f.nc_dimension_groups()
('forecast', 'model')
>>> f.nc_del_dimension('/forecast/model/time')
'/forecast/model/time'
>>> f.nc_dimension_groups()
()

nc_get_dimension(default=ValueError())[source]¶

Return the netCDF dimension name.

Added in version (cfdm): 1.7.0

See also

nc_del_dimension, nc_has_dimension, nc_set_dimension

Parameters:

default: optional: Return the value of the default parameter if the netCDF dimension name has not been set. If set to an Exception instance then it will be raised instead.

Returns:

str: The netCDF dimension name.

Examples

>>> f.nc_set_dimension('time')
>>> f.nc_has_dimension()
True
>>> f.nc_get_dimension()
'time'
>>> f.nc_del_dimension()
'time'
>>> f.nc_has_dimension()
False
>>> print(f.nc_get_dimension(None))
None
>>> print(f.nc_del_dimension(None))
None

nc_get_sample_dimension(default=ValueError())[source]¶

Return the netCDF sample dimension name.

Added in version (cfdm): 1.7.0

See also

nc_del_sample_dimension, nc_has_sample_dimension, nc_set_sample_dimension

Parameters:

default: optional: Return the value of the default parameter if the netCDF sample dimension name has not been set. If set to an Exception instance then it will be raised instead.

Returns:

str: The netCDF sample dimension name.

Examples

>>> f.nc_set_sample_dimension('time')
>>> f.nc_has_sample_dimension()
True
>>> f.nc_get_sample_dimension()
'time'
>>> f.nc_del_sample_dimension()
'time'
>>> f.nc_has_sample_dimension()
False
>>> print(f.nc_get_sample_dimension(None))
None
>>> print(f.nc_del_sample_dimension(None))
None

nc_get_variable(default=ValueError())[source]¶

Return the netCDF variable name.

Added in version (cfdm): 1.7.0

See also

nc_del_variable, nc_has_variable, nc_set_variable

Parameters:

default: optional: Return the value of the default parameter if the netCDF variable name has not been set. If set to an Exception instance then it will be raised instead.

Returns:

str: The netCDF variable name. If unset then default is returned, if provided.

Examples

>>> f.nc_set_variable('tas')
>>> f.nc_has_variable()
True
>>> f.nc_get_variable()
'tas'
>>> f.nc_del_variable()
'tas'
>>> f.nc_has_variable()
False
>>> print(f.nc_get_variable(None))
None
>>> print(f.nc_del_variable(None))
None

nc_has_dimension()[source]¶

Whether the netCDF dimension name has been set.

Added in version (cfdm): 1.7.0

See also

nc_del_dimension, nc_get_dimension, nc_set_dimension

Returns:

bool: True if the netCDF dimension name has been set, otherwise False.

Examples

>>> f.nc_set_dimension('time')
>>> f.nc_has_dimension()
True
>>> f.nc_get_dimension()
'time'
>>> f.nc_del_dimension()
'time'
>>> f.nc_has_dimension()
False
>>> print(f.nc_get_dimension(None))
None
>>> print(f.nc_del_dimension(None))
None

nc_has_sample_dimension()[source]¶

Whether the netCDF sample dimension name has been set.

Added in version (cfdm): 1.7.0

See also

nc_del_sample_dimension, nc_get_sample_dimension, nc_set_sample_dimension

Returns:

bool: True if the netCDF sample dimension name has been set, otherwise False.

Examples

>>> f.nc_set_sample_dimension('time')
>>> f.nc_has_sample_dimension()
True
>>> f.nc_get_sample_dimension()
'time'
>>> f.nc_del_sample_dimension()
'time'
>>> f.nc_has_sample_dimension()
False
>>> print(f.nc_get_sample_dimension(None))
None
>>> print(f.nc_del_sample_dimension(None))
None

nc_has_variable()[source]¶

Whether the netCDF variable name has been set.

Added in version (cfdm): 1.7.0

See also

nc_del_variable, nc_get_variable, nc_set_variable

Returns:

bool: True if the netCDF variable name has been set, otherwise False.

Examples

>>> f.nc_set_variable('tas')
>>> f.nc_has_variable()
True
>>> f.nc_get_variable()
'tas'
>>> f.nc_del_variable()
'tas'
>>> f.nc_has_variable()
False
>>> print(f.nc_get_variable(None))
None
>>> print(f.nc_del_variable(None))
None

nc_hdf5_chunksizes(todict=False)[source]¶

Get the HDF5 chunking strategy for the data.

Deprecated at version 1.12.2.0 and is no longer available. Use nc_dataset_chunksizes instead.

Added in version (cfdm): 1.11.2.0

nc_sample_dimension_groups()[source]¶

Return the netCDF sample dimension group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

Added in version (cfdm): 1.8.6

See also

nc_clear_sample_dimension_groups, nc_set_sample_dimension_groups

Returns:

tuple of str: The group structure.

Examples

>>> f.nc_set_sample_dimension('element')
>>> f.nc_sample_dimension_groups()
()
>>> f.nc_set_sample_dimension_groups(['forecast', 'model'])
>>> f.nc_sample_dimension_groups()
('forecast', 'model')
>>> f.nc_get_sample_dimension()
'/forecast/model/element'
>>> f.nc_clear_sample_dimension_groups()
('forecast', 'model')
>>> f.nc_get_sample_dimension()
'element'

>>> f.nc_set_sample_dimension('/forecast/model/element')
>>> f.nc_sample_dimension_groups()
('forecast', 'model')
>>> f.nc_del_sample_dimension('/forecast/model/element')
'/forecast/model/element'
>>> f.nc_sample_dimension_groups()
()

nc_set_dataset_chunksizes(chunksizes)[source]¶

Set the dataset chunking strategy.

Added in version (cfdm): 1.12.2.0

See also

nc_dataset_chunksizes, nc_clear_dataset_chunksizes, cfdm.read, cfdm.write

Parameters:

chunksizes: None or str or int or float or dict or a sequence

Set the chunking strategy for writing to a netCDF4 file. One of:

None: No dataset chunking strategy has been defined. The chunking strategy will be determined at write time by cfdm.write.
'contiguous'

The data will be written to the file contiguously, i.e. no chunking.
int or float or str

The size in bytes of the dataset chunks. A floating point value is rounded down to the nearest integer, and a string represents a quantity of byte units. “Square-like” chunk shapes are preferred, maximising the amount of chunks that are completely filled with data values (see the cfdm.write dataset_chunks parameter for details). For instance a chunksize of 1024 bytes may be specified with any of 1024, 1024.9, '1024', '1024.9', '1024 B', '1 KiB', '0.0009765625 MiB', etc. Recognised byte units are (case insensitive): B, KiB, MiB, GiB, TiB, PiB, KB, MB, GB, TB, and PB. Spaces in strings are optional.
sequence of int or None

The maximum number of array elements in a chunk along each data axis, provided in the same order as the data axes. Values are automatically limited to the full size of their corresponding data axis, but the special values None or -1 may be used to indicate the full axis size. This chunking strategy may get automatically modified by methods that change the data shape (such as insert_dimension).
dict

The maximum number of array elements in a chunk along the axes specified by the dictionary keys. Integer values are automatically limited to the full size of their corresponding data axis, and the special values None or -1 may be used to indicate the full axis size. The chunk size for an unspecified axis defaults to an existing chunk size for that axis, if there is one, or else the axis size. This chunking strategy may get automatically modified by methods that change the data shape (such as insert_dimension).

Each dictionary key is an integer that specifies an axis by its position in the data array.

Returns:

None

nc_set_dimension(value)[source]¶

Set the netCDF dimension name.

If there are any / (slash) characters in the netCDF name then these act as delimiters for a group hierarchy. By default, or if the name starts with a / character and contains no others, the name is assumed to be in the root group.

Added in version (cfdm): 1.7.0

See also

nc_del_dimension, nc_get_dimension, nc_has_dimension

Parameters:

value: str: The value for the netCDF dimension name.

Returns:

None

Examples

>>> f.nc_set_dimension('time')
>>> f.nc_has_dimension()
True
>>> f.nc_get_dimension()
'time'
>>> f.nc_del_dimension()
'time'
>>> f.nc_has_dimension()
False
>>> print(f.nc_get_dimension(None))
None
>>> print(f.nc_del_dimension(None))
None

nc_set_dimension_groups(groups)[source]¶

Set the netCDF dimension group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

An alternative technique for setting the group structure is to set the netCDF dimension name, with nc_set_dimension, with the group structure delimited by / characters.

Added in version (cfdm): 1.8.6

See also

nc_clear_dimension_groups, nc_dimension_groups

Parameters:

groups: sequence of str: The new group structure.

Returns:

tuple of str: The group structure prior to being reset.

Examples

>>> f.nc_set_dimension('time')
>>> f.nc_dimension_groups()
()
>>> f.nc_set_dimension_groups(['forecast', 'model'])
>>> f.nc_dimension_groups()
('forecast', 'model')
>>> f.nc_get_dimension()
'/forecast/model/time'
>>> f.nc_clear_dimension_groups()
('forecast', 'model')
>>> f.nc_get_dimension()
'time'

>>> f.nc_set_dimension('/forecast/model/time')
>>> f.nc_dimension_groups()
('forecast', 'model')
>>> f.nc_del_dimension('/forecast/model/time')
'/forecast/model/time'
>>> f.nc_dimension_groups()
()

nc_set_hdf5_chunksizes(chunksizes)[source]¶

Set the HDF5 chunking strategy.

Deprecated at version 1.12.2.0 and is no longer available. Use nc_set_dataset_chunksizes instead.

Added in version (cfdm): 1.11.2.0

nc_set_sample_dimension(value)[source]¶

Set the netCDF sample dimension name.

If there are any / (slash) characters in the netCDF name then these act as delimiters for a group hierarchy. By default, or if the name starts with a / character and contains no others, the name is assumed to be in the root group.

Added in version (cfdm): 1.7.0

See also

nc_del_sample_dimension, nc_get_sample_dimension, nc_has_sample_dimension

Parameters:

value: str: The value for the netCDF sample dimension name.

Returns:

None

Examples

>>> f.nc_set_sample_dimension('time')
>>> f.nc_has_sample_dimension()
True
>>> f.nc_get_sample_dimension()
'time'
>>> f.nc_del_sample_dimension()
'time'
>>> f.nc_has_sample_dimension()
False
>>> print(f.nc_get_sample_dimension(None))
None
>>> print(f.nc_del_sample_dimension(None))
None

nc_set_sample_dimension_groups(groups)[source]¶

Set the netCDF sample dimension group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

An alternative technique for setting the group structure is to set the netCDF dimension name, with nc_set_sample_dimension, with the group structure delimited by / characters.

Added in version (cfdm): 1.8.6

See also

nc_clear_sample_dimension_groups, nc_sample_dimension_groups

Parameters:

groups: sequence of str: The new group structure.

Returns:

tuple of str: The group structure prior to being reset.

Examples

>>> f.nc_set_sample_dimension('element')
>>> f.nc_sample_dimension_groups()
()
>>> f.nc_set_sample_dimension_groups(['forecast', 'model'])
>>> f.nc_sample_dimension_groups()
('forecast', 'model')
>>> f.nc_get_sample_dimension()
'/forecast/model/element'
>>> f.nc_clear_sample_dimension_groups()
('forecast', 'model')
>>> f.nc_get_sample_dimension()
'element'

>>> f.nc_set_sample_dimension('/forecast/model/element')
>>> f.nc_sample_dimension_groups()
('forecast', 'model')
>>> f.nc_del_sample_dimension('/forecast/model/element')
'/forecast/model/element'
>>> f.nc_sample_dimension_groups()
()

nc_set_variable(value)[source]¶

Set the netCDF variable name.

If there are any / (slash) characters in the netCDF name then these act as delimiters for a group hierarchy. By default, or if the name starts with a / character and contains no others, the name is assumed to be in the root group.

Added in version (cfdm): 1.7.0

See also

nc_del_variable, nc_get_variable, nc_has_variable

Parameters:

value: str: The value for the netCDF variable name.

Returns:

None

Examples

>>> f.nc_set_variable('tas')
>>> f.nc_has_variable()
True
>>> f.nc_get_variable()
'tas'
>>> f.nc_del_variable()
'tas'
>>> f.nc_has_variable()
False
>>> print(f.nc_get_variable(None))
None
>>> print(f.nc_del_variable(None))
None

nc_set_variable_groups(groups)[source]¶

Set the netCDF variable group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

An alternative technique for setting the group structure is to set the netCDF variable name, with nc_set_variable, with the group structure delimited by / characters.

Added in version (cfdm): 1.8.6

See also

nc_clear_variable_groups, nc_variable_groups

Parameters:

groups: sequence of str: The new group structure.

Returns:

tuple of str: The group structure prior to being reset.

Examples

>>> f.nc_set_variable('time')
>>> f.nc_variable_groups()
()
>>> f.nc_set_variable_groups(['forecast', 'model'])
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'/forecast/model/time'
>>> f.nc_clear_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'time'

>>> f.nc_set_variable('/forecast/model/time')
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_del_variable('/forecast/model/time')
'/forecast/model/time'
>>> f.nc_variable_groups()
()

nc_variable_groups()[source]¶

Return the netCDF variable group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

Added in version (cfdm): 1.8.6

See also

nc_clear_variable_groups, nc_set_variable_groups

Returns:

tuple of str: The group structure.

Examples

>>> f.nc_set_variable('time')
>>> f.nc_variable_groups()
()
>>> f.nc_set_variable_groups(['forecast', 'model'])
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'/forecast/model/time'
>>> f.nc_clear_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'time'

>>> f.nc_set_variable('/forecast/model/time')
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_del_variable('/forecast/model/time')
'/forecast/model/time'
>>> f.nc_variable_groups()
()

persist(*args, **kwargs)[source]¶

Persist data into memory.

Persisting turns an underlying lazy dask array into an equivalent chunked dask array, but now with the results fully computed and in memory. This can avoid the expense of re-reading the data from disk, or re-computing it, when the data is accessed on multiple occasions.

Performance

persist causes delayed operations to be computed.

Added in version (cfdm): 1.12.0.0

See also

array, datetime_array, cfdm.Data.persist

Parameters:

inplace: bool, optional: If True then do the operation in-place and return None.

Returns:

Index or None: The construct with persisted data. If the operation was in-place then None is returned.

properties()[source]¶

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.Index()
>>> 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()
{}

replace_directory(old=None, new=None, normalise=False, common=False)[source]¶

Replace a file directory in-place.

Added in version (cfdm): 1.12.0.0

See also

file_directories, get_filenames

Parameters:

old: str or None, optional: The base directory structure to be replaced by new. If None (the default) or an empty string, and normalise is False, then new (if set) is prepended to each file name.
new: str or None, optional: The new directory that replaces the base directory structure identified by old. If None (the default) or an empty string, then old (if set) is replaced with an empty string.
normalise: bool, optional: If True then old and new directories, and the file names, are normalised to absolute paths prior to the replacement. If False (the default) then no normalisation is done.
common: bool, optional: If True the base directory structure that is common to all files with new.

Returns:

None

set_data(data, copy=True, inplace=True)[source]¶

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 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 Index instance is returned.

Added in version (cfdm): 1.8.7.0

Returns:

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

Examples

>>> f = cfdm.Index()
>>> 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)[source]¶

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.Index()
>>> 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)[source]¶

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.Index()
>>> 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

squeeze(*args, **kwargs)[source]¶

Remove size one axes from the data array.

By default all size one axes are removed, but particular size one axes may be selected for removal.

Added in version (cfdm): 1.7.0

See also

insert_dimension, transpose

Parameters:

axes: (sequence of) int, optional

The positions of the size one axes to be removed. By default all size one axes are removed.

Each axis is identified by its integer position in the data. Negative integers counting from the last position are allowed.

Parameter example:: axes=0
Parameter example:: axes=-1
Parameter example:: axes=[1, -2]

inplace: bool, optional

If True then do the operation in-place and return None.

Returns:

Index or None: A new instance with removed size 1 one data axes. If the operation was in-place then None is returned.

Examples

>>> f = cfdm.Index()
>>> d = cfdm.Data(numpy.arange(7008).reshape((1, 73, 1, 96)))
>>> f.set_data(d)
>>> f.shape
(1, 73, 1, 96)
>>> f.squeeze().shape
(73, 96)
>>> f.squeeze(0).shape
(73, 1, 96)
>>> f.squeeze([-3, 2]).shape
(73, 96)

to_memory(*args, **kwargs)[source]¶

Bring data on disk into memory.

There is no change to data that is already in memory.

Parameters:

inplace: bool, optional: If True then do the operation in-place and return None.

Returns:

Index or None: A copy with the data in memory, or None if the operation was in-place.

transpose(*args, **kwargs)[source]¶

Permute the axes of the data array.

Added in version (cfdm): 1.7.0

See also

insert_dimension, squeeze

Parameters:

axes: (sequence of) int, optional

The new axis order. By default the order is reversed.

Each axis is identified by its integer position in the data. Negative integers counting from the last position are allowed.

Parameter example:: axes=0
Parameter example:: axes=-1
Parameter example:: axes=[1, -2]

inplace: bool, optional

If True then do the operation in-place and return None.

Returns:

Index or None: A new instance with permuted data axes. If the operation was in-place then None is returned.

Examples

>>> f.shape
(19, 73, 96)
>>> f.transpose().shape
(96, 73, 19)
>>> f.transpose([1, 0, 2]).shape
(73, 19, 96)

uncompress(*args, **kwargs)[source]¶

Uncompress the construct.

Whether or not the construct is compressed does not alter its functionality nor external appearance.

A construct that is already uncompressed will be returned uncompressed.

The following type of compression are available:

Ragged arrays for discrete sampling geometries (DSG). Three different types of ragged array representation are supported.

Compression by gathering.

Compression by coordinate subsampling

Added in version (cfdm): 1.7.11

Parameters:

inplace: bool, optional: If True then do the operation in-place and return None.

Returns:

Index or None: The uncompressed construct, or None if the operation was in-place.

Examples

>>> f.data.get_compression_type()
'ragged contiguous'
>>> g = f.uncompress()
>>> g.data.get_compression_type()
''
>>> g.equals(f)
True

property array¶

A numpy array deep copy of the data.

Changing the returned numpy array does not change the data array.

Added in version (cfdm): 1.10.0.0

See also

data, datetime_array

Examples

>>> f.data
<Data(5): [0, ... 4] kg m-1 s-2>
>>> a = f.array
>>> type(a)
<type 'numpy.ndarray'>
>>> 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
<Data(5): [0, ... 4] kg m-1 s-2>

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.Data.array, del_data, get_data, has_data, set_data

Returns:

Data: The data.

Examples

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

property datetime_array¶

An independent numpy array of date-time objects.

Only applicable for data 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.

Added in version (cfdm): 1.10.0.0

See also

array, data

Examples

>>> f.units
'days since 2000-01-01'
>>> print(f.array)
[ 0 31 60 91]
>>> print(f.datetime_array)
[cftime.DatetimeGregorian(2000-01-01 00:00:00)
 cftime.DatetimeGregorian(2000-02-01 00:00:00)
 cftime.DatetimeGregorian(2000-03-01 00:00:00)
 cftime.DatetimeGregorian(2000-04-01 00:00:00)]

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

cfdm 1.12.3.0

Related Topics

cfdm.index¶