cf.VariableList

class cf.VariableList(sequence=())

Bases: cf.utils.CfList

An ordered sequence of variables stored in a list-like object.

In some contexts, whether an object is a variable or a variable list is not known and does not matter. So to avoid ungainly type testing, some aspects of the VariableList interface are shared by a variable and vice versa.

Any attribute or method belonging to a variable may be used on a variable list and will be applied independently to each element.

Just as it is straight forward to iterate over the variables in a variable list, a variable will behave like a single element variable list in iterative and indexing contexts.

Initialization

Parameters :

sequence : iterable, optional

Define a new list with these elements.

VariableList methods (undocumented methods behave exactly as their counterparts in a built-in list)

append
copy	Return a deep copy.
count	Return the number of occurrences of a given value.
delprop	Delete a CF property from each element of the list.
dump	Return a string containing the full descriptions of each variable in
equals	True if two instances are equal, False otherwise.
extend
getprop	Return a built-in list of a CF properties from each element.
hasprop	Return a built-in list describing whether each element has a CF
index	Return the first index of a given value.
insert	Insert an object before the given index in place.
match	Return a list of booleans showing which elements match the given conditions.
name	Return a built-in list of the names of each element of the list of
override_units	Override the each element’s data array units in place.
pop
remove
reverse
set_equals	True if two instances are set-wise equal, False otherwise.
setprop	Set a CF property on each element of the list.
sort	Sort the elements in place.
subset	Return the elements which match the given conditions.
subspace	Subspace each variable in the list, returning a new list of variables.

copy()

Return a deep copy.

Equivalent to copy.deepcopy(s).

Returns :

out :

The deep copy.

Examples

>>> s.copy()

count(value)

Return the number of occurrences of a given value.

Uses numerically tolerant equality where appropriate.

Parameters :

value :

The value to count.

Returns :

out : int

The number of occurrences of value.

Examples

>>> s
[1, 2, 3, 2, 4, 2]
>>> s.count(1)
1
>>> s.count(2)
3

delprop(prop)

Delete a CF property from each element of the list.

Parameters :

prop : str

The name of the property to delete.

Returns :

None

Examples

>>> len(fl)
2
>>> fl.getprop('foo')
['bar', 'bar']
>>> fl.delprop('foo')
>>> fl.getprop('foo', 5)
[5, 5]

Note that recognised CF propeties (such as ‘long_name’) may be deleted directly:

>>> del fl.standard_name
>>> getattr(fl, 'standard_name', None)
[None, None]

dump(*arg, **kwargs)

Return a string containing the full descriptions of each variable in the list.

equals(other, rtol=None, atol=None, traceback=False)

True if two instances are equal, False otherwise.

Two instances are equal if their attributes are equal and their elements are equal pair-wise.

Parameters :

other :

The object to compare for equality.

atol : float, optional

The absolute tolerance for all numerical comparisons, By default the value returned by the ATOL function is used.

rtol : float, optional

The relative tolerance for all numerical comparisons, By default the value returned by the RTOL function is used.

traceback : bool, optional

If True then print a traceback highlighting where the two instances differ.

Returns :

out : bool

Whether or not the two instances are equal.

getprop(prop, *default)

Return a built-in list of a CF properties from each element.

Parameters :

prop : str

The name of the property to get.

default : optional

Return default for each element that does not have the named property.

Returns :

out : list

The value of the named property, or the default value, for each element.

Raises :

AttributeError :

If any element does not have the named property and a default value has not been set.

Examples

>>> len(fl)
2
>>> fl.getprop('foo')
['bar', 'bar']
>>> fl.delprop('foo')
>>> fl.getprop('foo', 0.0)
[0.0, 0.0]

Note that recognised CF propeties (such as ‘long_name’) may be retrieved directly:

>>> fl.standard_name
['air_temperature', 'air_temperature']
>>> getattr(fl, 'long_name', 'default')
['default', 'default']

hasprop(prop)

Return a built-in list describing whether each element has a CF property.

Parameters :

prop : str

The name of the property to get.

Returns :

out : list or bools

Whether each element has the named property.

Examples

>>> len(fl)
2
>>> fl.hasprop('foo')
[False, True]

Warning: Recognised CF propeties (such as ‘long_name’) may be interrogated with the built-in hasattr, but with a different result:

>>> getattr(fl, 'standard_name', None)
['air_tmperature', None]
>>> hasattr(fl, 'standard_name')
True
>>> fl.hasprop('standard_name')
[True, False]

index(value, start=0, stop=None)

Return the first index of a given value.

Uses numerically tolerant equality where appropriate.

Parameters :

value :

The value to look for in the list.

start : int, optional

Start looking from this index. By default, look from the beginning of the list.

stop : int, optional

Stop looking before this index. By default, look up to the end of the list.

Returns :

out : int

Raises :

ValueError :

If the given value is not in the list.

Examples

>>> s
[1, 2, 3, 2, 4, 2]
>>> s.index(1)
1
>>> s.index(2, 2)
3
>>> s.index(2, start=2, stop=5)
3
>>> s.index(6)
ValueError: CfList doesn't contain: 6

insert(index, item)

Insert an object before the given index in place.

Parameters :

index : int

item :

Returns :

None

Examples

>>> s
[1, 2, 3]
>>> s.insert(1, 'A')
>>> s
[1, 'A', 2, 3]
>>> s.insert(100, 'B')
[1, 'A', 2, 3, 'B']
>>> s.insert(100, 'B')
[1, 'A', 2, 3, 'B']
>>> s.insert(-2, 'C')
[1, 'A', 2, 'C', 3, 'B']
>>> s.insert(-100, 'D')
['D', 1, 'A', 2, 'C', 3, 'B']

match(*args, **kwargs)

Return a list of booleans showing which elements match the given conditions.

The match conditions are passed to each element’s match method in turn.

Parameters :

args, kwargs :

As for the variable’s match method.

Returns :

out : list

A built-in list of booleans showing which elements match the conditions.

Examples

>>> fl
[<>
 <>]
>>> fl.match(attr={'standard_name': 'air_temperature'})
[True, False]

name(*arg, **kwargs)

Return a built-in list of the names of each element of the list of variables.

override_units(*args, **kwargs)

Override the each element’s data array units in place.

Not to be confused with setting the Units attribute to units which are equivalent to each element’s original units.

This is different to setting the Units attribute, as the new units need not be equivalent to the original ones and the each data array will not be changed to reflect the new units.

set_equals(other, rtol=None, atol=None, traceback=False)

True if two instances are set-wise equal, False otherwise.

Two instances are set-wise equal if their attributes are equal and their elements are equal set-wise (i.e. the order of the lists is irrelevant).

Parameters :

other :

The object to compare for equality.

atol : float, optional

The absolute tolerance for all numerical comparisons, By default the value returned by the ATOL function is used.

rtol : float, optional

The relative tolerance for all numerical comparisons, By default the value returned by the RTOL function is used.

traceback : bool, optional

If True then print a traceback highlighting where the two instances differ.

Returns :

out : bool

Whether or not the two instances are equal.

Examples

setprop(prop, value)

Set a CF property on each element of the list.

Parameters :

prop : str

The name of the property to set.

value :

The value for the property.

Returns :

None

Examples

>>> len(fl)
2
>>> fl.setprop('foo', 'bar')
>>> fl.getprop('foo')
['bar', 'bar']

Note that recognised CF propeties (such as ‘long_name’) may be set directly:

>>> fl.standard_name = 'air_temperature'
>>> fl.standard_name
['air_temperature', 'air_temperature']

sort(*args, **kwargs)

Sort the elements in place.

The sort is stable which means that when multiple records have the same key, their original order is preserved.

Parameters :

args, kwargs :

As for the built-in list’s sort method.

Returns :

None

Examples

Two ways of sorting by standard name:

>>> fl.sort(key=lambda f: f.standard_name)
>>> from operator import attrgetter
>>> fl.sort(key=attrgetter('standard_name'))

Get the elements in reverse standard name order:

>>> fl.sort(key=attrgetter('standard_name'), reverse=True)

Sort by standard name then by the value of the first element of the data array:

>>> fl.sort(key=attrgetter('standard_name', 'first_datum'))

Sort by standard name then by the value of the second element of the data array:

>>> fl.sort(key=lambda f: (f.standard_name, f.subspace[..., 1].first_datum))

subset(*args, **kwargs)

Return the elements which match the given conditions.

The match conditions are passed to each element’s match method in turn.

Parameters :

args, kwargs :

As for the variable’s match method.

Returns :

out :

A new list containing the matching elements.

Examples

>>> fl
[<>
 <>]
>>> fl.subset(attr={'standard_name': 'air_temperature'})
[<>]

subspace

Subspace each variable in the list, returning a new list of variables.

Examples

>>> vl
[<CF Variable: air_temperature(73, 96)>,
 <CF Variable: air_temperature(73, 96)>]
>>> vl.subspace[0,0]
[<CF Variable: air_temperature(1,1)>,
 <CF Variable: air_temperature(1,1)>]