pygcam.units

This module contains functions and classes that support symbolic constants usable by the chart command (and user code) for on-the-fly data conversion.

API

class pygcam.units.UnitNamespace

UnitNamespace is a namespace-like class that stores the names of unit conversions, allowing these names to be used in the GCAM tool “chart” sub-command to specify values to multiply or divide by to convert units for plotting. Names can be set and accessed using ‘.’ notation. That is, after calling u = getUnits(), you can access a conversion named, for example, ‘MJ_to_EJ’ as u.MJ_to_EJ, or set a new value for, say, ‘foo’ simply by setting u.foo = value.

Note that the getUnits() method should generally be used rather than calling UnitNamespace() directly to ensure that the single instance of the class is returned.

convert(string, raiseError=True)

Convert the given string to its numerical value, either by direct type conversion, or if this fails, by look-up as the name of a defined unit conversion.

Parameters:
  • string – (str) a string representing a float or the name of a defined unit conversion.
  • raiseError – (bool) if True, an error is raised if the string is neither a number nor a defined unit conversion.
Returns:

(float or None) returns the converted value, or if raiseError is False and the string is not a recognized unit conversion, None is returned.

get(name, raiseError=True)

Get the value of a variable defined in the unitConversion module. Basically an “eval” operation.

Parameters:
  • name – (str) the name of a variable to look up.
  • raiseError – (bool) if True, raise an error if converter is not found.
Returns:

(float or None) the value of the named variable, or None if not found.

pygcam.units.getUnits(other=None)

Returns a singleton instance of a private namespace-like class that can set and get unit conversions.

Parameters:other – (dict-like) an object supporting the items() method that returns pairs of (name, value) that are added to the built-in unit conversion look-up table. Note that elements in other will overwrite existing entries of the same name.
Returns:(UnitNamespace) returns a singleton instance, i.e., subsequent calls will return the same object, though additional names can be passed on each call.