Design steps
The process of solving the design problem can be divided into 3 successive steps, each of which is addressed by a specific in vivo-specific wrapper function.
Assign treatments to individuals animals (function InVivo_assignTreatments())
Allocate animals to cages (function Invivo_assignCages())
Arrange cages in one or more racks of given dimension (function Invivo_arrangeCages())
Dedicated constraints have to be handled at each step, as is reflected in the interface of those wrappers.
As stated above, implementation details are beyond the scope of this example. We will instead just show the interfaces of the three wrappers, run the example case and visualize the resulting design.
Assign treatments to animal list
InVivo_assignTreatments <- function(animal_list, treatments,
balance_treatment_vars = c(),
form_cages_by = c(),
n_shuffle = c(rep(5, 100), rep(3, 200), rep(2, 500), rep(1, 20000)),
quiet_process = FALSE, quiet_optimize = TRUE) {
(...)
}The function works with the initial animal and treatment lists.
Most importantly, balance_treatment_vars lists the variables that should be balanced across treatments (e.g. strain, sex, body weight, age, litter). Different scoring functions will be created for categorical and numerical covariates.
form_cages_by is not mandatory, but gives important clues regarding the variables that will later be homogeneous within each cage (e.g. strain, sex, litter). Providing this may be crucial for finding good solutions with a low number of single-housed animals that don’t fit into any other cage.
It is also possible to modify the shuffling protocol and toggle messaging on the level of processing steps as well as optimization iterations.
Populate cages
Invivo_assignCages <- function(design_trt,
cagegroup_vars,
unique_vars = c(),
balance_cage_vars = c(),
n_min = 2, n_max = 5, n_ideal = 2, prefer_big_groups = TRUE, strict = TRUE,
maxiter = 5e3,
quiet_process = FALSE, quiet_optimize = TRUE) {
(...)
}This wrapper takes the output of the previous step (‘design_trt’) as input.
- cagegroup_vars is a list of variables that must be uniform within each cage (e.g. treatment”, strain, sex, litter).
- unique_vars is a list of variables whose values should be unique per cage (e.g. ear marking). This constraint will be relaxed in a stepwise way if no solution can be found under strict adherence.
- balance_cage_vars lists variables which should be evenly distributed across cages, as far as possible (e.g. age, body weight).
- n_min, n_max and n_ideal specify the minimal, maximal and ideal cage sizes, respectively. It is often necessary to release the strict criterion to find any solution at all or reduce the number of remaining single-housed animals.
Arrange cages in rack(s)
Invivo_arrangeCages <- function(design_cage,
distribute_cagerack_vars = "Treatment",
rack_size_x = 4,
rack_size_y = 4,
n_shuffle = c(rep(5, 100), rep(3, 400), rep(2, 500), rep(1, 4000)),
quiet_process = FALSE, quiet_optimize = TRUE) {
(...)
}This wrapper takes the output of the previous step (‘design_cage’) as input.
distribute_cagerack_vars is a list of variables that should be evenly spaced out across the rows and columns of a rack (or several racks, if needed). Typical cases may include treatment, strain and sex of the animals.
rack_size_x and rack_size_y specify the number of cages that fit into the rows and columns of a grid like rack, respectively. Depending on the actual number of cages, one or more racks are automatically assigned. Only rectangular sub-grids may be used of any rack to accommodate the cages.
Calculating the design
A full run of the three wrapper functions is executed below, printing messages on the level of processing steps, but not the iterations within every optimization.
set.seed(44)
# Assign treatments to animals, respecting user provided as well as passed constraints
design_trt <- InVivo_assignTreatments(invivo_study_samples, invivo_study_treatments,
form_cages_by = c("Strain", "Sex", "Litter_combine_females"),
balance_treatment_vars = c("Strain", "Sex", "ArrivalWeight", "AgeGroup"),
n_shuffle = c(rep(5, 200), rep(3, 300), rep(2, 500), rep(1, 3000)),
quiet_process = FALSE,
quiet_optimize = TRUE
)
#> Performing treatment assignment with constrained animal selection.
#> Using constraints in variables: Strain, Sex
#> Checking if solution is possible:
#> ... Yes!
#> Setting up batch container.
#> Constructing scoring functions:
#> ... user specified treatment allocation constraint (Treatment-Strain-Sex)
#> ... facilitating homogeneity of treatment in cages (CageGroup)
#> ... ANOVA -logP for numerical variables balanced across treatment (ArrivalWeight, AgeGroup)
#> Success. User provided constraints could be fully met.
# Form cages with reasonable animal numbers and compliant with all constraints
design_cage <- Invivo_assignCages(design_trt,
cagegroup_vars = c("Treatment", "Strain", "Sex", "Litter_combine_females"),
unique_vars = c("Earmark"),
balance_cage_vars = c("ArrivalWeight", "AgeGroup"),
n_min = 2, n_max = 5, n_ideal = 2, prefer_big_groups = T, strict = F,
maxiter = 1000,
quiet_process = FALSE,
quiet_optimize = TRUE
)
#> Setting up batch container.
#>
#> Formed 22 homogeneous groups using 59 samples.
#> 27 subgroups needed to satisfy size constraints.
#>
#> Finding possible ways to allocate variable of interest with 1 levels ...
#>
#> Finished with 27 recursive calls.
#> 1 allocations found.
#>
#> Expecting 27 cages to be created and 4 single-housed animals.
#> Constructing scoring functions:
#> ... ANOVA -logP for numerical variables balanced across cages (ArrivalWeight, AgeGroup)
#> Adding 4 attributes to samples.
# Arrange cages in sub-grid of one rack (or several racks), avoiding spatial clusters
design_rack <- Invivo_arrangeCages(design_cage,
distribute_cagerack_vars = c("Treatment", "Strain", "Sex"),
rack_size_x = 7,
rack_size_y = 10,
n_shuffle = c(rep(5, 100), rep(3, 200), rep(2, 300), rep(1, 500)),
quiet_process = FALSE,
quiet_optimize = TRUE
)
#> Needing 1 rack with a grid of 4 x 7 cages.
#> There will be 1 empty position overall.
#> Setting up batch container.
#>
#> Distributing target variables (Treatment, Strain, Sex) within rack
#> ... Rack 1
#> ... Performing simple mean/stddev adjustment.
#> ... final scores: Plate_Treatment: 5.12, Plate_Strain: 5.48, Plate_Sex: 5.72Visualization of the study design
Cage composition
There are 27 cages in total.
Strains and age groups should be evenly split (balanced) across the treatments. Also,in each cage there should be only animals with the same treatment, strain and sex.
Females are exclusively used for treatment 2, as was specified in the treatment list.
Body weights
Body weights should be balanced across treatments as well as possible.
The plot illustrates that this is true for the overall weight distribution (box plots). Interestingly, as there are females (associated with considerable less body weight) involved in treatment 2, the optimization favored the selection of heavier males in this group to compensate, achieving better cross-treatment balance of this factor.
Red diamonds mark the mean values for a specific sex within each treatment group.
Cage arrangement in rack
The following plots show the organization of the cage rack, individual cages colored by different variables each time.
Individual animals in cages
Finally, an overview plot illustrates the placement of animals in the cages. Notice the distinct earmarks within each cage, a ‘soft’ design constraint that could be achieved with the given solution.
