Skip to contents

Run BEAST2

Source: R/bbt_run.R
bbt_run.Rd

Do a full BEAST2 run: create a 'BEAST2' configuration file (like 'BEAUti 2'), run 'BEAST2', parse results (like 'Tracer')

Usage

bbt_run(
  fasta_filename,
  tipdates_filename = NA,
  site_model = beautier::create_jc69_site_model(),
  clock_model = beautier::create_strict_clock_model(),
  tree_prior = beautier::create_yule_tree_prior(),
  mrca_prior = NA,
  mcmc = beautier::create_mcmc(),
  beast2_input_filename = beastier::create_temp_input_filename(),
  rng_seed = 1,
  beast2_output_state_filename = beastier::create_temp_state_filename(),
  beast2_path = beastier::get_default_beast2_path(),
  overwrite = TRUE,
  verbose = FALSE
)

Arguments

fasta_filename

a FASTA filename

tipdates_filename

name of the file containing tip dates

site_model

one site model, see create_site_models

clock_model

one clock model, see create_clock_model

tree_prior

one tree priors, as created by create_tree_prior

mrca_prior

one Most Recent Common Ancestor prior, as returned by create_mrca_prior

mcmc

the MCMC options, see create_mcmc

beast2_input_filename

path of the 'BEAST2' configuration file. By default, this file is put in a temporary folder with a random filename, as the user needs not read it: it is used as input of 'BEAST2'. Specifying a beast2_input_filename allows to store that file in a more permanently stored location.

rng_seed

the random number generator seed. Must be either NA or a positive non-zero value. An RNG seed of NA results in 'BEAST2' picking a random seed.

beast2_output_state_filename

name of the final state file created by 'BEAST2', containing the operator acceptances. By default, this file is put a temporary folder with a random filename, as the user needs not read it: its content is parsed and returned by this function. Specifying a beast2_output_state_filename allows to store that file in a more permanently stored location.

beast2_path

name of either a 'BEAST2' binary file (usually simply beast) or a 'BEAST2' jar file (usually has a .jar extension). Use get_default_beast2_bin_path to get the default BEAST binary file's path Use get_default_beast2_jar_path to get the default BEAST jar file's path

overwrite

will 'BEAST2' overwrite files? Like 'BEAST2', this is set to TRUE by default. If TRUE, 'BEAST2' will overwrite the beast2_options$output_state_filename if its present. If FALSE, 'BEAST2' will not overwrite the beast2_options$output_state_filename if its present and babette will give an error message. Note that if overwrite is set to FALSE when a tracelog (see create_tracelog), screenlog (see create_screenlog) or treelog (see create_treelog) file already exists, 'BEAST2' (and thus babette) will freeze.

verbose

set to TRUE for more output

Value

a list with the following elements:

  • estimates: a data frame with 'BEAST2' parameter estimates

  • [alignment_id]_trees: a multiPhylo containing the phylogenies in the 'BEAST2' posterior. [alignment_id] is the ID of the alignment. For example, when running bbt_run with anthus_aco.fas, this element will have name anthus_aco_trees

  • operators: a data frame with the 'BEAST2' MCMC operator acceptances

  • output: a numeric vector with the output sent to standard output and error streams

  • ns: (optional) the results of a marginal likelihood estimation, will exist only when create_ns_mcmc was used for the MCMC. This structure will contain the following elements:

    • marg_log_lik the marginal log likelihood estimate

    • marg_log_lik_sd the standard deviation around the estimate

    • estimates the parameter estimates created during the marginal likelihood estimation

    • trees the trees created during the marginal likelihood estimation

Details

Prefer using bbt_run_from_model, as it has a cleaner interface.

See also

Use remove_burn_ins to remove the burn-ins from the posterior's estimates (posterior$estimates)

Author

Richèl J.C. Bilderbeek

Examples

if (beautier::is_on_ci() && is_beast2_installed()) {
  beastier::remove_beaustier_folders()
  beastier::check_empty_beaustier_folders()

  # Setup for a short run
  mcmc <- create_test_mcmc()

  # Store filenames for cleanup.
  # Note that 'bbt_run_from_model allows for easier cleanup
  mcmc$tracelog$filename <- tempfile()
  mcmc$treelog$filename <- tempfile()
  mcmc$screenlog$filename <- tempfile()
  beast2_input_filename <- tempfile()
  beast2_output_state_filename <- tempfile()

  bbt_run(
    fasta_filename = get_babette_path("anthus_aco.fas"),
    beast2_input_filename = beast2_input_filename,
    beast2_output_state_filename = beast2_output_state_filename,
    mcmc = mcmc
  )

  # Cleanup
  # Again, note that 'bbt_run_from_model allows for easier cleanup
  file.remove(mcmc$tracelog$filename)
  file.remove(mcmc$treelog$filename)
  file.remove(mcmc$screenlog$filename)
  file.remove(beast2_input_filename)
  file.remove(beast2_output_state_filename)
  beastier::remove_beaustier_folders()
  beastier::check_empty_beaustier_folders()
}