cmiputil.convoc module

Access CMIP6 Controlled Vocabularies(CVs).

Controlled Vocabularies

A CV, in simplest form, is a list of the permitted values that can be assigned to a given global attribute, such as <activity_id>, <experiment_id>, etc.

For some attributes, such as <source_id>, its value is a key-value pair, whose value is again dict of key-value.

CVs search path

CVs are maintained as json files. You should clone them from github.

Search path for CVs is set in the order below:

1. paths given to the constructor or ConVoc.setSearchPath()

2. CMIP6_CVs_dir in section [ConVoc] in config file.

3. current directory

Non-existent directories are omitted silently. You have to specify '.' explicitly if necessary. Note that the order is meaningful.

exception convoc.ControlledVocabulariesError

Bases: Exception

Base exception class for convoc.

exception convoc.InvalidCVAttribError

Bases: convoc.ControlledVocabulariesError

Error for invalid attribute as a Controlled Vocabulary

exception convoc.InvalidCVKeyError

Bases: convoc.ControlledVocabulariesError

Error for invalid key as a Controlled Vocabulary for valid attribute.

exception convoc.InvalidCVPathError

Bases: convoc.ControlledVocabulariesError

Error for invalid path as a Controlled Vocabulary

class convoc.ConVoc(conffile='', paths='')

Bases: object

Class for accessing CMIP6 Controlled Vocabularies.

This class reads CV from corresponding json file on demand and keep as a member.

See setSearchPath() for the argument path.

conf

‘[ConVoc]’ section of conffile

cvpath

list of CV files search path.

Parameters

• conf (path-like) – config file

• paths (str) – a colon separated string

Examples

>>> cvs = ConVoc()
>>> activity = cvs.getAttrib('activity_id')
>>> activity['CFMIP']
'Cloud Feedback Model Intercomparison Project'
>>> cvs.getValue('CFMIP', 'activity_id')
'Cloud Feedback Model Intercomparison Project'

>>> cvs.isValidValueForAttr('MIROC-ES2H', 'source_id')
True
>>> cvs.isValidValueForAttr('MIROC-ES2M', 'source_id')
False

In the below example, instance member attribute experiment_id is set AFTER isValidValueForAttr().

>>> hasattr(cvs, 'experiment_id')
False
>>> cvs.isValidValueForAttr('historical', 'experiment_id')
True
>>> hasattr(cvs, 'experiment_id')
True

In the below, example, table_id has only keys with no value, getValue() return nothing (not None).

>>> cvs.isValidValueForAttr('Amon', 'table_id')
True
>>> cvs.getValue('Amon', 'table_id')

Invalid attribute raises InvalidCVAttribError.

>>> cvs.getAttrib('invalid_attr')
Traceback (most recent call last):
  ...
InvalidCVAttribError: Invalid attribute as a CV: invalid_attr

Invalid key for valid attribute raises KeyError.

>>> cvs.getValue('CCMIP', 'activity_id')
Traceback (most recent call last):
  ...
KeyError: 'CCMIP'

getAttrib(attr)

Return values of given attr.

attr must be valid and it’s json file must be in CV search path.

Parameters

attr (str) – attribute to get. must be in managedAttribs

Raises

InvalidCVAttribError – if attr is invalid

Returns

str or dict or “” – CV values for attr

getSearchPath()

Return search paths for CV.

Returns

list of path-like – search path.

getValue(key, attr)

Return current value of key of attribute attr.

Parameters

• key (str) – key to be get it’s value.

• attr (str) – attribute, must be in managedAttribs

Raises

• InvalidCVAttribError – if attr is invalid

• KeyError – if key is invalid for attr

Returns

object – value of key, or None if key has no value.

isValidValueForAttr(key, attr)

Check if given key is in CV attr.

Parameters

• key (str) – to be checked

• attr (str) – attribute, must be in managedAttribs

Raises

• InvalidCVAttribError – if attr is invalid

• KeyError – if key is invalid for attr

Returns

bool

setAttrib(attr)

Read CV json file for attr and set members of self.

If attr is already read and set, do nothing.

Parameters

attr (str) – attribute to be read and set, must be in managedAttribs

Raises

• InvalidCVAttribError – if attr is invalid.

• InvalidCVPathError – if a valid CV file not found.

Returns

nothing.

setSearchPath(paths='')

Set search path for CV json files.

paths must be a colon separated string of serach path.

Parameters

paths (str) – a colon separated string

Raises

InvalidCVPathError – Unless valid path is set.

Returns

nothing

managedAttribs = ('activity_id', 'experiment_id', 'frequency', 'grid_label', 'institution_id', 'license', 'nominal_resolution', 'realm', 'required_global_attributes', 'source_id', 'source_type', 'sub_experiment_id', 'table_id')

Attributes managed by this class. Note that this is the CLASS attribute, not an instance attribute.

convoc.getDefaultConf()

Return default values for config file.

Intended to be called before config.writeConf()

Example

>>> from cmiputil import convoc, config
>>> conf = config.Conf(None)   #  to create brank config
>>> conf.setCommonSection()
>>> d = convoc.getDefaultConf()
>>> conf.read_dict(d)
>>> conf.writeConf('/tmp/cmiputil.conf', overwrite=True)

After above example, /tmp/cmiputil.conf is as below:

[cmiputil]
cmip6_data_dir = /data

[ConVoc]
cmip6_cvs_dir = ./:./CMIP6_CVs:~/CMIP6_CVs:/data/CMIP6_CVs

convoc.DEFAULT_CVPATH = './:./CMIP6_CVs:~/CMIP6_CVs:/data/CMIP6_CVs'

path to be written to the sample config file, via getDefaultConf()