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’ asu.MJ_to_EJ
, or set a new value for, say, ‘foo’ simply by settingu.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.