This vignette is identical to Pebesma, Mailund, and Hiebert (2016), except for two changes:
We briefly review SI units, and discuss R packages that deal with measurement units, their compatibility and conversion. Built upon the UNIDATA udunits library, we introduce the package units that provides a class for maintaining unit metadata. When used in expression, it automatically converts units, and simplifies units of results when possible; in case of incompatible units, errors are raised. The class flexibly allows expansion beyond predefined units. Using units may eliminate a whole class of potential scientific programming mistakes. We discuss the potential and limitations of computing with explicit units.
Two quotes from Cobb and Moore (1997) – Data are
not just numbers, they are numbers with a context and in data
analysis, context provides meaning – illustrate that for a data
analysis to be meaningful, knowledge of the data’s context is needed.
Pragmatic aspects of this context include who collected or generated the
data, how this was done, and for which purpose (Scheider
et al. 2016); semantic aspects concern what the data
represents: which aspect of the world do the data refer to, when and
where were they measured, and what a value of
R does allow for keeping some context with data, for instance
data.framecolumns must have and
listelements may have names that can be used to describe context, using freetext
arrayobjects may have
levelsmay indicate, using freetext, the categories of nominal or ordinal variables
Dateobjects specify how numbers should be interpreted as time or date, with fixed units (second and day, respectively) and origin (Jan 1, 1970, 00:00 UTC)
difftimeobjects specify how time duration can be represented by numbers, with flexible units (secs, mins, hours, days, weeks); lubridate (Grolemund and Wickham 2011) extends some of this functionality.
Furthermore, if spatial objects as defined in package sp (Pebesma and Bivand 2005) have a proper coordinate reference system set, they can be transformed to other datums, or converted to various flat (projected) representations of the Earth (Iliffe and Lott 2008).
In many cases however, R drops contextual information. As an example,
we look at annual global land-ocean temperature index (from
temp_data = subset(read.table("647_Global_Temperature_Data_File.txt", header=TRUE)[1:2], Year >= 1960) temp_data$date = as.Date(paste0(temp_data$Year, "-01-01")) temp_data$time = as.POSIXct(temp_data$date) Sys.setenv(TZ="UTC") head(temp_data, 3) ## Year Annual_Mean date time ## 81 1960 -0.03 1960-01-01 1960-01-01 ## 82 1961 0.05 1961-01-01 1961-01-01 ## 83 1962 0.02 1962-01-01 1962-01-01 year_duration = diff(temp_data$date) mean(year_duration) ## Time difference of 365.2545 days
Here, the time difference units are reported for the
year_duration, but if we would
use it in a linear algebra operation
year_duration %*% rep(1, length(year_duration)) / length(year_duration) ## [,1] ## [1,] 365.2545
the unit is dropped. Similarly, for linear regression coefficients we see
coef(lm(Annual_Mean ~ date, temp_data)) ## (Intercept) date ## 1.833671e-02 4.364763e-05 coef(lm(Annual_Mean ~ time, temp_data)) ## (Intercept) time ## 1.833671e-02 5.051809e-10
where the unit of change is in degrees Celsius but either per
date) or per second (
For purely mathematical manipulations, R often strips context from
numbers when it is carried in attributes, the linear algebra routines
being a prime example.
Most variables are somehow attributed with information about their
units, which specify what the value
1 of this
variable represents. This may be counts of something,
1 apple, but it may also refer to some physical
unit, such as distance in meter. This article discusses how strong
unit support can be introduced in R.
The BIPM (Bureau International des Poids et Mesures) is “the intergovernmental organization through which Member States act together on matters related to measurement science and measurement standards. Its recommended practical system of units of measurement is the International System of Units (Système International d’Unités, with the international abbreviation SI) (https://www.bipm.org/en/measurement-units/)”.
International Bureau of Weights and Measures, Taylor, and Thompson (2001) describe the SI units, where, briefly, SI units
kg; as a base unit, kg can be part of coherent derived units); an example of a coherent derived unit is 1 watt = 1 joule per 1 second,
base quantities, SI units and their symbols (from International Bureau of Weights and Measures, Taylor, and Thompson (2001), p. 23):
|Base quantity||SI base unit|
|electric current||\(I, i\)||ampere||A|
|amount of substance||\(n\)||mole||mol|
Udunits, developed by UCAR/UNIDATA, advertises itself on its web page as: “The udunits package supports units of physical quantities. Its C library provides for arithmetic manipulation of units and for conversion of numeric values between compatible units. The package contains an extensive unit database, which is in XML format and user-extendable.”
Unlike the measurements and NISTunits, the underlying udunits2 C library parses units as expressions, and bases its logic upon the convertibility of expressions, rather than the comparison of fixed strings:
m100_a = paste(rep("m", 100), collapse = "*") dm100_b = "dm^100" units::ud_are_convertible(m100_a, dm100_b) ##  TRUE
This has the advantage that through complex computations, intermediate objects can have units that are arbitrarily complex, and that can potentially be simplified later on. It also means that the package practically supports an unlimited amount of derived units.
Another set of encodings for measurement units is the Unified Code for Units of Measure (UCUM, Schadow and McDonald (2009)). A dedicated web site describes the details of the differences between udunits and UCUM, and provides a conversion service between the two encoding sets.
The UCUM website refers to some Java implementations, but some of the links seem to be dead. UCUM is the preferred encoding for standards from the Open Geospatial Consortium. udunits on the other hand is the units standard of choice by the climate science community, and is adopted by the CF (Climate and Forecast) conventions, which mostly uses NetCDF. NetCDF (Rew and Davis 1990) is a binary data format that is widely used for atmospheric and climate model predictions.
The udunits library is a C library that has strong support from UNIDATA, and we decided to build our developments on this, rather than on Java implementations of UCUM with a less clear provenance.
units objects from scratch, e.g. where
library(units) ## udunits database from /usr/share/xml/udunits/udunits2.xml x = set_units(1:5, m/s) str(x) ## Units: [m/s] int [1:5] 1 2 3 4 5
represents speed values in
m/s. The units
s are resolved from the udunits2 C library (but could
be user-defined units).
Units can be used in arbitrary R expressions like
set_units(1:3, m/s^2) ## Units: [m/s^2] ##  1 2 3
Several manipulations with
units objects will now be
illustrated. Manipulations that do not involve unit conversion are for
x = set_units(1:3, m/s) x + 2 * x ## Units: [m/s] ##  3 6 9
Explicit unit conversion is done by assigning new units:
(x = set_units(x, cm/s)) ## Units: [cm/s] ##  100 200 300 as.numeric(x) ##  100 200 300
similar to the behaviour of
difftime objects, this
modifies the numeric values without modifying their meaning (what the
numbers refer to).
When mixing units in sums, comparisons or concatenation, units are automatically converted to those of the first argument:
y = set_units(1:3, km/h) x + y ## Units: [cm/s] ##  127.7778 255.5556 383.3333 y + x ## Units: [km/h] ##  4.6 9.2 13.8 x == y ##  FALSE FALSE FALSE c(y, x) ## Units: [km/h] ##  1.0 2.0 3.0 3.6 7.2 10.8
c(y, x) concatenates
x after converting
x to the units of
y. Derived units are created where appropriate:
x * y ## Units: [cm*km/h/s] ##  100 400 900 x^3 ## Units: [cm^3/s^3] ##  1.0e+06 8.0e+06 2.7e+07
and meaningful error messages appear when units are not compatible:
e = try(z <- x + x * y) ## Error : cannot convert cm*km/h/s into cm/s attr(e, "condition")[] ##  "cannot convert cm*km/h/s into cm/s"
The full set of methods and method groups for
objects is shown by
methods(class = "units") ##  Math Ops Summary [ [<- ##  [[ [[<- all.equal anyDuplicated as.Date ##  as.POSIXct as.data.frame as.list as_units boxplot ##  c diff drop_units duplicated format ##  hist log10 log2 mean median ##  mixed_units plot print quantile rep ##  seq set_units str summary unique ##  units units<- weighted.mean ## see '?methods' for accessing help and source code
where the method groups
Opsinclude operations that require compatible units, converting when necessary (
>=), and operations that create new units (
range, and all convert to the unit of the first argument.
When possible, new units are simplified:
a = set_units(1:10, m/s) b = set_units(1:10, h) a * b ## Units: [m] ##  3600 14400 32400 57600 90000 129600 176400 230400 291600 360000 ustr1 = paste(rep("m", 101), collapse = "*") ustr2 = "dm^100" as_units(ustr1) / as_units(ustr2) ## 1e+100 [m]
Units are printed as simple R expressions, e.g.
set_units(1, m^5/s^4) ## 1 [m^5/s^4]
Another way to print units commonly seen in Climate and Forecast
m2 s-1 for m\(^2\)/s. These are not R expressions, but
they can be parsed by
as_units, and created by
as_units("m2 s-1") ## 1 [m^2/s] deparse_unit(set_units(1, m^2*s^-1)) ##  "m2 s-1"
hist methods add units to
default axis labels, an example is shown in the following figures. For
(Wickham 2009), automatic unit placement
in default axis label is also provided;
library(units) units_options(negative_power = TRUE) # initialize variables with units: mtcars$consumption = set_units(mtcars$mpg, mi/gallon) # "in" is also a reserved R keyword, and so needs back-quotes: mtcars$displacement = set_units(mtcars$disp, `in`^3) # convert to SI: mtcars$consumption = set_units(mtcars$consumption, km/l) mtcars$displacement = set_units(mtcars$displacement, cm^3) par(mar = par("mar") + c(0, .3, 0, 0)) with(mtcars, plot(1/displacement, 1/consumption))
library(ggplot2) ggplot(mtcars) + geom_point(aes(x = 1/displacement, y = 1/consumption))
Automatic conversion between
difftime is provided:
(dt = diff(Sys.time() + c(0, 1, 1+60, 1+60+3600))) # class difftime ## Time differences in secs ##  1 60 3600 (dt.u = as_units(dt)) ## Units: [s] ##  1 60 3600 identical(as_difftime(dt.u), dt) ##  TRUE
as well as to and from
(t1 <- as_units(as.POSIXct("2017-08-20 17:03:00"))) ## 1503248580 [(seconds since 1970-01-01 00:00:00 +00:00)] (t2 <- as_units(as.POSIXct("2017-08-20 17:03:00"), "hours since 2017-08-20")) ## 17.05 [(hours since 2017-08-20)] (d1 <- as_units(as.Date("2017-08-20"))) ## 17398 [(days since 1970-01-01)] as.POSIXct(t1) ##  "2017-08-20 17:03:00 UTC" as.Date(d1) ##  "2017-08-20"
Objects of class
units can be used as columns in
data.frame objects, as well as in
Francois, and Müller 2016). They can also be
array, with the constraint that a
single unit holds for all elements.
The units R
package provides a new class,
units, for numeric data with
associated measurement units. Operations on objects of this class retain
the unit metadata and provide automated dimensional analysis: dimensions
are taken into consideration in computations and comparisons. Combining
different units that are compatible triggers automatic unit conversion,
derived units are automatically generated and simplified where possible,
and meaningful error messages are given when a user tries to add objects
with incompatible units. This verifies that computations are not only
syntactically and numerically allowed, but also semantically, and in the
case of physical units, physically allowed, which may support code
verification and provenance tracking. Using this package may eliminate a
whole class of potential scientific programming mistakes.
Where the R packages measurements and NISTunits provide conversion between a fixed number of units, with the help of the udunits2 C library and unit database, R package units handles arbitrarily complex derived units. By treating units as expressions it can derive, convert and simplify units. In addition, beyond the SI units packaged, units handles user-defined units.
units vectors can be stored as columns in
tbl_df objects, and can be
converted to and from
objects have associated time and location information, they could be
stored in spatial or spatio-temporal objects provided by sp or spacetime (Pebesma
2012) as these store attribute data in
data.frame slots, but for instance not in
and Grothendieck 2005) or
xts (Ryan and
Ulrich 2014) objects, as these latter two set the class
attribute of a vector or matrix.
Despite all standardization efforts, units may still be ambiguous, or
subject to interpretation. For instance for the duration of one year NISTunits gives
us an answer that depends on whether we want a common, leap, Gregorian,
Julian, tropical or siderial year (Lang (2006), see also
demo(year)). This illustrates that those who apply unit
conversion should be aware of possible pitfalls. Support for calendars
in udunits seems not as well developed as in R.
Future work includes extending packages that read external data from formats, databases or interfaces with support for measurement unit information into R, preserving the measurement unit information. Examples would be interfaces to HDF5 (e.g., h5, Annau (2016)), RNetCDF (Michna and Woods 2016) or sos4R (Nüst, Stasch, and Pebesma 2011). It would be nice to see units of measurements propagate into units of regression coefficient estimates.
We acknowledge three anonymous reviewers and the handling editor for
their constructive comments, and Thomas Lin Pedersen for implementing
the ggplot extensions in package
ggforce (ported to the
units package since v0.8-0) that automatically add units to
default ggplot axis labels.