2.3.3. vacumm.misc.axes – Tools for axes

2.3.3.1. Overview

Attributes:

BASIC_AXIS_DEFAULTS

BASIC_AXIS_SPECS

Functions:

axis_type() check_axes() check_axis() check_id() check_order() create_axis() create_dep() create_depth() create_lat()

create_lon() create_time() get_axis_type() get_checker() get_order() guess_timeid() is_geo_axis() is_geo_axis_type() isaxis()

isdep() islat() islev() islon() istime() merge_orders() order_match() set_order()

2.3.3.2. Content

Generic tools dealing with information about longitude, latitude, depth and time axes

See also

Tutorials: user.tut.misc.variables.axes

axis_type(axis, genname=False, **kw)

Return the axis type as a signle letter (CDAT standards): -, t, z, y, or x

Params:

• axis: CDAT axis.
• genname, optional: Return a generic name or None.
• Other keywords are passed to checking functions (islon()…).

Example:

>>> get_axis_type(create_time((5,),'days since 2000'))
't'
>>> get_axis_type(axis, genname=True, ro=True, checkatts=False)
'time'

check_axes(var, **kw)

Check the format of all axes of a cdms variable

check_axis(axis, **kw)

Check the format an axis

check_id(axis, **kwargs)

Verify that an axis has a suitable id (not like ‘axis_3’ but ‘lon’)

check_order(var, allowed, vertical=None, copy=False, reorder=False, extended=None, getorder=False)

Check that the axis order of a variable is matches at least one the specifed valid orders

Params:

• var: MV2 array.

• allowed: A single order string or a list. It should contain one or several of these letters:

  • x: longitudes,
  • y: latitudes,
  • z: vertical levels,
  • t: time axis,
  • d: data values (ignored),
  • -: any kind of axis.

Return:

var, or var, order, reordered if reorder is True.

create_axis(values, atype='-', **atts)

Quickly create a cdms2 axis

Params:

• values: Numerical values.
• atype, optional: axis type within ‘x’,’y’,’z’,’t’,’-‘ [default: ‘-‘]
• Other keywords are passed as attributes to the axis.

Example:

>>> lon = create_axis(N.arange(-10., 0, 2), 'x')
>>> lon = create_axis((-10., 0, 2), 't', id='temps', units='seconds since 2000')
>>>

create_dep(values, **atts)

Create a depthaxis

Params:

• values: Numeric values
• Keywords are passed as attributes to the axis.

Example:

>>> create_dep(numpy.arange(-1000., -500., 10.))
>>> create_dep(numpy.arange(-1000., -500., 10.),long_name='deep_depth')

create_depth(values, **atts)

Create a depthaxis

Params:

• values: Numeric values
• Keywords are passed as attributes to the axis.

Example:

>>> create_dep(numpy.arange(-1000., -500., 10.))
>>> create_dep(numpy.arange(-1000., -500., 10.),long_name='deep_depth')

create_lat(values, **atts)

Create a latitude axis

Params:

• values: Numeric values
• Keywords are passed as attributes to the axis.

Example:

>>> create_lat(numpy.arange(40., 48., 1.5))
>>> create_lat(numpy.arange(40., 48., 1.5),long_name='strange_latitude')

create_lon(values, **atts)

Create a longitude axis

Params:

• values: Numeric values
• Keywords are passed as attributes to the axis.

Example:

>>> create_lon(numpy.arange(-18., -5.))
>>> create_lon(numpy.arange(-18., -5.),long_name='original_longitude')

create_time(values, units=None, **atts)

Create a time axis

Params:

• values: Numeric values, or list of date objects (datetime, comptime(), reltime()).
• units, optional: Time units like ‘days since 2000-01-01’.
• Other keywords are passed as attributes to the axis.

Note

Units must be provided explicitly if no date are passed.

Example:

>>> from vacumm.misc.atime import create_time
>>> from datetime import datetime
>>> import cdtime
>>> taxis = create_time([1,2],units='months since 2000',long_name='My time axis')
>>> taxis = create_time(taxis)
>>> create_time([datetime(2000,1,1),'2000-2-1'],units='months since 2000')
>>> create_time([cdtime.reltime(1,'months since 2000'),cdtime.comptime(2000,1)])

get_axis_type(axis, genname=False, **kw)

Return the axis type as a signle letter (CDAT standards): -, t, z, y, or x

Params:

• axis: CDAT axis.
• genname, optional: Return a generic name or None.
• Other keywords are passed to checking functions (islon()…).

Example:

>>> get_axis_type(create_time((5,),'days since 2000'))
't'
>>> get_axis_type(axis, genname=True, ro=True, checkatts=False)
'time'

get_checker(name)

Get the function that checks if an axis of required type

Params:

• name: Generic name of the axis.

Returns:

islon(), islat(), islevel(), istime() or raises TypeError

Example:

>>> get_checker('x')
>>> get_checker('lon')(myaxis)

get_order(var)

Enhanced version of getOrder() method that handles 2D axes

Params:

• var: axis or cdms variable.

Output:

string containing letters x, y, z, t or -

Example:

>>> get_order(var)
"-yx"

guess_timeid(ncfile, vnames=None)

Guess the id of the time axis in a netcdf file

Params:

• ncfile: Netcdf file name or descriptor.
• vnames, optional: List of variables to look for a time axis (defaults to all variables)

Return:

The id as a string, or None if not found.

Example:

>>> tid = guess_timeid('file.nc')
>>> f = cdms2.open('file.nc')
>>> tid = guess_timeid(f)
>>> f.close()

is_geo_axis(axis, **kw)

Return True if axis is time, level, lat or lon

is_geo_axis_type(obj, atype, defaults=None, ro=False, checkaxis=True, checkatts=True, **attchecks)

Check if an object is of a specific type

Params:

• obj: CDAT 1D or 2D axis or other object.
• atype: Axis type as one of ‘x’, ‘y’, ‘z’ or ‘z’.
• ids, optional: List od ids to check.
• standard_names, optional: List of standard_names to check.
• long_names, optional: List of long_names to check.
• units, optional: List of units to check.
• ro, optional: Read-only mode?
• checkatts, optional: If False, do not check units and long_name attributes.
• attchecks: Extra keywords are attributes name and checklist that will checks using match_atts().

isaxis(obj)

isdep(obj, defaults=None, ro=False, checkaxis=True, checkatts=True, **attchecks)

Check if an object is of depth type

islat(obj, defaults=None, ro=False, checkaxis=True, checkatts=True, **attchecks)

Check if an object is of latitude type

islev(obj, defaults=None, ro=False, checkaxis=True, checkatts=True, **attchecks)

Check if an object is of level type

islon(obj, defaults=None, ro=False, checkaxis=True, checkatts=True, **attchecks)

Check if an object is of longitude type

istime(obj, defaults=None, ro=False, checkaxis=True, checkatts=True, **attchecks)

Check if an object is of time type

merge_orders(order1, order2, raiseerr=True)

Merge two axis orders

When two orders doesn’t have the same length, they are right adjusted.

Examples:

>>> merge_orders('t-x', 'y-')
'tyx', 'yx'
>>> merge_orders('yx', 'tz')
'yx', 'tz'
>>> merge_orders(myvar, zaxis)

order_match(order1, order2, asscore=False, strict=False)

Check that to axis orders are compatible

Params:

• order1/2: Order strings containing x, y, z, t or - chars.

• asscore, optional: Return the total level of matching, where, for one char:

  • 0: no matching,
  • 1: matching with -,
  • 2: letters equal.

• strict, optional: Be more strict.

  • False: Not strict.
  • True or "both": Fail even with -.
  • "left" or "right": Designate the reference order, where the other one is not allowed to be different, except when the former has a -.

Examples:

>>> order_match('y', 'x')
False
>>> order_match('x-', 'xy')
True
>>> order_match('x-', 'xy', strict="right")
False

set_order(var, order, replace=False)

Restore axis order of cdms variable

Params:

• var: A cdms array.
• order: A cdms order string(like ‘tx’)
• replace: Erase existing axis types?

Example:

>>> set_order(temp, 'tyx')