R has little support for physical measurement units. The exception is
formed by time differences: time differences objects of class
difftime have a units attribute that can be
modified:
t1 = Sys.time()
t2 = t1 + 3600
d = t2 - t1
class(d)
## [1] "difftime"
units(d)
## [1] "hours"
d
## Time difference of 1 hours
units(d) = "secs"
d
## Time difference of 3600 secsWe see here that the units method is used to retrieve
and modify the unit of time differences.
The units package generalizes this idea to other
physical units, building upon the udunits2 C
library. The udunits2 library provides the following
operations:
m/s is a
valid physical unitm/s and
km/h are convertibleThe units R package uses the udunits2 C
library to extend R with functionality for manipulating numeric vectors
that have physical measurement units associated with them, in a similar
way as difftime objects behave.
We can set units to numerical values by set_units:
library(units)
(a <- set_units(runif(10), m/s))
## Units: [m/s]
## [1] 0.52259468 0.20063396 0.79467267 0.33072156 0.39870312 0.03588982
## [7] 0.72273395 0.13527465 0.16599681 0.13370071the result, e.g.
set_units(10, m/s)
## 10 [m/s]literally means “10 times 1 m divided by 1 s”. In writing, the “1” values are omitted, and the multiplication is implicit.
When conversion is meaningful, such as hours to seconds or meters to kilometers, conversion can be done explicitly by setting the units of a vector
b = a
units(b) <- make_units(km/h)
b
## Units: [km/h]
## [1] 1.8813408 0.7222823 2.8608216 1.1905976 1.4353312 0.1292033 2.6018422
## [8] 0.4869887 0.5975885 0.4813225Arithmetic operations verify units, and create new ones
a + a
## Units: [m/s]
## [1] 1.04518936 0.40126792 1.58934534 0.66144311 0.79740624 0.07177963
## [7] 1.44546791 0.27054930 0.33199362 0.26740142
a * a
## Units: [m^2/s^2]
## [1] 0.273105197 0.040253986 0.631504655 0.109376747 0.158964177 0.001288079
## [7] 0.522344368 0.018299232 0.027554941 0.017875879
a ^ 2
## Units: [m^2/s^2]
## [1] 0.273105197 0.040253986 0.631504655 0.109376747 0.158964177 0.001288079
## [7] 0.522344368 0.018299232 0.027554941 0.017875879
a ** -2
## Units: [s^2/m^2]
## [1] 3.661593 24.842260 1.583520 9.142711 6.290725 776.349983
## [7] 1.914446 54.647103 36.291132 55.941304and convert to the units of the first argument if necessary:
a + b # m/s + km/h -> m/s
## Units: [m/s]
## [1] 1.04518936 0.40126792 1.58934534 0.66144311 0.79740624 0.07177963
## [7] 1.44546791 0.27054930 0.33199362 0.26740142Currently, powers are only supported for integer powers, so using
a ** 2.5 would result in an error.
There are some basic simplification of units:
t <- make_units(s)
a * t
## Units: [m]
## [1] 0.52259468 0.20063396 0.79467267 0.33072156 0.39870312 0.03588982
## [7] 0.72273395 0.13527465 0.16599681 0.13370071which also work when units need to be converted before they can be simplified:
t <- make_units(min)
a * t
## Units: [m]
## [1] 31.355681 12.038038 47.680360 19.843293 23.922187 2.153389 43.364037
## [8] 8.116479 9.959809 8.022042Simplification to unit-less values gives the “1” as unit:
m <- make_units(m)
a * t / m
## Units: [1]
## [1] 31.355681 12.038038 47.680360 19.843293 23.922187 2.153389 43.364037
## [8] 8.116479 9.959809 8.022042Allowed operations that require convertible units are +,
-, ==, !=, <,
>, <=, >=. Operations
that lead to new units are *, /, and the power
operations ** and ^.
Mathematical operations allowed are: abs,
sign, floor, ceiling,
trunc, round, signif,
log, cumsum, cummax,
cummin.
signif(a ** 2 / 3, 3)
## Units: [m^2/s^2]
## [1] 0.091000 0.013400 0.211000 0.036500 0.053000 0.000429 0.174000 0.006100
## [9] 0.009180 0.005960
cumsum(a)
## Units: [m/s]
## [1] 0.5225947 0.7232286 1.5179013 1.8486229 2.2473260 2.2832158 3.0059498
## [8] 3.1412244 3.3072212 3.4409219
log(a) # base defaults to exp(1)
## Units: [(ln(re 1 m.s-1))]
## [1] -0.6489491 -1.6062731 -0.2298250 -1.1064785 -0.9195382 -3.3273017
## [7] -0.3247141 -2.0004481 -1.7957867 -2.0121515
log(a, base = 10)
## Units: [(lg(re 1 m.s-1))]
## [1] -0.28183502 -0.69759555 -0.09981172 -0.48053750 -0.39935037 -1.44502877
## [7] -0.14102154 -0.86878357 -0.77990026 -0.87386629
log(a, base = 2)
## Units: [(lb(re 1 m.s-1))]
## [1] -0.9362357 -2.3173623 -0.3315674 -1.5963110 -1.3266132 -4.8002817
## [7] -0.4684634 -2.8860366 -2.5907726 -2.9029210Summary functions sum, min,
max, and range are allowed:
sum(a)
## 3.440922 [m/s]
min(a)
## 0.03588982 [m/s]
max(a)
## 0.7946727 [m/s]
range(a)
## Units: [m/s]
## [1] 0.03588982 0.79467267
make_units(min(m/s, km/h)) # converts to first unit:
## 0.2777778 [m/s]Following difftime, printing behaves differently for
length-one vectors:
a
## Units: [m/s]
## [1] 0.52259468 0.20063396 0.79467267 0.33072156 0.39870312 0.03588982
## [7] 0.72273395 0.13527465 0.16599681 0.13370071
a[1]
## 0.5225947 [m/s]The usual subsetting rules work:
a[2:5]
## Units: [m/s]
## [1] 0.2006340 0.7946727 0.3307216 0.3987031
a[-(1:9)]
## 0.1337007 [m/s]c(a,a)
## Units: [m/s]
## [1] 0.52259468 0.20063396 0.79467267 0.33072156 0.39870312 0.03588982
## [7] 0.72273395 0.13527465 0.16599681 0.13370071 0.52259468 0.20063396
## [13] 0.79467267 0.33072156 0.39870312 0.03588982 0.72273395 0.13527465
## [19] 0.16599681 0.13370071concatenation converts to the units of the first argument, if necessary:
c(a,b) # m/s, km/h -> m/s
## Units: [m/s]
## [1] 0.52259468 0.20063396 0.79467267 0.33072156 0.39870312 0.03588982
## [7] 0.72273395 0.13527465 0.16599681 0.13370071 0.52259468 0.20063396
## [13] 0.79467267 0.33072156 0.39870312 0.03588982 0.72273395 0.13527465
## [19] 0.16599681 0.13370071
c(b,a) # km/h, m/s -> km/h
## Units: [km/h]
## [1] 1.8813408 0.7222823 2.8608216 1.1905976 1.4353312 0.1292033 2.6018422
## [8] 0.4869887 0.5975885 0.4813225 1.8813408 0.7222823 2.8608216 1.1905976
## [15] 1.4353312 0.1292033 2.6018422 0.4869887 0.5975885 0.4813225difftimeFrom difftime to units:
t1 = Sys.time()
t2 = t1 + 3600
d = t2 - t1
(du = as_units(d))
## 1 [h]vice versa:
(dt = as_difftime(du))
## Time difference of 1 hours
class(dt)
## [1] "difftime"matrix objectsset_units(matrix(1:4,2,2), m/s)
## Units: [m/s]
## [,1] [,2]
## [1,] 1 3
## [2,] 2 4
set_units(matrix(1:4,2,2), m/s * m/s)
## Units: [m^2/s^2]
## [,1] [,2]
## [1,] 1 3
## [2,] 2 4but
set_units(matrix(1:4,2,2), m/s) %*% set_units(4:3, m/s)
## [,1]
## [1,] 13
## [2,] 20strips units.
data.framesunits in data.frame objects are printed, but do not
appear in summary:.
set.seed(131)
d <- data.frame(x = runif(4),
y = set_units(runif(4), s),
z = set_units(1:4, m/s))
d
## x y z
## 1 0.2064370 0.8463468 [s] 1 [m/s]
## 2 0.1249422 0.5292048 [s] 2 [m/s]
## 3 0.2932732 0.5186254 [s] 3 [m/s]
## 4 0.3757797 0.2378545 [s] 4 [m/s]
summary(d)
## x y z
## Min. :0.1249 Min. :0.2379 Min. :1.00
## 1st Qu.:0.1861 1st Qu.:0.4484 1st Qu.:1.75
## Median :0.2499 Median :0.5239 Median :2.50
## Mean :0.2501 Mean :0.5330 Mean :2.50
## 3rd Qu.:0.3139 3rd Qu.:0.6085 3rd Qu.:3.25
## Max. :0.3758 Max. :0.8463 Max. :4.00
d$yz = with(d, y * z)
d
## x y z yz
## 1 0.2064370 0.8463468 [s] 1 [m/s] 0.8463468 [m]
## 2 0.1249422 0.5292048 [s] 2 [m/s] 1.0584095 [m]
## 3 0.2932732 0.5186254 [s] 3 [m/s] 1.5558761 [m]
## 4 0.3757797 0.2378545 [s] 4 [m/s] 0.9514180 [m]
d[1, "yz"]
## 0.8463468 [m]Units are often written in the form m2 s-1, for square
meter per second. This can be defined as unit, and also parsed by
as_units:
(x = 1:10 * as_units("m2 s-1"))
## Units: [m^2/s]
## [1] 1 2 3 4 5 6 7 8 9 10udunits understands such string, and can convert them
y = 1:10 * make_units(m^2/s)
x + y
## Units: [m^2/s]
## [1] 2 4 6 8 10 12 14 16 18 20Printing units in this form is done by
deparse_unit(x)
## [1] "m2 s-1"Base scatter plots and histograms support automatic unit placement in
axis labels. In the following example we first convert to SI units.
(Unit in needs a bit special treatment, because
in is a reserved word in R.)
mar = par("mar") + c(0, .3, 0, 0)
displacement = mtcars$disp * as_units("in")^3
units(displacement) = make_units(cm^3)
weight = mtcars$wt * 1000 * make_units(lb)
units(weight) = make_units(kg)
par(mar = mar)
plot(weight, displacement)We can change grouping symbols from [ ] into
( ):
units_options(group = c("(", ")") ) # parenthesis instead of square brackets
par(mar = mar)
plot(weight, displacement)We can also remove grouping symbols, increase space between variable name and unit by:
units_options(sep = c("~~~", "~"), group = c("", "")) # no brackets; extra space
par(mar = mar)
plot(weight, displacement)More complex units can be plotted either with negative powers, or as
divisions, by modifying one of units’s global options using
units_options:
gallon = as_units("gallon")
consumption = mtcars$mpg * make_units(mi/gallon)
units(consumption) = make_units(km/l)
par(mar = mar)
plot(displacement, consumption) # division in consumptionunits_options(negative_power = TRUE) # division becomes ^-1
plot(displacement, consumption) # division in consumptionAs usual, units modify automatically in expressions:
units_options(negative_power = TRUE) # division becomes ^-1
par(mar = mar)
plot(displacement, consumption)plot(1/displacement, 1/consumption)