Description Usage Arguments Details Value Warning Note Author(s) References See Also Examples
Various pems.utils functions for the management of data units.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | 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("special", "input", "data.frame", "pems"),
force = FALSE, overwrite = FALSE, hijack = FALSE)
convertUnits(input = NULL, to = NULL, from = NULL, data = NULL, ...,
if.missing = c("stop", "warning", "return"),
output = c("special", "input", "data.frame", "pems"),
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.
None currently
This set of functions is intended to provide a flexible framework for the routine handling of data units.
Karl Ropkins
References in preparation
None currently
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 | ###########
##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")
#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
# units: "mi/h"
###########
##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)
|
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.