Multiplies (or divides) the numeric value columns of data by the value
of attribute resolved for each row's unit – a net calorific value to
turn mass into energy, an emission factor to turn energy into CO2, a
density to turn volume into mass. Values are resolved along the hierarchy
exactly as scale_attributes() does, so a factor stored on a coarser
member applies to every atom under it that has no factor of its own.
convert_scale(
data,
x,
attribute,
from_unit,
to_unit,
key = NULL,
frame = NULL,
values = NULL,
source = NULL,
na_action = c("error", "keep"),
collect = NULL
)The data, in any supported backend, with a column of codes at
frame.
A NestedScale carrying attribute.
Name of the attribute to convert with.
The physical units of the values before and after, matching the attribute's unit of measure.
Name of the code column in data; defaults to frame.
Frame the codes belong to. Inferred when exactly one of the
scale's frame names (or its atom level) is a column of data.
Value columns to convert; NULL takes every numeric column
that is not the key.
Restrict the attribute to one source; NULL errors on a
conflict between sources.
What to do with rows whose unit has no value:
"error" (default) or "keep" (an NA result).
For lazy inputs: materialise (TRUE) or return the query.
data with the value columns converted, plus two columns named
after the attribute: <attribute> (the factor applied) and
<attribute>.origin_frame (the frame the factor was taken from), in the
input's class.
Direction comes from the attribute's unit of measure, read as
"<numerator>/<denominator>": with lhv in "GJ/t", from_unit = "t", to_unit = "GJ" multiplies, and from_unit = "GJ", to_unit = "t" divides.
The inverse is allowed only when the attribute's kind is "property";
a "factor" is one-way. No unit-prefix arithmetic is done: a column in
kilotonnes must be turned into tonnes before converting with a GJ/t
factor.
A unit for which no value resolves is an error by default – a
silently dropped row is a wrong total – unless na_action = "keep",
which leaves NA in its rows.
s <- attach_attributes_scale(
scale_example(),
data.frame(frame = c("sector", "unit"), unit = c("P", "U5"),
attribute = "lhv", value = c(20, 30),
unit_of_measure = "GJ/t"),
source = "example", kind = "property"
)
mass <- data.frame(unit = c("U1", "U2", "U5"), t = c(100, 200, 50))
energy <- convert_scale(mass, s, attribute = "lhv",
from_unit = "t", to_unit = "GJ")
energy
#> unit t lhv lhv.origin_frame
#> 1 U1 2000 20 sector
#> 2 U2 4000 20 sector
#> 3 U5 1500 30 unit
# back to tonnes: a property is invertible
convert_scale(energy[c("unit", "t")], s, attribute = "lhv",
from_unit = "GJ", to_unit = "t")
#> unit t lhv lhv.origin_frame
#> 1 U1 100 20 sector
#> 2 U2 200 20 sector
#> 3 U5 50 30 unit