apply_multiwave: Apply a basic optimall function to a Multiwave Object

In optimall: Allocate Samples Among Strata

Apply a basic optimall function to a Multiwave Object

Description

Given a specified phase and wave of an object of class multiwave, apply_multiwave applies one of four optimall functions and returns an updated multiwave object with the output of the applied function in its specified slot.

Usage

apply_multiwave(x, phase, wave, fun, ...)

## S4 method for signature 'Multiwave'
apply_multiwave(x, phase, wave, fun, ...)

Arguments

x	An Object of class "multiwave"
phase	A numeric or character value specifying the phase of multiwave where the desired output should be placed.
wave	A numeric or character value specifying the wave of phase in multiwave where the output should be placed.
fun	A character value specifying the name of the optimall function to apply. The four available functions are: optimum_allocation, allocate_wave, sample_strata, and merge_samples. optimum_allocation: Uses the data from the previous wave (or previous phase if wave = 1) to determine the optimum sampling allocation for the specified wave. If used, the output multiwave object contains an updated "design" slot in the specified wave. allocate_wave: Uses the data from the previous wave (or previous phase if wave = 1) to determine the optimum sampling allocation for the specified wave. If used, the output multiwave object contains an updated "design" slot in the specified wave. sample_strata: Uses the data from the previous wave (or previous phase if wave = 1) and design from current wave to generate a vector of ids to sample for the current wave. If used, the output multiwave object contains an updated "samples" slot in the specified wave. merge_samples: Uses the data from the previous wave (or previous phase if wave = 1) and sampled_data from the specified wave to generate the final, merged data for the current wave. If used, the output multiwave object contains an updated "data" slot in the specified wave. Note that merge_samples is already a method for multiwave objects, so calling it through apply_multiwave is the exact same as calling it on its own. See documentation of these functions for more details on the specific uses and arguments.
...	Optional arguments to be given to fun. Not necessary if the arguments are already provided as named values in the wave, phase, or overall metadata in the multiwave object. Arguments provided here will override specifications in the metadata if provided in both places.

Value

The inputted multiwave object with one slot updated to include the output of the specified function.

Note that the phase and wave arguments specify where the function output should be placed. apply_multiwave will determine where to get the input dataframes from (returning an error if those slots are empty or invalid) given the specified wave for the output. For example, if phase = 2, wave = 2, function = "allocate_wave", the data to determine the optimum allocation will be taken from the previous wave (phase 2, wave 1) and the output multiwave object will have an updated "design" slot of phase 2, wave 2.

Examples

library(datasets)

MySurvey <- new_multiwave(phases = 2, waves = c(1, 3))
get_data(MySurvey, phase = 1, slot = "data") <-
  dplyr::select(datasets::iris, -Sepal.Width)

# Get Design by applying optimum_allocation
MySurvey <- apply_multiwave(MySurvey,
  phase = 2, wave = 1,
  fun = "optimum_allocation", strata = "Species",
  y = "Sepal.Length",
  nsample = 15,
  method = "WrightII"
)

# or, we can establish function args in the metadata
get_data(MySurvey, phase = 2, slot = "metadata") <- list(
  strata = "Species",
  nsample = 15,
  y = "Sepal.Length",
  method = "WrightII"
)

# which allows the function to be run without specifying the args
MySurvey <- apply_multiwave(MySurvey,
  phase = 2, wave = 1,
  fun = "optimum_allocation"
)

optimall documentation built on Sept. 8, 2023, 6:07 p.m.