Declare the overlap values and the scale they are on

A declarative marker for stack_frames()'s overlaps argument. It names, for every frame, the column holding the chance a unit would have been selected from that frame, including the frames it was not selected from, and states which scale those columns are on.

It is the declaring half of a pair. exante_overlaps() is the other: rather than naming columns that already hold the chances, it names the registers and lets samplyr resolve them from each frame's own design.

Usage

declared_overlaps(..., scale)

Arguments

...

One named argument per frame, giving the column name as a string: declared_overlaps(area = "pi_area", list = "pi_list").

scale

Which quantity the columns hold, "probabilities" or "weights". Required, and matched by exact name.

Value

An object of class samplyr_overlap_spec, carrying the declared scale and the column mapping, for stack_frames()'s overlaps argument.

Details

The scale is declared rather than inferred from the values. survey::multiframe() infers it, reading a matrix as weights when no non-zero entry in some frame falls below one, which is reachable whenever a frame is a census or its overlapping units are certainties. samplyr produces those routinely, so the value that decides the reading is a value this package generates on purpose.

"probabilities" and "weights" are reciprocal statements of the same thing, and the record normalizes either to probabilities, so the two are interchangeable once the scale is stated. scale has no default for the same reason it is not inferred: a probability of one and a weight of one are the same number.

See also

exante_overlaps() to resolve the chances from the registers instead of naming columns that hold them

Other multiple frames: as.data.frame.frame_stack(), as_svrepdesign.frame_stack(), as_svydesign.frame_stack(), exante_overlaps(), exante_probabilities(), stack_frames(), summary.frame_stack()

Examples

declared_overlaps(area = "pi_area", list = "pi_list",
                  scale = "probabilities")
#> ℹ Overlap probabilities, by frame: pi_area and pi_list

declared_overlaps(area = "w_area", list = "w_list", scale = "weights")
#> ℹ Overlap weights, by frame: w_area and w_list