Recast unit data down to the atom layer, and back

The two public halves of the from -> atoms -> to route: recast_to_atoms() projects unit-keyed data DOWN to the atom layer (one row per atom), and recast_from_atoms() aggregates atom-keyed data UP into a frame's units. Their composition is recast_scale(), and because the atom rows are keyed by the atom IDs, recast_from_atoms(recast_to_atoms(data, a), b, to) recasts across two scales that share atom keys.

recast_to_atoms(
  data,
  x,
  from = NULL,
  key = NULL,
  values = NULL,
  rule = NULL,
  weight = NULL,
  attach_weight = TRUE,
  collect = NULL
)

recast_from_atoms(
  data,
  x,
  to,
  key = NULL,
  values = NULL,
  rule = NULL,
  weight = NULL,
  na_rm = FALSE,
  na_action = c("drop", "error", "keep"),
  collect = NULL
)

Arguments

data

The data: for recast_to_atoms() keyed by unit code at frame from; for recast_from_atoms() keyed by atom IDs.

x

The NestedScale the data is keyed in, or aggregated into.

from

to_atoms only: frame name the codes belong to. NULL (default) is inferred as in recast_scale().

key

The key column; defaults as in recast_scale().

values, rule

As in recast_scale().

weight

to_atoms: a declared weight column of x. from_atoms: the name of a column of data to weight by, so the weight may vary by identifier. NULL uses a weight column of the data if present, else the scale's declared weight.

attach_weight

to_atoms only: attach the weight column (default TRUE).

collect

For lazy inputs: materialise (TRUE) or return the query.

to

from_atoms only: target frame name.

na_rm

from_atoms only: read an NA value as "this member says nothing" rather than as an unknown that makes the whole group NA.

na_action

from_atoms only: what to do with atoms that have no code at to.

Value

recast_to_atoms(): one row per (atom x identifier combination). recast_from_atoms(): one row per (unit x identifier combination). Both in the input's class; lazy in, lazy out.

Details

Going down, extensive columns (rule "sum") are split across a unit's atoms proportionally to the chosen weight so totals conserve; intensive columns are repeated. A weight column is attached by default so the return trip's "weighted_mean" reproduces the source weighting exactly.

Examples

s <- scale_example()
d <- data.frame(sector = c("P", "S"), capacity = c(10, 20))
atoms <- recast_to_atoms(d, s,
  from = "sector", rule = "sum",
  weight = "size"
)
head(atoms)
#>   unit  capacity weight
#> 1   U1  1.000000    100
#> 2   U2  2.000000    200
#> 3   U3  3.000000    300
#> 4   U4  4.000000    400
#> 5   U5  9.090909    500
#> 6   U6 10.909091    600
recast_from_atoms(
  atoms, s,
  to = "class",
  rule = "sum",
  na_action = "keep"
)
#>   class capacity
#> 1    G1        3
#> 2    G2        7
#> 3    S1       20
#> 4  <NA>       NA