2.2.unit.handlers {pems.utils} | R Documentation |
Various pems.utils functions for the management of data units.
getUnits(input = NULL, data = NULL, ..., if.missing = c("stop", "warning", "return"), hijack = FALSE) setUnits(input = NULL, units = NULL, data = NULL, ..., if.missing = c("stop", "warning", "return"), output = c("input", "data.frame", "pems", "special"), force = FALSE, overwrite = FALSE, hijack = 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, hijack = 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)
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: |
hijack |
(Logical) The argument |
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 |
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.
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.
This set of functions is intended to provide a flexible framework for the routine handling of data units.
Karl Ropkins
References in preparation
########### ##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)