2.5.1. vacumm.data.cf – CF conventions and extensions

Conventions about data formats and names

VAR_SPECS = <vacumm.data.cf.VarSpecs object>

Specifications for variables

AXIS_SPECS = <vacumm.data.cf.AxisSpecs object>

Specifications for axes

format_var(var, name=None, force=True, format_axes=True, order=None, nodef=True, mode='warn', **kwargs)

Format a MV2 variable according to its generic name

Params:

• var: A numpy or MV2 variabe.

• name: Generic name of variable. It should be one of those listed by CF_VAR_SPECS. If None, it is guessed with match_known_var().

• force, optional: Overwrite attributes in all cases.

• format_axes, optional: Also format axes.

• nodef, optional: Remove location specification when it refers to the default location (DEFAULT_LOCATION).

• mode: “silent”, “warn” or “raise”.

• Other parameters are passed as attributes, except those:

  • present in specifications to allow overriding defaults,
  • starting with ‘x’, ‘y’, or ‘t’ which are passed to format_axis().

Examples:

>>> var = format_var(myarray, 'sst', valid_min=-2, valid_max=100)

format_axis(axis, name=None, force=True, recreate=False, format_subaxes=True, nodef=True, mode='warn', **kwargs)

Format a MV2 axis according to its generic name

Params:

• axis: A numpy or MV2 variabe.
• name: Single or list of generic axis names. It should be one of those listed by CF_AXIS_SPECS.If None, it is guessed with match_known_axis().
• force, optional: Overwrite attributes in all cases.
• nodef, optional: Remove location specification when it refers to the default location (DEFAULT_LOCATION).
• axes2d_<param>, optional: <param> is passed to create_axes2d() for 2D axes.
• recreate, optional: Force recreation of axes using either
• Other parameters are passed as attributes.

Examples:

>>> axis1d = format_axis(array1d, 'lon')
>>> axis2d = format_axis(array2d, 'lon_u', axes2d_iid = 'xi',  axes2d_jid = 'xi', recreate=True)

format_grid(grid, pt, **kwargs)

Format a grid and its axes

match_obj(obj, name, searchmode=None, **kwargs)

Check if a variable or an axis matches generic specifications

Params:

• obj: a numpy or cdms2 axis or variable.
• name: A generic names.
• searchmode, optional: Passed to ncmatch_obj().

cf2atts(name, select=None, exclude=None, ordered=True, **extra)

Extract specs from CF_AXIS_SPECS or CF_VAR_SPECS to form a dictionary of attributes (units and long_name)

cf2search(name, mode='isa', raiseerr=True, **kwargs)

Extract specs from CF_AXIS_SPECS or CFVAR_SPECS to form a search dictionary

Params:

• name: Generic name of an axis or a variable.

• mode, optional: Search mode [default: None->``”ns”``]. A string containg one or more of the following letters:

  • "n": Search using names (ids).
  • "s": Search using standard_name attribute.
  • "a": Search using axis attribute.
  • "l": Search using long_name attribute.
  • "u": Search using units attribute.

  The order is important.

Return:

An colections.OrderedDict

Example:

>>> cf2search('sst', mode='isu')
{'id':['sst'], 'id':['sst'],
'standard_names':['sea_surface_temperature'],
'units':['degrees_celsius']}

cp_suffix(idref, id, suffixes=['_t', '_u', '_v', '_w', '_f'])

Copy a suffix if found in an id (name) to another id

get_loc(var, stype=None, mode='loc', default=None)

Get the location testing id, standard_name or long_name and other attributes

Params:

• var: Generic id of the variable or axis OR an object CDAT object (variable or axis). If a CDAT object, it first searches for the _vacumm_cf_location attributes.

• stype, optional: One of ‘id’, ‘standard_name’ or ‘long_name’. If None, they are all tested. If var is a string, location is searched interpreting it as of type 'stype. Else if var is an object stype specifies what attribute to test.

• mode, optional: What you get if something found.

  • "loc": Get the location lowercase letter (like “u”).
  • "ext": Same as "loc" but searches for the position first if case of a CDAT variable, then the _vacumm_cf_physloc attributes or the “physloc” specification if var has an entry in CF_VAR_SPECS, else defaults to DEFAULT_LOCATION.
  • Else, the matched string.

Example:

>>> loc = get_loc('toto_u')
>>> suffix = get_loc('toto_at_u_location', stype='standard_name', mode='full')
>>> loc = get_loc(myvar, stype=['id','long_name'])

Return:

• None if no location spec found,
• if mode=="loc", one of possible physical ARAKAWA_LOCATIONS,
• else, the complete matching string, like “_at_u_location”.

change_loc(var, toloc, axes=True, squeeze=True)

Change location specifications of a variable and its axes

It affects the id, the standard_name and the long_name when they are defined.

Params:

Example:

>>> change_loc(sst, 'u').id
'sst_u'
>>> change_loc(sst, 't', squeeze=True).id
'sst'

change_loc_single(name, stype, loc, squeeze=None)

Change location specification

Params:

• name: String to change
• stype: String type: name, standard_name or long_name.
• loc: Location as a letter or None.
• squeeze, optional: If specified and equal to loc, location is removed instead of being changed.

Example:

>>> change_loc_single('usurf_u', 'name', 't')
'usurf_t'
>>> change_loc_single('sst_at_u_location', 'standard_name', 'v')
'sst_at_v_location'
>>> change_loc_single('usurf_t', 'name', 'u', squeeze='u')
'usurf'

dupl_loc_specs(all_specs, fromname, toloc)

Duplicate the specification for a variable or an axis to another or several locations

The following rules apply:

• If the original specifications are from a name without a specific location (generic), new specs (located) are appended (merged) with original specs.
• If the specifications at target location already exist, it merges new specs with old specs.
• Generic specification are systematically created or updated by merging of specialized ones.

Example:

>>> dupl_loc_specs(CF_VAR_SPECS, 'corio', 'u') # Create the 'corio_u' entry in CF_VAR_SPECS and update 'corio'
>>> dupl_loc_specs(CF_VAR_SPECS, 'corio_t', 'u') # Create 'corio_u' and 'corio_t'

no_loc_single(name, stype)

Remove location specification

Params:

• name: String to change
• stype: One of ‘id’, ‘standard_name’ or ‘long_name’.

change_loc_specs(loc, id=None, standard_name=None, long_name=None, axes=None, iaxis=None, jaxis=None, squeeze=None, **kwargs)

Change location specification in id, standard names long name and axes id

Example:

>>> specs = change_loc_specs('v', id = ['usurf_u', 'u_u'])

Return:

A dictionary

squeeze_loc_single(name, stype, physloc=None)

Squeeze location specs if it matches physical location

squeeze_loc(var)

Squeeze out location specification of a variable if the location is physloc or DEFAULT_LOCATION

Params:

• var: CDAT variable.
• physloc, optional: physloc specs given by the entry in CF_VAR_SPECS or DEFAULT_LOCATION.

Return:

The same variable

get_physloc(var)

Get the physical location of a variable

Note

The physical location may be different from the current location.

It defaults to DEFAULT_LOCATION

HIDDEN_CF_ATTS = ['_vacumm_cf_name', '_vacumm_cf_physloc', '_vacumm_cf_location']

Hidden attributes of variable useful of this module

set_loc(var, loc, addpos=False)

Define (or remove) the location of a variable with _vacumm_cf_location attribute

It also makes sure that the position attribute is the same if present.

Params:

• var: CDAT variable.
• loc: Location. If empty, remove _vacumm_cf_location and position attributes.
• addpos, optional: Set also the position attribute.

match_known_var(obj, searchmode=None, **kwargs)

Check if an object matches a known variable

match_known_axis(obj, searchmode=None, **kwargs)

Check if an object matches a known axis

CF_AXIS_SPECS = <vacumm.data.cf.AxisSpecs object>

Specifications for axes

CF_VAR_SPECS = <vacumm.data.cf.VarSpecs object>

Specifications for variables

register_cf_variable(name, **specs)

Register a new CF variable given its generic name and its specs

It simply calls register() on CF_VAR_SPECS

register_cf_variables_from_cfg(cfg)

Register a new CF variables from a config file or a dict

It must contains a “variables” section.

It simply calls register_from_cfg() on CF_VAR_SPECS

register_cf_axis(name, **specs)

Register a new Cf axis given its generic name and its specs

It simply calls register() on CF_AXIS_SPECS

register_cf_axes_from_cfg(cfg)

Register a new CF variables from a config file or a dict

It must contains a “axes” section.

It simply calls register_from_cfg() on CF_AXIS_SPECS

get_cf_cmap(vname)

Get a cmap from a standard name

cmap may be specified for a variable with the ‘cmap’ key of its entry in CF_VAR_SPECS.

is_cf_known(name, type=None)

Is this names registered in CF_VAR_SPECS or CF_AXIS_SPECS

class VarSpecs(inherit=None, names=None)

Bases: vacumm.data.cf.BaseSpecs

category = 'variables'

class AxisSpecs(inherit=None, names=None)

Bases: vacumm.data.cf.BaseSpecs

category = 'axes'

CF_VAR_NAMES = ['temp', 'ptemp', 'sal', 'sst', 'sss', 'dens', 'sigmat', 'ndens', 'sigmatheta', 'pdens', 'sigma0', 'sigma1', 'sigma2', 'sigma3', 'sigma4', 'ssd', 'conduct', 'sndspd', 'mld', 'ped', 'ohc', 'osc', 'cp', 'ssh', 'u', 'v', 'w', 'u3d', 'v3d', 'w3d', 'ubt', 'vbt', 'ubc', 'vbc', 'usurf', 'vsurf', 'ugbt', 'vgbt', 'cspd', 'speed', 'cdir', 'ke', 'eke', 'tke', 'mke', 'kz', 'bathy', 'bathy_u', 'bathy_v', 'meanlev', 'depth', 'altitude', 'dx', 'dy', 'dz', 'dlon', 'dlat', 'cvol', 'vol', 'corio', 'beta', 'oro', 'orosm', 'nethf', 'lwnhf', 'swnhf', 'ghf', 'lwuhf', 'swuhf', 'lwdhf', 'swdhf', 'lathf', 'hflat', 'senhf', 'hfsen', 'evap', 'rain', 't2m', 'q2m', 'hu2m', 'z0a', 'cda', 'cha', 'cea', 'wspd', 'wdir', 'wfdir', 'wtdir', 'uair', 'vair', 'wair', 'tair', 'pa', 'tkea', 'u10m', 'v10m', 'w10m', 'ux10m', 'vy10m', 'tauu', 'tauv', 'taux', 'tauy', 'topheight', 'hs', 'mssx', 'mssy', 'mss', 'mlw', 't0m1', 'dp', 'tp', 'fp', 'th1p', 'char', 'ubr', 'uubr', 'vubr', 'bhd', 'foc', 'utwo', 'vtwo', 'utaw', 'vtaw', 'fbb', 'utbb', 'vtbb', 'uuss', 'vuss', 'utus', 'vtus', 'mapsta', 'wlv', 'mld_t', 'ped_t', 'ohc_t', 'osc_t', 'cp_t', 'u_u', 'u_t', 'u_v', 'v_v', 'v_t', 'v_u', 'w_w', 'u3d_u', 'u3d_t', 'u3d_v', 'v3d_v', 'v3d_t', 'v3d_u', 'w3d_w', 'ubt_u', 'ubt_t', 'ubt_v', 'vbt_v', 'vbt_t', 'vbt_u', 'ubc_u', 'ubc_t', 'ubc_v', 'vbc_v', 'vbc_t', 'vbc_u', 'usurf_u', 'usurf_t', 'usurf_v', 'vsurf_v', 'vsurf_t', 'vsurf_u', 'ugbt_u', 'ugbt_t', 'ugbt_v', 'vgbt_v', 'vgbt_t', 'vgbt_u', 'cspd_t', 'cspd_u', 'cspd_v', 'speed_t', 'speed_u', 'speed_v', 'cdir_t', 'cdir_u', 'cdir_v', 'bathy_t', 'depth_t', 'depth_u', 'depth_v', 'depth_w', 'altitude_t', 'altitude_u', 'altitude_v', 'altitude_w', 'dx_t', 'dx_u', 'dx_v', 'dx_f', 'dy_t', 'dy_u', 'dy_v', 'dy_f', 'dz_t', 'dz_u', 'dz_v', 'dz_w', 'dlon_t', 'dlon_u', 'dlon_v', 'dlon_f', 'dlat_t', 'dlat_u', 'dlat_v', 'dlat_f', 'cvol_t', 'cvol_u', 'cvol_v', 'cvol_w', 'vol_t', 'vol_u', 'vol_v', 'vol_w', 'corio_t', 'corio_u', 'corio_v', 'corio_f', 'u10m_t', 'u10m_u', 'u10m_v', 'v10m_t', 'v10m_u', 'v10m_v', 'ux10m_t', 'ux10m_u', 'ux10m_v', 'vy10m_t', 'vy10m_u', 'vy10m_v', 'tauu_u', 'tauv_v', 'taux_u', 'tauy_v']

List of generic variable names

CF_AXIS_NAMES = ['time', 'lon', 'lat', 'depth', 'depth_t', 'depth_u', 'depth_v', 'depth_w', 'level', 'level_w', 'ni', 'nj', 'lon_t', 'lon_u', 'lon_v', 'lon_f', 'lat_t', 'lat_u', 'lat_v', 'lat_f', 'ni_t', 'ni_u', 'ni_v', 'ni_f', 'nj_t', 'nj_u', 'nj_v', 'nj_f']

List of generic axis names