4.4.unit.handlers: data unit handlers
In pems.utils: Portable Emissions (and Other Mobile) Measurement System Utilities
4.4.unit.handlers 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 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.
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
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)
pems.utils documentation built on April 3, 2025, 6:02 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| 4.4.unit.handlers | 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
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)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.