In richelbilderbeek/babettes: Experimental babette features

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

This vignette describes how to transition your interface from beautier v1.12.0 to v1.12.1 and why this interface is changed.

library(beautier)

Internal functions

This vignette checks if XML files created by beautier are accepted by BEAST2. The internal function is_beast2_input_file lets BEAST2 validate a BEAST2 input file. is_beast2_input_file assumes that BEAST2 is installed correctly and stops otherwise. Instead of forcing all beautier users to install BEAST2, a fail-safe wrapper function will be used:

is_beast2_input_file_safe <- function(beast2_input_filename) {
  tryCatch(
    return(beautier:::is_beast2_input_file(beast2_input_filename)),
    error = function(cond) {
      print("BEAST2 not found")
    }
  )
  TRUE
}

Changes

The major change is in how to set a fixed crown age.

One alignment is no problem

For one alignment, this is how this is done:

fasta_filename <- get_fasta_filename()

create_beast2_input_file_1_12(
  input_filenames = fasta_filename,
  output_filename = "fix.xml",
  fixed_crown_ages = TRUE,
  initial_phylogenies = fasta_to_phylo(
    fasta_filename = fasta_filename,
    crown_age = 15
  )
)
testit::assert(is_beast2_input_file_safe("fix.xml"))

For one alignment, these is no room to do incorrect things. This will change when using two alignments.

For two alignment, problems arise

When using two alignments, in which both crown ages are fixed, the interface is:

fasta_filenames <- get_beautier_paths(c("anthus_aco.fas", "anthus_nd2.fas"))

create_beast2_input_file_1_12(
  input_filenames = fasta_filenames,
  output_filename = "fix_fix.xml",
  fixed_crown_ages = c(TRUE, TRUE),
  initial_phylogenies = fastas_to_phylos(
    fasta_filename = fasta_filenames,
    crown_age = 15
  )
)
testit::assert(is_beast2_input_file_safe("fix_fix.xml"))

Questions that may open up are:

what if fixed_crown_ages is set to other boolean pairs?
what if initial_phylogenies is supplied two phylogenies with different crown ages?

what if `fixed_crown_ages` is set to other boolean pairs?

In the code above, fixed_crown_ages is set to TRUE for both alignments. This invites to explore other boolean pairs:

combinations <- list()
combinations[[1]] <- c(FALSE, FALSE)
combinations[[2]] <- c(TRUE, FALSE)
combinations[[3]] <- c(FALSE, TRUE)

for (i in seq_along(combinations)) {
  combination <- combinations[[i]]
  output_filename <- paste0("combination_", i, ".xml")

  create_beast2_input_file_1_12(
    input_filenames = fasta_filenames,
    output_filename = output_filename,
    fixed_crown_ages = combination,
    initial_phylogenies = fastas_to_phylos(
      fasta_filename = fasta_filenames,
      crown_age = 15
    )
  )
  testit::assert(is_beast2_input_file_safe(output_filename))
}

All combinations are legal, but irrelevant. Especially the combination c(TRUE, FALSE) is misleading: this will result in a posterior with phylogenies of all the same (fixed) crown ages: the first TRUE will 'take the lead', similar to when supplying two phylogenies with a different fixed crown age (see below).

what if `initial_phylogenies` is supplied two phylogenies with different crown ages?

If two phylogenies with a fixed -but different- crown age are supplied, a valid BEAST2 input file is created:

fasta_filenames <- get_beautier_paths(c("anthus_aco.fas", "anthus_nd2.fas"))

initial_phylogenies <- list()
initial_phylogenies[[1]] <- fasta_to_phylo(fasta_filenames[1], crown_age = 12)
initial_phylogenies[[2]] <- fasta_to_phylo(fasta_filenames[2], crown_age = 34)

create_beast2_input_file_1_12(
  input_filenames = fasta_filenames,
  output_filename = "12_34.xml",
  fixed_crown_ages = c(TRUE, TRUE),
  initial_phylogenies = initial_phylogenies
)

testit::assert(is_beast2_input_file_safe("12_34.xml"))

Running BEAST2 with 12_34.xml results in a posterior with phylogenies of a crown age of 12. Go ahead and try.

# Cleaning up
filenames <- c(
  "fix.xml", 
  "fix_fix.xml", 
  paste0("combination_", seq(1, 3), ".xml"), 
  "12_34.xml"
)

for (filename in filenames) {
  if (file.exists(filename)) file.remove(filename)
}