1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/user_conversion.R
3\name{install_unit}
4\alias{install_unit}
5\alias{remove_unit}
6\title{Define or remove units}
7\usage{
8install_unit(symbol = character(0), def = character(0), name = character(0))
9
10remove_unit(symbol = character(0), name = character(0))
11}
12\arguments{
13\item{symbol}{a vector of symbols to be installed/removed.}
14
15\item{def}{either \itemize{
16  \item an empty definition, which defines a new base unit;
17  \item \code{"unitless"}, which defines a new dimensionless unit;
18  \item a relationship with existing units (see details for the syntax).
19}}
20
21\item{name}{a vector of names to be installed/removed.}
22}
23\description{
24Installing new symbols and/or names allows them to be used in \code{as_units},
25\code{make_units} and \code{set_units}. Optionally, a relationship can be
26defined between such symbols/names and existing ones (see details and examples).
27}
28\details{
29At least one symbol or name is expected, but multiple symbols and/or names
30can be installed (and thus mapped to the same unit) or removed at the same
31time. The \code{def} argument enables arbitrary relationships with existing
32units using UDUNITS-2 syntax:
33\tabular{llll}{
34  \strong{String Type} \tab \strong{Using Names} \tab \strong{Using Symbols}
35    \tab \strong{Comment}\cr
36  Simple \tab meter \tab m \tab \cr
37  Raised \tab meter^2 \tab m2 \tab
38    higher precedence than multiplying or dividing\cr
39  Product \tab newton meter \tab N.m \tab \cr
40  Quotient \tab meter per second \tab m/s \tab \cr
41  Scaled \tab 60 second \tab 60 s \tab \cr
42  Prefixed \tab kilometer \tab km \tab \cr
43  Offset \tab kelvin from 273.15 \tab K @ 273.15 \tab
44    lower precedence than multiplying or dividing\cr
45  Logarithmic \tab lg(re milliwatt) \tab lg(re mW) \tab
46    "lg" is base 10, "ln" is base e, and "lb" is base 2\cr
47  Grouped \tab (5 meter)/(30 second) \tab (5 m)/(30 s) \tab
48}
49The above may be combined, e.g., \code{"0.1 lg(re m/(5 s)^2) @ 50"}.
50You may also look at the \code{<def>} elements in the units database to see
51examples of string unit specifications.
52}
53\examples{
54# define a fortnight
55install_unit("fn", "2 week", "fortnight")
56year <- as_units("year")
57set_units(year, fn)        # by symbol
58set_units(year, fortnight) # by name
59# clean up
60remove_unit("fn", "fortnight")
61
62# working with currencies
63install_unit("dollar")
64install_unit("euro", "1.22 dollar")
65install_unit("yen", "0.0079 euro")
66set_units(as_units("dollar"), yen)
67# clean up
68remove_unit(c("dollar", "euro", "yen"))
69
70# an example from microbiology
71cfu_symbols <- c("CFU", "cfu")
72cfu_names <- c("colony_forming_unit", "ColonyFormingUnit")
73install_unit("cell")
74install_unit(cfu_symbols, "3.4 cell", cfu_names)
75cell <- set_units(2.5e5, cell)
76vol <- set_units(500, ul)
77set_units(cell/vol, "cfu/ml")
78set_units(cell/vol, "CFU/ml")
79set_units(cell/vol, "colony_forming_unit/ml")
80set_units(cell/vol, "ColonyFormingUnit/ml")
81# clean up
82remove_unit(c("cell", cfu_symbols), cfu_names)
83
84}
85