cf.CoordinateReference

class cf.CoordinateReference(name=None, crtype=None, coords=None, coord_terms=None, **kwargs)

Bases: cf.utils.Dict

A CF coordinate reference construct.

A coordinate reference construct relates the field’s coordinate values to locations in a planetary reference frame.

The coordinate reference object is associated with a coordinate system and contains links to the dimension or auxiliary coordinate constructs to which it applies; and any additional terms, such as parameter values and field objects which define a datum and coordinate conversion, i.e. a formula for converting coordinate values taken from the dimension or auxiliary coordinate objects to a different coordinate system.

Accessing terms

The coordinate reference object behaves like a dictionary when it comes to accessing its terms and their values: For example:

>>> c = cf.CoordinateReference('azimuthal_equidistant', 
...                             longitude_of_projection_origin=80.5,
...                             latitude_of_projection_origin=5, 
...                             false_easting=cf.Data(-200, 'km'),
...                             false_northing=cf.Data(-100, 'km'))
>>> c.keys()
['false_easting',
 'latitude_of_projection_origin',
 'false_northing',
 'longitude_of_projection_origin']
>>> c.items()
[('false_easting', <CF Data: -200 km>),
 ('latitude_of_projection_origin', 5),
 ('false_northing', <CF Data: -100 km>),
 ('longitude_of_projection_origin', 80.5)]
>>> c['latitude_of_projection_origin']
5
>>> c['latitude_of_projection_origin'] = -75.25
>>> c['latitude_of_projection_origin']
-75.25

Attributes

Attribute	Description
!name	The identity of the coordinate reference.
!type	The CF type of the coordinate reference.
!coords	The identities of the dimension and auxiliary coordinate objects of the which apply to this coordinate reference.
!coord_terms	The terms of the coordinate conversion which refer to dimension or auxiliary coordinate objects.

Initialization

Parameters:

name : str, optional

A name which describes the nature of the coordinate conversion. This is usually a CF grid_mapping name or the standard name of a CF dimensionless vertical coordinate, but is not restricted to these.

Example: To create a polar stereographic coordinate reference: name='polar_stereographic'. To create coordinate reference for an ocean sigma over z coordinate: name='ocean_sigma_z_coordinate'. To create new type of coordinate reference: name='my_new_type'.

crtype : str, optional

The CF type of the coordinate reference. This is either 'grid_mapping' or 'formula_terms'. By default the type is inferred from the name, if possible. For example:

>>> c = cf.CoordinateReference('transverse_mercator')
>>> c.type
'grid_mapping'

>>> c = cf.CoordinateReference('my_new_type', crtype='formula_terms')
>>> c.type
'formula_terms'

>>> c = cf.CoordinateReference('my_new_type')
>>> print c.type
None

>>> c = cf.CoordinateReference('my_new_type', crtype='grid_mapping')
>>> print c.type
'grid_mapping'

coords : sequence of str, optional

Identify the dimension and auxiliary coordinate objects which apply to this coordinate reference. By default the standard names of those expected by the CF conventions are used. For example:

>>> c = cf.CoordinateReference('transverse_mercator')
>>> c.coords
{'latitude', 'longitude', 'projection_x_coordinate', 'projection_y_coordinate'}

>>> c = cf.CoordinateReference('transverse_mercator', coords=['ncvar:lat'])
>>> c.coords
{'ncvar:lat'}

coord_terms : sequence of str, optional

The terms of the coordinate conversion which refer to dimension or auxiliary coordinate objects. For example:

>>> c = cf.CoordinateReference('lambert_conformal_conic')
>>> c.coord_terms
set()

>>> c = cf.CoordinateReference('atmosphere_hybrid_height_coordinate',
...                            coord_terms=['a', 'b'])
>>> c.coord_terms
{'a', 'b'}

kwargs : optional

The terms of the coordinate conversion and their values. A term’s values may be one of the following:

• A number or size one numeric array.
• A string containing a coordinate object’s identity.
• A Field.
• None, indicating that the term exists but is unset.

For example:

>>> c = cf.CoordinateReference('orthographic', 
...                            grid_north_pole_latitude=70,
...                            grid_north_pole_longitude=cf.Data(120, 'degreesE'))
>>> c['grid_north_pole_longitude']
<CF Data: 120 degreesE>

>>> orog_field
<CF Field: surface_altitude(latitude(73), longitude(96)) m>
>>> c = cf.CoordinateReference('atmosphere_hybrid_height_coordinate',
...                            a='long_name:ak',
...                            b='long_name:bk',
...                            orog=orog_field)

__init__(name=None, crtype=None, coords=None, coord_terms=None, **kwargs)

Initialization

Parameters:

name : str, optional

A name which describes the nature of the coordinate conversion. This is usually a CF grid_mapping name or the standard name of a CF dimensionless vertical coordinate, but is not restricted to these.

Example: To create a polar stereographic coordinate reference: name='polar_stereographic'. To create coordinate reference for an ocean sigma over z coordinate: name='ocean_sigma_z_coordinate'. To create new type of coordinate reference: name='my_new_type'.

crtype : str, optional

The CF type of the coordinate reference. This is either 'grid_mapping' or 'formula_terms'. By default the type is inferred from the name, if possible. For example:

>>> c = cf.CoordinateReference('transverse_mercator')
>>> c.type
'grid_mapping'

>>> c = cf.CoordinateReference('my_new_type', crtype='formula_terms')
>>> c.type
'formula_terms'

>>> c = cf.CoordinateReference('my_new_type')
>>> print c.type
None

>>> c = cf.CoordinateReference('my_new_type', crtype='grid_mapping')
>>> print c.type
'grid_mapping'

coords : sequence of str, optional

Identify the dimension and auxiliary coordinate objects which apply to this coordinate reference. By default the standard names of those expected by the CF conventions are used. For example:

>>> c = cf.CoordinateReference('transverse_mercator')
>>> c.coords
{'latitude', 'longitude', 'projection_x_coordinate', 'projection_y_coordinate'}

>>> c = cf.CoordinateReference('transverse_mercator', coords=['ncvar:lat'])
>>> c.coords
{'ncvar:lat'}

coord_terms : sequence of str, optional

The terms of the coordinate conversion which refer to dimension or auxiliary coordinate objects. For example:

>>> c = cf.CoordinateReference('lambert_conformal_conic')
>>> c.coord_terms
set()

>>> c = cf.CoordinateReference('atmosphere_hybrid_height_coordinate',
...                            coord_terms=['a', 'b'])
>>> c.coord_terms
{'a', 'b'}

kwargs : optional

The terms of the coordinate conversion and their values. A term’s values may be one of the following:

• A number or size one numeric array.
• A string containing a coordinate object’s identity.
• A Field.
• None, indicating that the term exists but is unset.

For example:

>>> c = cf.CoordinateReference('orthographic', 
...                            grid_north_pole_latitude=70,
...                            grid_north_pole_longitude=cf.Data(120, 'degreesE'))
>>> c['grid_north_pole_longitude']
<CF Data: 120 degreesE>

>>> orog_field
<CF Field: surface_altitude(latitude(73), longitude(96)) m>
>>> c = cf.CoordinateReference('atmosphere_hybrid_height_coordinate',
...                            a='long_name:ak',
...                            b='long_name:bk',
...                            orog=orog_field)

Methods

__init__([name, crtype, coords, coord_terms])	Initialization
canonical_units(term)	Return the canonical units for a standard CF coordinate conversion term.
change_coord_identities(coord_map[, i])	Change the idientifier of all coordinates.
clear(() -> None.  Remove all items from D.)
close()	Close all files referenced by coordinate conversion term values.
copy([domain])	Return a deep copy.
default_value(term)	Return the default value for an unset standard CF coordinate conversion term.
dump([complete, display, _level, domain])	Return a string containing a full description of the coordinate reference.
equals(other[, rtol, atol, ...])	True if two instances are equal, False otherwise.
equivalent(other[, atol, rtol, traceback])	True if two coordinate references are logically equal, False otherwise.
get((k[,d]) -> D[k] if k in D, ...)
has_key(key)
identity([default])	Return the identity of the coordinate reference.
inspect()	Inspect the attributes.
items(() -> list of D’s (key, value) pairs, ...)
iteritems(() -> an iterator over the (key, ...)
iterkeys(() -> an iterator over the keys of D)
itervalues(...)
keys(() -> list of D’s keys)
match([match, exact, match_all, inverse])	Test whether or not the coordinate reference satisfies the given conditions.
pop((k[,d]) -> v, ...)	If key is not found, d is returned if given, otherwise KeyError is raised.
popitem(() -> (k, v), ...)	as a 2-tuple; but raise KeyError if D is empty.
remove_all_coords()	Remove all links to coordinate objects.
set(term, value)
setcoord(term, value)
setdefault((k[,d]) -> D.get(k,d), ...)
structural_signature([rtol, atol])
update(([E, ...)	If E present and has a .keys() method, does: for k in E: D[k] = E[k]
values(() -> list of D’s values)

Attributes

T	False.
X	Returns False.
Y	Returns False.
Z	Returns False.
hasbounds	False

classmethod canonical_units(term)

Return the canonical units for a standard CF coordinate conversion term.

Parameters:

term : str

The name of the term.

Returns:

out : cf.Units or None

The canonical units, or None if there are not any.

Examples:

>>> cf.CoordinateReference.canonical_units('perspective_point_height')
<CF Units: m>
>>> cf.CoordinateReference.canonical_units('ptop')
None

change_coord_identities(coord_map, i=False)

Change the idientifier of all coordinates.

If a coordinate identifier is not in the provided mapping then it is set to None and thus effectively removed from the coordinate reference.

Parameters:

coord_map : dict

For example: {'dim2': 'dim3', 'aux2': 'latitude', 'aux4': None}

i : bool, optional

Returns:

None

Examples:

>>> r = cf.CoordinateReference('atmosphere_hybrid_height_coordinate',
...                             coord_terms=['a', 'b'],
...                             a='ncvar:ak',
...                             b='ncvar:bk')
>>> r.coords
{'atmosphere_hybrid_height_coordinate', 'ncvar:ak', 'ncvar:bk'}
>>> r.change_coord_identitiers({'atmosphere_hybrid_height_coordinate', 'dim1',
...                             'ncvar:ak': 'aux0'})
>>> r.coords
{'dim1', 'aux0'}

clear() → None. Remove all items from D.

close()

Close all files referenced by coordinate conversion term values.

Returns:None Examples:

>>> c.close()

copy(domain=None)

Return a deep copy.

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

Examples 1:

>>> d = c.copy()

Parameters:

domain : cf.Domain, optional

Returns:

out :

The deep copy.

Examples 2:

>>> domain
<CF Domain: (110, 106, 3, 5)>
>>> d = c.copy(domain=domain)

classmethod default_value(term)

Return the default value for an unset standard CF coordinate conversion term.

The default values are stored in the file cf/etc/coordinate_reference/default_values.txt.

Parameters:

term : str

The name of the term.

Returns:

out :

The default value, or None if there is not one.

Examples:

>>> cf.CoordinateReference.default_value('ptop')
0.0
>>> print cf.CoordinateReference.default_value('north_pole_grid_latitude')
None

dump(complete=False, display=True, _level=0, domain=None)

Return a string containing a full description of the coordinate reference.

Parameters:

complete : bool, optional

display : bool, optional

If False then return the description as a string. By default the description is printed, i.e. c.dump() is equivalent to print c.dump(display=False).

domain : cf.Domain, optional

Returns:

out : str

A string containing the description.

Examples:

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

True if two instances are equal, False otherwise.

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.

ignore_fill_value : bool, optional

If True then data arrays with different fill values are considered equal. By default they are considered unequal.

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:

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

True if two coordinate references are logically equal, False otherwise.

Parameters:

other : cf.CoordinateReference

The object to compare for equality.

atol : float, optional

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

rtol : float, optional

The relative tolerance for all numerical comparisons, By default the value returned by the cf.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 objects are equivalent.

Examples:

>>>

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

has_key(key)

identity(default=None)

Return the identity of the coordinate reference.

The identity is the standard_name of a formula_terms-type coordinate reference or the grid_mapping_name of grid_mapping-type coordinate reference.

Parameters:

default : optional

If the coordinate reference has no identity then return default. By default, default is None.

Returns:

out :

The identity.

Examples:

>>> c.identity()
'rotated_latitude_longitude'
>>> c.identity()
'atmosphere_hybrid_height_coordinate'

inspect()

Inspect the attributes.

See also

cf.inspect

Returns:None

items() → list of D's (key, value) pairs, as 2-tuples

iteritems() → an iterator over the (key, value) items of D

iterkeys() → an iterator over the keys of D

itervalues() → an iterator over the values of D

keys() → list of D's keys

match(match=None, exact=False, match_all=True, inverse=False)

Test whether or not the coordinate reference satisfies the given conditions.

Returns:

out : bool

True if the coordinate reference satisfies the given criteria, False otherwise.

Examples:

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

remove_all_coords()

Remove all links to coordinate objects.

All terms linked to coordinate objects are set to None.

Returns:None Examples:

>>> c.remove_all_coords()

set(term, value)

setcoord(term, value)

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

structural_signature(rtol=None, atol=None)

update([E, ]**F) → None. Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → list of D's values

T

False.

Provides compatibility with the cf.Coordinate API.

See also

cf.Coordinate.T, X, ~cf.CoordinateReference.Y, Z

Examples:

>>> c.T
False

X

Returns False.

Provides compatibility with the cf.Coordinate API.

See also

cf.Coordinate.X, T, ~cf.CoordinateReference.Y, Z

Examples:

>>> c.X
False

Y

Returns False.

Provides compatibility with the cf.Coordinate API.

See also

cf.Coordinate.Y, T, X, Z

Examples:

>>> c.Y
False

Z

Returns False.

Provides compatibility with the cf.Coordinate API.

See also

cf.Coordinate.Z, T, X, ~cf.CoordinateReference.Y

Examples:

>>> c.Z
False

hasbounds

False

Examples:

>>> c.hasbounds
False