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 secs
We 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 R package, which in turn is build 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 R package udunits2
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.
Existing units are resolved from a database in the units
package, called ud_units
. We can see the first three elements of it by
library(units)
ud_units[1:3]
## $m
## 1 m
##
## $kg
## 1 kg
##
## $s
## 1 s
We can set units to numerical values by set_units
:
(a <- set_units(runif(10), m/s))
## Units: m/s
## [1] 0.1147498 0.6014402 0.3770455 0.8671714 0.9575136 0.8089004 0.3809314
## [8] 0.1090912 0.6669849 0.7163281
the 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.
The units
package comes with a list of over 3000 predefined units,
length(ud_units)
## [1] 3225
We can retrieve a single unit from the ud_units
database by
with(ud_units, km/h)
## 1 km/h
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) <- with(ud_units, km/h)
b
## Units: km/h
## [1] 0.4130992 2.1651847 1.3573639 3.1218172 3.4470488 2.9120415 1.3713530
## [8] 0.3927282 2.4011458 2.5787813
Arithmetic operations verify units, and create new ones
a + a
## Units: m/s
## [1] 0.2294996 1.2028804 0.7540911 1.7343429 1.9150271 1.6178008 0.7618628
## [8] 0.2181823 1.3339699 1.4326563
a * a
## Units: m^2/s^2
## [1] 0.01316751 0.36173030 0.14216333 0.75198631 0.91683221 0.65431988
## [7] 0.14510872 0.01190088 0.44486891 0.51312601
a ^ 2
## Units: m^2/s^2
## [1] 0.01316751 0.36173030 0.14216333 0.75198631 0.91683221 0.65431988
## [7] 0.14510872 0.01190088 0.44486891 0.51312601
a ** -2
## Units: s^2/m^2
## [1] 75.944490 2.764491 7.034163 1.329811 1.090712 1.528304 6.891385
## [8] 84.027380 2.247853 1.948839
and convert to the units of the first argument if necessary:
a + b # m/s + km/h -> m/s
## Units: m/s
## [1] 0.2294996 1.2028804 0.7540911 1.7343429 1.9150271 1.6178008 0.7618628
## [8] 0.2181823 1.3339699 1.4326563
Currently, 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 <- with(ud_units, s)
a * t
## Units: m
## [1] 0.1147498 0.6014402 0.3770455 0.8671714 0.9575136 0.8089004 0.3809314
## [8] 0.1090912 0.6669849 0.7163281
which also work when units need to be converted before they can be simplified:
t <- with(ud_units, min)
a * t
## Units: m
## [1] 6.884987 36.086411 22.622732 52.030287 57.450813 48.534025 22.855883
## [8] 6.545470 40.019096 42.979689
Simplification to unit-less values gives the “1” as unit:
m <- with(ud_units, m)
a * t / m
## Units: 1
## [1] 6.884987 36.086411 22.622732 52.030287 57.450813 48.534025 22.855883
## [8] 6.545470 40.019096 42.979689
Allowed 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.00439 0.12100 0.04740 0.25100 0.30600 0.21800 0.04840 0.00397
## [9] 0.14800 0.17100
cumsum(a)
## Units: m/s
## [1] 0.1147498 0.7161900 1.0932355 1.9604069 2.9179205 3.7268209 4.1077523
## [8] 4.2168435 4.8838284 5.6001565
log(a) # base defaults to exp(1)
## Units: (ln(m/s))
## [1] -2.1650013 -0.5084282 -0.9753893 -0.1425186 -0.0434154 -0.2120795
## [7] -0.9651360 -2.2155713 -0.4049878 -0.3336169
log(a, base = 10)
## Units: (lg(m/s))
## [1] -0.94024813 -0.22080756 -0.42360621 -0.06189503 -0.01885507
## [6] -0.09210494 -0.41915324 -0.96221041 -0.17588397 -0.14488799
log(a, base = 2)
## Units: (lb(m/s))
## [1] -3.12343669 -0.73350683 -1.40718936 -0.20561085 -0.06263518
## [6] -0.30596599 -1.39239693 -3.19639380 -0.58427392 -0.48130747
Summary functions sum
, min
, max
, and range
are allowed:
sum(a)
## 5.600157 m/s
min(a)
## 0.1090912 m/s
max(a)
## 0.9575136 m/s
range(a)
## Units: m/s
## [1] 0.1090912 0.9575136
with(ud_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.1147498 0.6014402 0.3770455 0.8671714 0.9575136 0.8089004 0.3809314
## [8] 0.1090912 0.6669849 0.7163281
a[1]
## 0.1147498 m/s
The usual subsetting rules work:
a[2:5]
## Units: m/s
## [1] 0.6014402 0.3770455 0.8671714 0.9575136
a[-(1:9)]
## 0.7163281 m/s
c(a,a)
## Units: m/s
## [1] 0.1147498 0.6014402 0.3770455 0.8671714 0.9575136 0.8089004 0.3809314
## [8] 0.1090912 0.6669849 0.7163281 0.1147498 0.6014402 0.3770455 0.8671714
## [15] 0.9575136 0.8089004 0.3809314 0.1090912 0.6669849 0.7163281
concatenation converts to the units of the first argument, if necessary:
c(a,b) # m/s, km/h -> m/s
## Units: m/s
## [1] 0.1147498 0.6014402 0.3770455 0.8671714 0.9575136 0.8089004 0.3809314
## [8] 0.1090912 0.6669849 0.7163281 0.1147498 0.6014402 0.3770455 0.8671714
## [15] 0.9575136 0.8089004 0.3809314 0.1090912 0.6669849 0.7163281
c(b,a) # km/h, m/s -> km/h
## Units: km/h
## [1] 0.4130992 2.1651847 1.3573639 3.1218172 3.4470488 2.9120415 1.3713530
## [8] 0.3927282 2.4011458 2.5787813 0.4130992 2.1651847 1.3573639 3.1218172
## [15] 3.4470488 2.9120415 1.3713530 0.3927282 2.4011458 2.5787813
difftime
From difftime
to units
:
t1 = Sys.time()
t2 = t1 + 3600
d = t2 - t1
(du = as.units(d))
## 1 h
vice versa:
(dt = as.dt(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 * 4 * m/s)
## Units: m^2/s^2
## [,1] [,2]
## [1,] 1 3
## [2,] 2 4
but
set_units(matrix(1:4,2,2), m/s) %*% set_units(4:3, m/s)
## [,1]
## [1,] 13
## [2,] 20
strips units.
data.frame
sunits 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, but is not interpreted by R:
(x = 1:10 * make_unit("m2 s-1"))
## Units: (m2 s-1)
## [1] 1 2 3 4 5 6 7 8 9 10
udunits understands such string, and can convert them
y = 1:10 * with(ud_units, m^2/s)
x + y
## Units: (m2 s-1)
## [1] 2 4 6 8 10 12 14 16 18 20
but R cannot simplify them:
x/y
## Units: (m2 s-1)*s/m^2
## [1] 1 1 1 1 1 1 1 1 1 1
Instead, we can tell R to parse such a string, which then allows simplification:
(z = 1:10 * parse_unit("m2 s-1"))
## Units: m^2/s
## [1] 1 2 3 4 5 6 7 8 9 10
z + y
## Units: m^2/s
## [1] 2 4 6 8 10 12 14 16 18 20
z / y
## Units: 1
## [1] 1 1 1 1 1 1 1 1 1 1
Printing units in this form is done by
as_cf(z)
## [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 * ud_units[["in"]]^3
units(displacement) = with(ud_units, cm^3)
weight = mtcars$wt * 1000 * with(ud_units, lb)
units(weight) = with(ud_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 = make_unit("gallon")
consumption = mtcars$mpg * with(ud_units, mi/gallon)
units(consumption) = with(ud_units, km/l)
par(mar = mar)
plot(displacement, consumption) # division in consumption
units_options(negative_power = TRUE) # division becomes ^-1
plot(displacement, consumption) # division in consumption
As 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)