pems.utils (version 0.3.0.7)

4.4.unit.handlers: data unit handlers

Description

Various pems.utils functions for the management of data units.

Usage

getUnits(input = NULL, data = NULL, ..., 
         if.missing = c("stop", "warning", "return"))
setUnits(input = NULL, units = NULL, data = NULL, ..., 
         if.missing = c("stop", "warning", "return"), 
         output = c("input", "data.frame", "pems", "special"),
         force = FALSE, overwrite = FALSE)
convertUnits(input = NULL, to = NULL, from = NULL, data = NULL, ..., 
         if.missing = c("stop", "warning", "return"), 
         output = c("input", "data.frame", "pems", "special"), 
         unit.conversions = NULL, force = FALSE, overwrite = FALSE)
#local unit.conversion method handling 
addUnitConversion(to = NULL, from = NULL, conversion = NULL, 
         tag = "undocumented",
         unit.conversions = ref.unit.conversions, ...,
         overwrite = FALSE)
addUnitAlias(ref = NULL, alias = NULL, 
         unit.conversions = ref.unit.conversions, ...)
listUnitConversions(unit.conversions = ref.unit.conversions, ...,
         verbose = FALSE, to = NULL, from = NULL)

Value

getUnits returns the units of an input as a character vector if available, else it returns NULL.

setUnits sets the units of an input to a supplied value, units, if they have not already be set or if force = TRUE. The result is returned as the modified input alone, the modified input as an element in a data.frame, or the modifed input as an element in a pems object (depending on output setting). If either a

data.frame or pems object is supplied as data, this is used as the target when repacking the output. (Note: output = "special" is a special case which allows the function to select the output mode based on the type of data supplied.

convertUnits converts the units of an input. Typically, this is done by setting the required new units, using to, and letting the function select a suitable conversion method. However, conversions can be forced by setting from and force = TRUE to apply a specifc

to/from method to an input regardless of the actual units of input. As with setUnits, results can be output as input, data.frame or pems

objects.

addUnitConversion returns a supplied unit conversion look-up table (or in its absence the reference

ref.unit.conversions) subject to the requested addition or update. Note: modifications that change exist information require the extra argument overwrite = TRUE as confirmation.

addUnitAlias returns a supplied unit conversion look-up table (or in its absence the reference

ref.unit.conversions) subject to the requested alias addition.

listUnitConversions returns summary descriptions of methods in the supplied unit conversion look-up table (or in its absence the reference ref.unit.conversions). Additional arguments, to and

from, can be used to select unit conversions of particular relevance.

Arguments

input

(vector, object or object element) An input, e.g. a vector of speed measurements.

data

(data.frame, pems object) If supplied, the assumed source for an input. This can currently be a standard data.frame or a 'pems' object. Note: if an input is not found in data, the parent environment is then also checked before returning an error message.

units, to, from, ref, alias, tag

(Character vectors). Unit ids. units sets the units of input in setUnits. to sets the units to convert input to when using convertUnits. The additional arguments from can be used to apply unit conversions to inputs with un-defined or mismatched units, but requires the extra argument force = TRUE to confirm action. When working with local unit conversions to and from should be used to identify specific conversions, e.g. when using addUnitConversion to add a new unit conversion method, and ref and alias should be used to identify a current unit id and new alias, respectively, when using addUnitAlias. tag is an optional more detailed conversion description, intended for use in method documentation. (See Below for further details.)

...

(Optional) Other arguments, currently ignored.

if.missing

(Optional character vector) What the function should do if things do not go as expected. Current options include: "stop" to stop the function with an error message; "warning" to warn users that expected information was missing but to continue running the parent code; or "return" to continue running the parent code without any warnings.

output

(Character vector) Output mode for function results. Options currently include: special, input, data.frame, and pems. See force, overwrite and Values below for further details.

force

(Logical) Should a unit change to attempted even if checking indicates a mismatch, e.g. an attempt to set the units of an input that already has units assigned.

overwrite

(Logical) If 'same name' cases are encountered when packing/repacking an output into a data.frame or pems object, should the function overwrite the case in the target data.frame or pems object with the modified input? (If FALSE, a new element is generated with a unique name in the form [input.name].number.)

unit.conversions

(Optional list) If supplied, unit.conversions is a 'look up' table for unit conversion methods. By default, functions in pems.utils use the reference ref.unit.conversions, but this can be copied to the workspace and updated to provide the user with a means of updating and expanding the method set.

conversion

(Numeric or function) When adding or updating a conversion method using addUnitConversion, the conversion method. This can be a numeric, in which case it is assumed to be a multiplication factor (and converted to a function in the form function(x) x * conversion) or a function to be applied directly to an input.

verbose

(Logical) For listUnitConversions. Should unit.conversions be reported in detail? By default (verbose = FALSE) only unit conversion tags are reported.

Author

Karl Ropkins

Details

getUnits returns the units of an input.

setUnits sets/resets the units of an input.

convertUnits converts the units of an input.

addUnitConversion adds a conversion method to a local version of the unit conversion look-up table. Methods should be supplied as to and from unit ids and an associated conversion. A tag can also be supplied to provide a more detailed description of the conversion for use in documentation.

addUnitAlias adds an alias for an existing unit id in a local version of the unit conversion look-up table. The existing unit id should be identified using ref and the new alias should be assinged using alias. The alias is added to all to and from elements containing ref to allow users to work with alternative unit abbreviations.

listUnitConversions lists the methods a supplied unit conversion look-up table. If to and/or from arguments are also supplied, these are used to subsample relevant methods.

References

References in preparation

See Also

pems.element

Examples

###########
##example 1 
###########

#work with data units

#getting units (where assigned)
getUnits(velocity, pems.1) #km/h

#setting units
a <- 1:10
a <- setUnits(a, "km/h") #add unit 

#alternaltive 
#using pems.element
#a <- pems.element(a, units="km/h", name = "a") 

#changing units
convertUnits(a, "mi/h")

# [1] 0.6213712 1.2427424 1.8641136 2.4854848 3.1068560 3.7282272 4.3495983
# [8] 4.9709695 5.5923407 6.2137119
# pems.element; [unnamed] [mi/h] [n = 10]

###########
##example 2
###########

#working with local unit conversions
#adding/updating unit conversion methods

#make a local reference
ref.list <- ref.unit.conversions 

#add a miles/hour alias to mi/h
ref.list <- addUnitAlias("mi/h", "miles/hour", ref.list)

#add a new conversion
ref.list <- addUnitConversion(to = "silly", from = "km/h", 
                              conversion = function(x) 12 + (21 * x), 
                              tag = "kilometers/hour to some silly scale",
                              unit.conversions = ref.list)

#use these
convertUnits(a, "miles/hour", unit.conversions = ref.list)

# [1] 0.6213712 1.2427424 1.8641136 2.4854848 3.1068560 3.7282272 4.3495983
# [8] 4.9709695 5.5923407 6.2137119
# units: "miles/hour" (as above but using your unit abbreviations)

convertUnits(a, "silly", unit.conversions = ref.list)

# [1]  33  54  75  96 117 138 159 180 201 222
# units: "silly" (well, you get what you ask for)