cf.FieldList

class cf.FieldList(sequence=())

Bases: cf.variablelist.VariableList

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

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

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

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

Initialization

Parameters :

sequence : iterable, optional

Define a new list with these elements.

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

append
coord	Apply the coord method to each element of the list.
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.
squeeze	Apply the squeeze method to each element of the list.
subset	Return the elements which match the given conditions.
subspace	Slice each field in the list, returning a new list of fields.
unsqueeze	Apply the unsqueeze method to each element of the list.

coord(*args, **kwargs)

Apply the coord method to each element of the list.

Note that a coordinate list is returned (as opposed to a field list).

Parameters :

args, kwargs :

As for a field’s coord method.

Returns :

out : CoordinateList

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))

squeeze(*args, **kwargs)

Apply the squeeze method to each element of the list.

Parameters :

args, kwargs :

As for a field’s squeeze method.

Returns :

out : FieldList

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'})
[<>]

unsqueeze(*args, **kwargs)

Apply the unsqueeze method to each element of the list.

Parameters :

args, kwargs :

As for a field’s unsqueeze method.

Returns :

out : FieldList

subspace

Slice each field in the list, returning a new list of fields. Slicing by indices or by coordinate values are both allowed.

Examples

>>> fl
[<CF Variable: air_temperature(73, 96)>,
 <CF Variable: air_temperature(73, 96)>]
>>> fl.subspace[0,0]
[<CF Variable: air_temperature(1,1)>,
 <CF Variable: air_temperature(1,1)>]
>>> fl.slice(longitude=0, latitude=0)
[<CF Variable: air_temperature(1,1)>,
 <CF Variable: air_temperature(1,1)>]