The animal (sample) sheet

str(invivo_study_samples)
#> 'data.frame':    59 obs. of  8 variables:
#>  $ AnimalID           : chr  "F1" "F2" "F3" "F4" ...
#>  $ Strain             : chr  "Strain B" "Strain B" "Strain B" "Strain B" ...
#>  $ Sex                : chr  "F" "F" "F" "F" ...
#>  $ BirthDate          : Date, format: "2021-05-24" "2021-03-01" ...
#>  $ Earmark            : chr  "R" "2L" "2L1R" "L" ...
#>  $ ArrivalWeight      : num  19.4 26.5 20.8 22.1 22.9 ...
#>  $ Arrival.weight.Unit: chr  "g" "g" "g" "g" ...
#>  $ Litter             : chr  "Litter 1" "Litter 2" "Litter 2" "Litter 2" ...

invivo_study_samples |>
  dplyr::count(Strain, Sex, BirthDate) |>
  gt::gt()

A simple data summary reveals that the cohort is almost equally composed of Strains A and B. There are male and female animals in quite different proportions, with a noticeable excess of the males. Birth dates are available for Strain A, but missing completely for Strain B.

Initial body weights (arrival weights), identifying ear marks and litter information are available for all animals. The litter is nested within the strain and all individuals within one litter naturally share one birth date.

invivo_study_samples |>
  dplyr::count(Strain, Litter, BirthDate) |>
  gt::gt()

Treatment list

str(invivo_study_treatments)
#> 'data.frame':    59 obs. of  3 variables:
#>  $ Treatment: chr  "Treatment 1" "Treatment 1" "Treatment 1" "Treatment 1" ...
#>  $ Strain   : chr  "Strain A" "Strain A" "Strain A" "Strain A" ...
#>  $ Sex      : chr  "M" "M" "M" "M" ...

invivo_study_treatments |>
  dplyr::count(Treatment, Strain, Sex) |>
  gt::gt()

We have 3 treatments that should each be administered to a defined number of animals. In addition, some satellite animals of either strain will not receive any treatment at all, which is specified by a fourth (‘untreated’) condition.

In most cases the treatment list could be reduced to the first column, i.e. repeating each label for the right number of times so that the total length matches the sample sheet.

However, additional study specific constraints may be specified by adding columns that also appear in the animal list and indicate how the treatments should be assigned to subgroups of the cohort. In this example, a different number of animals is used for each of the treatments, balanced across strains. However, female animals are only to be used for treatment 2.

Design constraints and data preparation

The specific constraints for our type of in vivo study may be summarized as follows:

• We want to form cages, each hosting ideally 3 animals (preferred range from 2-5)
• Strain, Sex and Treatment must be homogeneous within a cage
• Males from different litters must not be put into the same cage; litter mixing is possible however for female animals!
• Average body weight and age composition should be comparable between treatment groups and cages
• If at all possible, we avoid putting animals with identical ear markings into the same cage
• The distribution of treatments across animal subgroups (if specified by the treatment list!) has to be respected

The very special and intricate nature of these requirements motivate th creation of dedicated functionality on top of this package, as demonstrated by this vignette.

Before using these functions, we add two auxiliary columns to the sample sheet:

• AgeGroup represents the different birth dates as an integer variable, where unknown (NA) values get their own code.
• Litter_combine_females groups all female animals in a pseudo litter, facilitating the assignment of animals to cages at which point only the females can be freely combined (co-housed).

invivo_study_samples <- dplyr::mutate(invivo_study_samples,
  AgeGroup = as.integer(factor(BirthDate, exclude = NULL)),
  Litter_combine_females = ifelse(Sex == "F", "female_all", Litter)
)

invivo_study_samples |>
  dplyr::count(Strain, Litter_combine_females, BirthDate, AgeGroup) |>
  gt::gt()

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.

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.72