tunits: Convert table column from one set of units to another

Package: nttools

Usage

tunits table column newunits

Description

Tunits converts a column in a table from one set of units to another. It supports both scalar and array columns. You supply the table and column name and the new units you want the column to be in. Optionally, you can apply the current column units if the units string stored in the table is missing or incorrect. Tunits only supports multiplicative conversions, conversions that involve additive changes, like Kelvin to Celsius, are not supported. Unit names and conversions are read from two tables. You can copy these tables and edit them if you want to add new conversions.

You can find out the current units for a table column by running tlcol. If a units conversion is not supported by this task and you know the conversion formula, you can run tcalc.

Tunits must parse the unit strings you pass it, which requires that they follow a certain set of rules. Units can be a simple units name, such as ergs, or a units name raised to a power, such as meters^2, or the product or quotient of units names raised to a power, such as feet/sec or gm*cm/s^2. If two units names are next to each other without any operator between them, a multiplication is assumed. If a units name is followed by a number, the units name is assumed to be raised to that power.

Powers can also be specified by preceding the unit name with the string "square", "sq", "cubic", or "cu". For example, "square meter" is equivalent to "meter^2".

The operators recognized are:

division        / or per
multiplication  *
exponentiation  ^ or **

Division has the lowest priority and exponentiation the highest. This means ergs/sec*angstrom is interpreted as ergs/(sec*angstrom) and not (ergs/sec)*angstrom, as it would be in most computer languages. The default priority can be changed by changed by grouping terms with parentheses.

Each set of units can have several synonymous names. These names are listed in the abbreviations table. Case is not significant in names and regular plurals (made by adding an "s") are converted to the singular. Names should contain only alphabetic characters. Blanks, underscores and digits are not allowed.

The conversions supported by this task are read from the units conversion table. The table lists the old and new units and a conversion factor. Only one conversion is allowed for each set of units.

Parameters

table [file]: The name of the table the conversion is applied to.

column [string]: The column to be converted. Both scalar and array columns are supported.

newunits [string]: The new set of units for the column. The format of this parameter is described above. This task writes the new units to the units field in the table column.

(oldunits = " ") [string]: The units that the table column is currently in. If the value of this parameter is blank, the units will be read from the table.

(abrevtab = "ttools$tunits/abrev.tab") [file]: A table of alternate names for each unit. This table contains two columns. The first column is the name of the units and the second column is the standard abbreviation. Because the default table is an ascii file, columns are read positionally and not by column names Many units have more than one name or abbreviation. Using a standard abbreviation allows units to be converted to a standard form, which simplifies calculations. The standard abbreviation is used internally when computing the conversion factor. Case is not significant in names and regular plurals (made by adding an "s") are converted to the singular before looking them up in the table. Names should contain only alphabetic characters. Blanks, underscores and digits are not allowed. The name of this table is a parameter to allow you to create your own table of standard abbreviations, with additional units.

(unittab = "ttools$tunits/units.tab") [file]: A table of conversion factors from one set of units into another. This table contains four columns. The first is the conversion factor, a double precision number. The second is the units the task tries to convert from. The third column is the units the task tries to convert to. The fourth column is contains the boolean variable swap, explained a little later. The table is interpreted as "There are <factor> <from> in a <to>." For example, "There are 100 centimeters in a meter." The last column, swap, does not change the sense of the sentence but does change the direction that the conversion is applied, For example, "60 seconds in a minute" is actually a conversion from minutes to seconds because swap is yes. Unit conversions should set swap to yes when the desired conversion is not an exact value, but its inverse is. Only one conversion is allowed per unit, which simplifies the program logic considerably. Conversions should be chosen so that they ultimately resolve to MKS units. To prevent endless loops conversions from the fundamental units of MKS are checked for and forbidden. However, the program does not check for other loops, so be careful when adding new conversions! As in the case of the abbreviation table, the table name is a parameter to allow you to create your own table with additional unit conversions.

(verbose = no) [bool]: If you set this parameter to yes, the task will print a message to STDERR for each units conversion utilized in computing the conversion factor.

Examples

Convert watts to ergs per second. Print the diagnostic messages:

tt> tunits source.tab power "ergs/sec" old=watts verb+

References

This task was written by Bernie Simon