| 4.4.unit.handlers {pems.utils} | R Documentation |
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)
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 |
units, to, from, ref, alias, tag |
(Character vectors). Unit ids. |
... |
(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: |
output |
(Character vector) Output mode for function results. Options currently include: |
force |
(Logical) Should a unit change to attempted even if checking indicates a mismatch, e.g. an attempt to
set the units of an |
overwrite |
(Logical) If 'same name' cases are encountered when packing/repacking an |
unit.conversions |
(Optional list) If supplied, |
conversion |
(Numeric or function) When adding or updating a conversion method using |
verbose |
(Logical) For |
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.
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.
Note
This set of functions is intended to provide a flexible framework for the routine handling of data units.
Author(s)
Karl Ropkins
References
References in preparation
See Also
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)