obtain_permutation_matrix: Obtain Permutation Matrix from a Random Assignment Declaration

Description

Enumerates the assignments a design could have produced, one column per assignment. The matrix is the input to randomization inference, where a test statistic is recomputed under each column to build the distribution it would follow if the treatment had no effect. When a design admits more assignments than maximum_permutations, a random sample of them is returned instead, which approximates the same distribution.

Usage

obtain_permutation_matrix(declaration, maximum_permutations = 10000)

Value

A matrix with one row per unit and one column per assignment, whose entries are condition names. The columns are all of the assignments the declared design could produce, or a random sample of maximum_permutations of them if there are more than that. Column order carries no meaning, but it is the order obtain_permutation_probabilities() returns its probabilities in.

Arguments

declaration: A random assignment declaration, created by declare_ra(). (required)
maximum_permutations: If the number of possible random assignments exceeds maximum_permutations, obtain_permutation_matrix returns a random sample of maximum_permutations of them instead of enumerating all of them. Defaults to 10,000. (optional)

References

Andrews, G. E. (1976). The Theory of Partitions. Encyclopedia of Mathematics and its Applications, Volume 2. Reading, MA: Addison-Wesley.

Examples

Run this code


# complete

declaration <- declare_ra(N = 4)
perms <- obtain_permutation_matrix(declaration)
dim(perms)
obtain_num_permutations(declaration)

# blocked

blocks <- c("A", "A", "B", "B", "C", "C", "C")
declaration <- declare_ra(blocks = blocks)
perms <- obtain_permutation_matrix(declaration)
dim(perms)
obtain_num_permutations(declaration)

# clustered

clusters <- c("A", "B", "A", "B", "C", "C", "C")
declaration <- declare_ra(clusters = clusters)
perms <- obtain_permutation_matrix(declaration)
dim(perms)
obtain_num_permutations(declaration)

# large

declaration <- declare_ra(20)
choose(20, 10)
perms <- obtain_permutation_matrix(declaration)
dim(perms)