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)
##  "difftime"
units(d)
##  "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:

• validating whether an expression, such as m/s is a valid physical unit
• verifying whether two units such as m/s and km/h are convertible
• converting values between two convertible units
• providing names and symbols for specific units
• handle different character encodings (utf8, ascii, iso-8859-1 and latin1)

The 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.

## Setting units, unit conversion

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] ##  0.4658085 0.2798466 0.1314922 0.4313912 0.4569852 0.8772569 0.2930929 ##  0.8782099 0.2897836 0.6193869 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) ##  3248 We can retrieve a single unit from the ud_units database by with(ud_units, km/h) ## 1 [km/h] ### Unit conversion 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.6769106 1.0074476 0.4733718 1.5530083 1.6451466 3.1581249 1.0551343 ##  3.1615555 1.0432208 2.2297930 ## Basic manipulations ### Arithmetic operations Arithmetic operations verify units, and create new ones a + a ## Units: [m/s] ##  0.9316170 0.5596931 0.2629844 0.8627824 0.9139704 1.7545138 0.5861857 ##  1.7564197 0.5795671 1.2387739 a * a ## Units: [m^2/s^2] ##  0.21697755 0.07831409 0.01729019 0.18609836 0.20883545 0.76957971 ##  0.08590343 0.77125255 0.08397451 0.38364017 a ^ 2 ## Units: [m^2/s^2] ##  0.21697755 0.07831409 0.01729019 0.18609836 0.20883545 0.76957971 ##  0.08590343 0.77125255 0.08397451 0.38364017 a ** -2 ## Units: [s^2/m^2] ##  4.608772 12.769094 57.836256 5.373502 4.788459 1.299411 11.640979 ##  1.296592 11.908375 2.606609 and convert to the units of the first argument if necessary: a + b # m/s + km/h -> m/s ## Units: [m/s] ##  0.9316170 0.5596931 0.2629844 0.8627824 0.9139704 1.7545138 0.5861857 ##  1.7564197 0.5795671 1.2387739 Currently, powers are only supported for integer powers, so using a ** 2.5 would result in an error. ### Unit simplification There are some basic simplification of units: t <- with(ud_units, s) a * t ## Units: [m] ##  0.4658085 0.2798466 0.1314922 0.4313912 0.4569852 0.8772569 0.2930929 ##  0.8782099 0.2897836 0.6193869 which also work when units need to be converted before they can be simplified: t <- with(ud_units, min) a * t ## Units: [m] ##  27.948509 16.790793 7.889531 25.883472 27.419111 52.635415 17.585572 ##  52.692591 17.387014 37.163216 Simplification to unit-less values gives the “1” as unit: m <- with(ud_units, m) a * t / m ## Units:  ##  27.948509 16.790793 7.889531 25.883472 27.419111 52.635415 17.585572 ##  52.692591 17.387014 37.163216 Allowed operations that require convertible units are +, -, ==, !=, <, >, <=, >=. Operations that lead to new units are *, /, and the power operations ** and ^. ### Mathematical functions 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] ##  0.07230 0.02610 0.00576 0.06200 0.06960 0.25700 0.02860 0.25700 0.02800 ##  0.12800 cumsum(a) ## Units: [m/s] ##  0.4658085 0.7456550 0.8771472 1.3085384 1.7655236 2.6427805 2.9358734 ##  3.8140832 4.1038668 4.7232537 log(a) # base defaults to exp(1) ## Units: [(ln(re 1 m.s-1))] ##  -0.7639807 -1.2735138 -2.0288079 -0.8407400 -0.7831043 -0.1309554 ##  -1.2272658 -0.1298697 -1.2386210 -0.4790251 log(a, base = 10) ## Units: [(lg(re 1 m.s-1))] ##  -0.33179260 -0.55308003 -0.88110008 -0.36512872 -0.34009789 -0.05687320 ##  -0.53299475 -0.05640169 -0.53792626 -0.20803796 log(a, base = 2) ## Units: [(lb(re 1 m.s-1))] ##  -1.1021912 -1.8372921 -2.9269511 -1.2129314 -1.1297807 -0.1889287 ##  -1.7705702 -0.1873624 -1.7869523 -0.6910871 ### Summary functions Summary functions sum, min, max, and range are allowed: sum(a) ## 4.723254 [m/s] min(a) ## 0.1314922 [m/s] max(a) ## 0.8782099 [m/s] range(a) ## Units: [m/s] ##  0.1314922 0.8782099 with(ud_units, min(m/s, km/h)) # converts to first unit: ## 0.2777778 [m/s] ### Printing Following difftime, printing behaves differently for length-one vectors: a ## Units: [m/s] ##  0.4658085 0.2798466 0.1314922 0.4313912 0.4569852 0.8772569 0.2930929 ##  0.8782099 0.2897836 0.6193869 a ## 0.4658085 [m/s] ### Subsetting The usual subsetting rules work: a[2:5] ## Units: [m/s] ##  0.2798466 0.1314922 0.4313912 0.4569852 a[-(1:9)] ## 0.6193869 [m/s] ### Concatenation c(a,a) ## Units: [m/s] ##  0.4658085 0.2798466 0.1314922 0.4313912 0.4569852 0.8772569 0.2930929 ##  0.8782099 0.2897836 0.6193869 0.4658085 0.2798466 0.1314922 0.4313912 ##  0.4569852 0.8772569 0.2930929 0.8782099 0.2897836 0.6193869 concatenation converts to the units of the first argument, if necessary: c(a,b) # m/s, km/h -> m/s ## Units: [m/s] ##  0.4658085 0.2798466 0.1314922 0.4313912 0.4569852 0.8772569 0.2930929 ##  0.8782099 0.2897836 0.6193869 0.4658085 0.2798466 0.1314922 0.4313912 ##  0.4569852 0.8772569 0.2930929 0.8782099 0.2897836 0.6193869 c(b,a) # km/h, m/s -> km/h ## Units: [km/h] ##  1.6769106 1.0074476 0.4733718 1.5530083 1.6451466 3.1581249 1.0551343 ##  3.1615555 1.0432208 2.2297930 1.6769106 1.0074476 0.4733718 1.5530083 ##  1.6451466 3.1581249 1.0551343 3.1615555 1.0432208 2.2297930 ## Conversion to/from difftime From 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) ##  "difftime" ## units in matrix objects set_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 4 but set_units(matrix(1:4,2,2), m/s) %*% set_units(4:3, m/s) ## [,1] ## [1,] 13 ## [2,] 20 strips units. ## units objects in data.frames units 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]

## formatting

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  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: [m^2/s]
##    2  4  6  8 10 12 14 16 18 20

Printing units in this form is done by

deparse_unit(x)
##  "m2 s-1"

## plotting

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 = as_units("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) 