Navigation

cf.CoordinateReference

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

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)[source]

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()
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(key[, default])
has_key(key)
identity([default]) Return the identity of the coordinate reference.
inspect() Inspect the attributes.
items()
iteritems()
iterkeys()
itervalues()
keys()
match([match, exact, match_all, inverse]) Test whether or not the coordinate reference satisfies the given conditions.
pop(key[, default])
popitem()
remove_all_coords() Remove all links to coordinate objects.
set(term, value)
setcoord(term, value)
setdefault(key[, default])
structural_signature([rtol, atol])
update(*args, **kwds)
values()

Attributes

T False.
X Returns False.
Y Returns False.
Z Returns False.
hasbounds False
classmethod canonical_units(term)[source]

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)[source]

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

Close all files referenced by coordinate conversion term values.

Returns:None
Examples: 
>>> c.close()
copy(domain=None)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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: 
>>>
has_key(key)[source]
identity(default=None)[source]

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

Inspect the attributes.

See also

cf.inspect

Returns:None
match(match=None, exact=False, match_all=True, inverse=False)[source]

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:
remove_all_coords()[source]

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)[source]
setcoord(term, value)[source]
structural_signature(rtol=None, atol=None)[source]
T

False.

Provides compatibility with the cf.Coordinate API.

See also

cf.Coordinate.T, X, Y, Z

Examples: 
>>> c.T
False
X

Returns False.

Provides compatibility with the cf.Coordinate API.

See also

cf.Coordinate.X, T, 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, Y

Examples: 
>>> c.Z
False
hasbounds

False

Examples: 
>>> c.hasbounds
False

Previous topic

cf.CoordinateBounds.where

Next topic

cf.Data

This Page

Navigation

© Copyright 2015, David Hassell. Last updated on Oct 28, 2015. Created using Sphinx 1.2.2.