block2seqblock: Prepare prior nonsequential assignments for subsequent...
In blockTools: Block, Assign, and Diagnose Potential Interference in Randomized Experiments

block2seqblock

R Documentation

Prepare prior nonsequential assignments for subsequent sequential assignments

Description

Converts output objects from the block and assignment functions into an object in the format of one output by the seqblock function. This allows the user to block and assign multiple units at the beginning of an experiment (using block and assignment) and then sequentially block and assign more units to the experiment over time (using seqblock).

Usage

block2seqblock(
  block.obj,
  assg.obj,
  data,
  exact.restr = NULL,
  covar.restr = NULL,
  covar.order = NULL,
  trn = NULL,
  apstat = "mean",
  mtrim = 0.1,
  apmeth = "ktimes",
  kfac = 2,
  assgpr = c(0.5, 0.5),
  distance = NULL,
  datetime = NULL,
  orig,
  seed = NULL,
  file.name = "sbout.RData",
  verbose = FALSE
)

Arguments

`block.obj`	an output object from `block`, or a user-specified block object
`assg.obj`	an output object from `assignment`, or a user-specified assignment object
`data`	a matrix or dataframe containing the original data used to block the units in the study
`exact.restr`	a list object containing the restricted values that the exact blocking variables can take on. Thus the first element of `exact.restr` is a vector containing all of the possible values that the first exact blocking variable can take on; the second element is a vector containing all of the possible values for the second exact blocking variable; and so on
`covar.restr`	a list object containing the restricted values that the non-exact blocking variables can take on. Thus the first element of `covar.restr` is a vector containing all of the possible values that the first non-exact blocking variable can take on; the second element is a vector containing all of the possible values for the second non-exact blocking variable; and so on
`covar.order`	a string or vector of strings containing the name of the non-exact blocking variables ordered so that the highest priority covariate comes first, followed by the second highest priority covariate, then the third, etc.
`trn`	a string or vector of strings containing the names of the different treatment groups
`apstat`	a string specifying the assignment probability summary statistic that was used
`mtrim`	a numeric value specifying the proportion of observations to be dropped when the assignment probability statistic takes on the value `"trimmean"`.
`apmeth`	a string specifying the assignment probability algorithm that was used.
`kfac`	the assignment probability kfactor; see assg.prob.kfac in the Arguments section above
`assgpr`	a vector of assignment probabilities to each treatment group
`distance`	a string specifying how the multivarite distance used for blocking is calculated
`datetime`	the date and time that the units were assigned to the treatment group; by default this is set to be a vector of NA; however the user could also specify a specific datetime and all of the units from the block object will be given the same datetime stamp
`orig`	a dataframe containing the names and values for the different id and blocking variables, as well as each unit's initial treatment assignment
`seed`	an optional integer value for the random seed set which is used when assigning units to treatment groups
`file.name`	a string containing the name of the file that one would like the output to be written to. Ideally this file name should have the extension .RData
`verbose`	a logical stating whether the function should print the name of the output file, the current working directory, and the dataframe `x` returned by the function as part of the `bdata` list

Details

The function converts data from a blocked experiment into a form allowing subsequent sequential blocking. Minimally, the user sets only the arguments block.obj, assg.obj and data. Then, block2seqblock uses the call to block, the assignment object, and the original data to create an object that is ready to be input into seqblock.

If the user explicitly specifies groups, id.vars and block.vars in the initial block function that is used to create the block.obj, block2seqblock will order the variables in the output it produces according to the order specified in the initial block function call. If the user does not explicitly specify the blocking variables in the block function call, block2seqblock will order the variables according to the order in the initial matrix or dataframe that was used to run the original block function.

As part of the function, variables that are of class factor in the original matrix or dataframe specified in data, will be converted into class character.

The trn argument uses the n.tr argument from block to extract the names of the treatment variables. Most other arguments are set to default values that mirror those in the seqblock function. One exception is the datetime argument, which defaults to a vector of NA's instead of the current datetime.

Value

A list (called bdata) with elements

x: a dataframe containing the names and values for the different ID and blocking variables, as well as each unit's initial treatment assignment.
nid: a string or vector of strings containing the name(s) of the ID variable(s).
nex: a string or vector of strings containing the name(s) of the exact blocking variable(s).
ncv: a string or vector of strings containing the name(s) of the non-exact blocking variable(s).
rex: a list of the restricted values of the exact blocking variables.
rcv: a list of the restricted values of the non-exact blocking variables.
ocv: a vector of the order of the non-exact blocking variables.
trn: a string or vector of strings containing the name(s) of the different treatment groups.
apstat: a string specifying the assignment probability summary statistic that was used.
mtrim: a numeric value specifying the proportion of observations to be dropped when the assignment probability statistic takes on the value "trimmean".
apmeth: a string specifying the assignment probability algorithm that was used.
kfac: the assignment probability kfactor; see assg.prob.kfac in the Arguments section above.
assgpr: a vector of assignment probabilities to each treatment group.
distance: a string specifying how the multivarite distance used for blocking is calculated
trd: a list with the length equal to the number of previously assigned treatment conditions; each object in the list contains a vector of the distance between each unit in one treatment group and the new unit. Set to NULL when there are no non-exact blocking variables.
tr.sort: a string vector of treatment conditions, sorted from the largest to the smallest
p: a vector of assignment probabilities to each treatment group used in assigning a treatment condition to the new unit.
trcount: a table containing the counts for each experimental/treatment conditions.
datetime: the date and time that the user was assigned a treatment group.
orig: a dataframe containing the names and values for the different id and blocking variables, as well as each unit's initial treatment assignment.

Author(s)

Tommy Carroll tcarroll22@wustl.edu, Jonathan Homola homola@wustl.edu, and Ryan T. Moore rtm@american.edu

Examples

# data(x100)
# out <- block(x100, n.tr = 2, id.vars = c("id"), block.vars = c("b1", "b2"), 
#              algorithm = "optGreedy", distance = "mahalanobis", 
#              valid.var = "b1", valid.range = c(0,500))
# assg.out <- assignment(out, seed = 123)
# b2sb <- block2seqblock(block.obj = out, assg.obj = assg.out, data = x100)
# sb <- seqblock("sbout.RData", id.vals = 1101, covar.vals = c(100, 200), file.name = "sb101.RData")

blockTools documentation built on Oct. 20, 2024, 1:08 a.m.