cf.CoordinateReference¶

class cf.CoordinateReference(name=None, crtype=None, coordinates=None, ancillaries=None, parameters=None, datum=None)[source]¶

Bases: 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 scalar 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.
!coordinates	The identities of the dimension and auxiliary coordinate objects of the which apply to this coordinate reference.

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'

coordinates: 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.coordinates
{'latitude', 'longitude', 'projection_x_coordinate', 'projection_y_coordinate'}

>>> c = cf.CoordinateReference('transverse_mercator', coordinates=['ncvar%lat'])
>>> c.coordinates
{'ncvar%lat', 'latitude', 'longitude', 'projection_x_coordinate', 'projection_y_coordinate'}

kwargs: optional

The terms of the coordinate conversion and their values. A term’s value 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, coordinates=None, ancillaries=None, parameters=None, datum=None)[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'

coordinates: 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.coordinates
{'latitude', 'longitude', 'projection_x_coordinate', 'projection_y_coordinate'}

>>> c = cf.CoordinateReference('transverse_mercator', coordinates=['ncvar%lat'])
>>> c.coordinates
{'ncvar%lat', 'latitude', 'longitude', 'projection_x_coordinate', 'projection_y_coordinate'}

kwargs: optional

The terms of the coordinate conversion and their values. A term’s value 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, coordinates, ...])	Initialization
`canonical_units`(term)	Return the canonical units for a standard CF coordinate conversion term.
`CoordinateReference.change_coord_identities`
`clear`([coordinates, parameters, ancillaries])
`close`()	Close all files referenced by coordinate conversion term values.
`copy`()	Return a deep copy.
`default_value`(term)	Return the default value for an unset standard CF coordinate conversion term.
`dump`([display, omit, field, key, _level, _title])	Return a string containing a full description of the coordinate reference object.
`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`((k) -> True if D has a key k, else False)
`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), ...)	2-tuple; but raise KeyError if D is empty.
`CoordinateReference.remove_all_coords`
`CoordinateReference.set`
`CoordinateReference.setcoord`
`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`	False.
`Y`	False.
`Z`	False.
`hasbounds`	False.

all_identifiers()[source]¶

canonical(field=None)[source]¶

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_identifiers(identity_map, coordinate=True, ancillary=True, strict=False, i=False)[source]¶

Change the

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

Parameters:

identity_map: dict: For example: {'dim2': 'dim3', 'aux2': 'latitude', 'aux4': None}
strict: bool, optional: If True then coordinate or domain ancillary identifiers not set in the identity_map dictiontary are set to None. By default they are left unchanged.

i: bool, optional

Returns:

None

Examples:

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

clear(coordinates=True, parameters=True, ancillaries=True)[source]¶

close()[source]¶

Close all files referenced by coordinate conversion term values.

Returns:	None
Examples:

>>> c.close()

copy()[source]¶

Return a deep copy.

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

Examples 1:

>>> d = c.copy()

Returns:	out: The deep copy.

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.
Examples:

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

dump(display=True, omit=(), field=None, key=None, _level=0, _title=None)[source]¶

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

Parameters:

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

field: cf.Field, optional

key: str, optional: Ignored.

Returns:

out: None or str

Examples:

equals(other, rtol=None, atol=None, ignore_fill_value=False, traceback=False, mapping=None)[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:

>>>

fromkeys(S[, v]) → New dict with keys from S and values equal to v.¶: v defaults to None.

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

has_key(k) → True if D has a key k, else False¶

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:

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

inspect()[source]¶

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

name(default=None, identity=False, ncvar=False)[source]¶

Return a name.

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

The standard_name CF property.

The !id attribute.

The long_name CF property, preceeded by the string 'long_name:'.

The !ncvar attribute, preceeded by the string 'ncvar%'.

The value of the default parameter.

Note that f.name(identity=True) is equivalent to f.identity().

See also

identity

Examples 1:

>>> n = r.name()
>>> n = r.name(default='NO NAME'))

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.

set_term(term_type, term, value)[source]¶

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

structural_signature(rtol=None, atol=None)[source]¶

update([E, ]**F) → None. Update D from dict/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 in F: D[k] = F[k]

values() → list of D's values¶

viewitems() → a set-like object providing a view on D's items¶

viewkeys() → a set-like object providing a view on D's keys¶

viewvalues() → an object providing a view on D's values¶

T¶

False. Coordinate reference objects are not T coordinates.

See also

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

Examples:

>>> c.T
False

X¶

False. Coordinate reference objects are not X coordinates.

Provides compatibility with the cf.Coordinate API.

See also

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

Examples:

>>> c.X
False

Y¶

False. Coordinate reference objects are not Y coordinates.

See also

cf.Coordinate.Y, T, X, Z

Examples:

>>> c.Y
False

Z¶

False. Coordinate reference objects are not Z coordinates.

See also

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

Examples:

>>> c.Z
False

conversion¶

hasbounds¶

False. Coordinate reference objects do not have cell bounds.

Examples:

>>> c.hasbounds
False

cf.CoordinateReference¶

Previous topic

Next topic

This Page