gavo.base.unitconv module

A python module to parse VOUnit strings and compute conversion factors.

We believe this implements the full VOUnit specification.

To use this, you must have the gavo utils package installed. For details, see http://soft.g-vo.org. The changes required to make this work without gavo.utils are minute, though. If you want that, talk to the authors.

Unit tests for this are at

http://svn.ari.uni-heidelberg.de/svn/gavo/python/trunk/tests/unitconvtest.py

exception gavo.base.unitconv.BadUnit(msg='', hint=None)

Bases: gavo.utils.excs.Error

class gavo.base.unitconv.Expression(term, scaleFactor)

Bases: gavo.base.unitconv._Node

The root node of an expression tree.

This contains a term and optionally a scale factor.

classmethod fromToks(s, p, toks)

getSI()

returns a pair of a numeric factor and a dict mapping SI units to their powers.

class gavo.base.unitconv.Factor(unit, power)

Bases: gavo.base.unitconv._Node

A UnitNode with a power.

classmethod fromToks(s, p, toks)

getFactorWithUnit(unit)

see Term.getFactorWithUnit.

getSI()

class gavo.base.unitconv.FunctionApplication(funcName, term)

Bases: gavo.base.unitconv._Node

A function applied to a term.

classmethod fromToks(s, p, toks)

getFactorWithUnit(unit)

see this method in Term.

We don’t simplify any units here, as that’s a bit hard in the current logic – though there’s something to be won, in particular with sqrt. Ah well.

getSI()

exception gavo.base.unitconv.IncompatibleUnits(msg='', hint=None)

Bases: gavo.utils.excs.Error

class gavo.base.unitconv.QuotedUnitNode(unit)

Bases: gavo.base.unitconv._Node

a quoted (“defined unknown”) unit.

classmethod fromToks(s, p, toks)

getSI()

class gavo.base.unitconv.Term(op1, operator, op2)

Bases: gavo.base.unitconv._Node

A Node containing two factors and an operator.

The operator here is either . (product) or / (division).

classmethod fromToks(s, p, toks)

getFactorWithUnit(unit)

returns a factor within self with unit if it exists.

Actually, it will return that factor and the exponentiation factor, which is -1 if that factor is in the denominator, 1 otherwise. This returns None, None if no such factor exists.

getSI()

class gavo.base.unitconv.UnitNode(unit, prefix='')

Bases: gavo.base.unitconv._Node

a terminal node containing a unit, possibly with a prefix

This is normally constructed through the fromToks constructor.

Check out the unit, prefix, and isUnknown attributes. The prefix can be turned to a factor using the PREFIXES dictionary. An empty prefix (factor 1) is represented by an empty string.

classmethod fromToks(s, p, toks)

getSI()

returns a pair of factor and basic unit.

Basic units are what’s in the defining pairs in the PLAIN_UNITS dict.

gavo.base.unitconv.asSequence(unitDict)

returns a sorted tuple of (si, power) for a result of getSI().

These should be more suitable for dimensional analysis.

gavo.base.unitconv.computeColumnConversions(newColumns, oldColumns)

returns a dict of conversion factors between newColumns and oldColumns.

Both arguments are iterables of columns.

For every column in newColumn, the function sees if the units of newColumn and oldColumn match. If they don’t, compute a conversion factor to be multiplied to oldColumns values to make them newColumns values and add it to the result dict.

The function raises a DataError if a column in newColumns has no match in oldColumns.

gavo.base.unitconv.computeConversionFactor(unitStr1, unitStr2)

returns the factor needed to get from quantities given in unitStr1 to unitStr2.

Both must be given in VOUnits form.

This function may raise a BadUnit if one of the strings are malformed, or an IncompatibleUnit exception if the units don’t have the same SI base.

If the function is successful, unitStr1 = result*unitStr2

gavo.base.unitconv.evalAll(s, p, toks)

a parse action evaluating the whole match as a python expression.

Obviously, this should only be applied to carefully screened nonterminals.

gavo.base.unitconv.formatScaleFactor(aFloat)

returns a reasonable decorative but python-readable representation of aFloat.

Floats looking good as simple decimals (modulus between 0.01 and 1000) are returned without exponent.

gavo.base.unitconv.getSpecConverter(fromUnit, toUnit)

Returns a function converting spectral values in fromUnit to toUnit.

gavo.base.unitconv.getSpecExpr(fromUnit, toUnit)

returns an expression that turns a value in fromUnit to one in toUnit.

The value in fromUnit is represented by a {} so you can just .format the expression it is in into the resulting string.

class gavo.base.unitconv.getUnitGrammar(arg)

Bases: gavo.utils.codetricks.CachedResource

the grammar to parse VOUnits.

After initialization, the class has a “symbols” dictionary containing the individual nonterminals.

cache = unit expression

classmethod enableDebuggingOutput()

(not user-servicable)

classmethod impl()

symbols = {'CLOSE_P': ")", 'FLOAT': Re:('[+-]?([0-9]+(\\.[0-9]*)?)'), 'FUNCTION_NAME': W:(ABCD...), 'Forward': <class 'gavo.imp.pyparsing.Forward'>, 'Literal': <class 'gavo.imp.pyparsing.Literal'>, 'OPEN_P': "(", 'Optional': <class 'gavo.imp.pyparsing.Optional'>, 'Regex': <class 'gavo.imp.pyparsing.Regex'>, 'SIGN': {"+" | "-"}, 'SIGNED_INTEGER': {{"+" | "-"} W:(0123...)}, 'Suppress': <class 'gavo.imp.pyparsing.Suppress'>, 'UNSIGNED_INTEGER': W:(0123...), 'VOFLOAT': Re:('0.[0-9]+([eE][+-]?[0-9]+)?|[1-9][0-9]*(\\.[0-9]+)?([eE][+-]?[0-9]+)?'), 'Word': <class 'gavo.imp.pyparsing.Word'>, 'ZeroOrMore': <class 'gavo.imp.pyparsing.ZeroOrMore'>, 'alphas': 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz', 'any_unit_atom': {atomic unit | quoted atomic unit}, 'cls': <class 'gavo.base.unitconv.getUnitGrammar'>, 'complete_expression': Forward: {units term [{"/" unit expression}]}, 'division_operator': "/", 'factor': factor, 'function_application': function application, 'input': unit expression, 'integer': integer, 'multiplication_operator': ".", 'numeric_power': {{{integer | {{"(" integer} ")"}} | {{"(" Re:('[+-]?([0-9]+(\\.[0-9]*)?)')} ")"}} | {{{{"(" integer} "/"} W:(0123...)} ")"}}, 'pow_10': {{"10" "**"} {{{integer | {{"(" integer} ")"}} | {{"(" Re:('[+-]?([0-9]+(\\.[0-9]*)?)')} ")"}} | {{{{"(" integer} "/"} W:(0123...)} ")"}}}, 'power_operator': "**", 'product_of_units': units term, 'pyparsingWhitechars': <function pyparsingWhitechars>, 'quoted_unit_atom': quoted atomic unit, 'scale_factor': scale_factor, 'unit_atom': atomic unit, 'unit_expression': unit expression}

gavo.base.unitconv.parseUnit(unitStr, unitGrammar=unit expression)

gavo.base.unitconv.toStdSpecUnit(fromUnit)

returns a pair of (standard unit, factor) to turn fromUnit into one of J, Hz, or m.

Unconvertable units raise a UfuncError.