Add tutorial for #9

.gitignore

@@ -42,3 +42,4 @@ vignettes/article_cache/
 vignettes/article_files/
 anthus_aco.log
 my_beast2_input.xml
+vignettes/tutorial_cache/

R/bbt_run.R

@@ -14,25 +14,35 @@
 #' @param posterior_crown_age the posterior's crown age. Use NA to let
 #'   BEAST2 estimate this parameter. Use a positive value to fix the
 #'   crown age to that value
-#' @param beast2_input_filename name of the BEAST2 configuration file
+#' @param 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 \code{beast2_input_filename} allows to store that file
+#'   in a more permanently stored location.
 #' @param rng_seed the random number generator seed. Must be either
 #'   \code{NA} or a positive non-zero value. An RNG seed of \code{NA}
 #'   results in BEAST2 picking a random seed.
 #' @param beast2_output_log_filename name of the log file created by BEAST2,
-#'   containing the parameter estimates in time. By default, this temporary
-#'   file is put a default temporary folder and will be cleaned up by the
-#'   operating system. This file is a temporary file, as its content
+#'   containing the parameter estimates in time. 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 \code{beast2_output_log_filename} allows to store that file
+#'   in a more permanently stored location.
 #' @param beast2_output_trees_filenames name of the one or more trees
-#'   files created by BEAST2, one per alignment. By default, these temporary
-#'   files are put a default temporary folder and will be cleaned up by the
-#'   operating system. These files are temporary files, as their content
+#'   files created by BEAST2, one per alignment. By default, these
+#'   files are put a temporary folder with a random
+#'   filename, as the user needs not read it: their content
 #'   is parsed and returned by this function.
+#'   Specifying \code{beast2_output_trees_filenames} allows to store these
+#'   one or more files in a more permanently stored location.
 #' @param beast2_output_state_filename name of the final state file created
-#'   by BEAST2, containing the operator acceptances. By default, this temporary
-#'   file is put a default temporary folder and will be cleaned up by the
-#'   operating system. This file is a temporary file, as its content
+#'   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 \code{beast2_output_state_filename} allows to store that file
+#'   in a more permanently stored location.
 #' @param beast2_jar_path path to the BEAST2 jar file
 #' @param verbose set to TRUE for more output
 #' @param cleanup set to FALSE to keep all temporary files

vignettes/tutorial.R

@@ -0,0 +1,157 @@
+## ----setup, include = FALSE----------------------------------------------
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+
+## ------------------------------------------------------------------------
+library(babette)
+
+## ------------------------------------------------------------------------
+fasta_filename <- get_babette_path("anthus_aco.fas")
+testit::assert(file.exists(fasta_filename))
+
+## ------------------------------------------------------------------------
+mcmc <- create_mcmc(chain_length = 2000, store_every = 1000)
+
+## ----cache=TRUE----------------------------------------------------------
+out <- bbt_run(
+ fasta_filenames = fasta_filename,
+ mcmc = mcmc
+)
+
+## ------------------------------------------------------------------------
+site_model <- create_site_model_jc69()
+site_model <- create_jc69_site_model()
+
+## ----cache=TRUE----------------------------------------------------------
+out <- bbt_run(
+  fasta_filenames = fasta_filename,
+  site_models = site_model,
+  mcmc = mcmc
+)
+
+## ------------------------------------------------------------------------
+clock_model <- create_clock_model_strict()
+clock_model <- create_strict_clock_model()
+
+## ----cache=TRUE----------------------------------------------------------
+out <- bbt_run(
+  fasta_filenames = fasta_filename,
+  clock_models = clock_model,
+  mcmc = mcmc
+)
+
+## ------------------------------------------------------------------------
+tree_prior <- create_tree_prior_yule()
+tree_prior <- create_yule_tree_prior()
+
+## ----cache=TRUE----------------------------------------------------------
+out <- bbt_run(
+  fasta_filenames = fasta_filename,
+  tree_priors = tree_prior,
+  mcmc = mcmc
+)
+
+## ------------------------------------------------------------------------
+mrca_prior <- create_mrca_prior(
+  alignment_id = get_alignment_id(fasta_filename = fasta_filename), 
+  taxa_names = get_taxa_names(filename = fasta_filename)[1:2],
+  is_monophyletic = TRUE
+)
+
+## ------------------------------------------------------------------------
+mrca_distr <- create_normal_distr(
+  mean = create_mean_param(value = 15.0), 
+  sigma = create_sigma_param(value = 1.0)
+)
+
+## ------------------------------------------------------------------------
+mrca_prior <- create_mrca_prior(
+  alignment_id = get_alignment_id(fasta_filename = fasta_filename), 
+  taxa_names = get_taxa_names(filename = fasta_filename),
+  mrca_distr = mrca_distr
+)
+
+## ----cache=TRUE----------------------------------------------------------
+out <- bbt_run(
+  fasta_filenames = fasta_filename,
+  mrca_priors = mrca_prior,
+  mcmc = mcmc
+)
+
+## ----cache=TRUE----------------------------------------------------------
+# Prefer to use the 'create_mrca_prior' version below
+out <- bbt_run(
+  fasta_filenames = fasta_filename,
+  posterior_crown_age = 15,
+  mcmc = mcmc
+)
+
+## ----cache=TRUE----------------------------------------------------------
+# Prefer this over using 'posterior_crown_age'
+out <- bbt_run(
+  fasta_filenames = fasta_filename,
+  mrca_priors = create_mrca_prior(
+    alignment_id = get_alignment_id(fasta_filename = fasta_filename), 
+    taxa_names = get_taxa_names(filename = fasta_filename),
+    mrca_distr = create_normal_distr(
+      mean = create_mean_param(value = 15.0), 
+      sigma = create_sigma_param(value = 0.0001)
+    )
+  ),
+  mcmc = mcmc
+)
+
+## ------------------------------------------------------------------------
+if (1 == 2) {
+  beast2_input_filename <- "beast_input.xml"
+  beast2_output_log_filename <- "beast_ouput.log"
+  beast2_output_trees_filenames <- "beast_output.trees"
+  beast2_output_state_filename <- "beast_state.xml.state"
+  all_files <- c(
+    beast2_input_filename,
+    beast2_output_log_filename,
+    beast2_output_trees_filenames,
+    beast2_output_state_filename
+  )
+
+  out <- bbt_run(
+    fasta_filenames = fasta_filename,
+    mcmc = mcmc,
+    beast2_input_filename = beast2_input_filename,
+    beast2_output_log_filename = beast2_output_log_filename,
+    beast2_output_trees_filenames = beast2_output_trees_filenames,
+    beast2_output_state_filename = beast2_output_state_filename
+  )
+  testit::assert(all(file.exists(all_files)))
+  file.remove(all_files)
+}
+
+## ----cache=TRUE----------------------------------------------------------
+out <- bbt_run(
+  fasta_filenames = fasta_filename,
+  mcmc = mcmc,
+  rng_seed = 314
+)
+
+## ------------------------------------------------------------------------
+beast2_jar_path <- beastier::get_default_beast2_jar_path()
+print(beast2_jar_path)
+
+## ------------------------------------------------------------------------
+if (file.exists(beast2_jar_path)) {
+  out <- bbt_run(
+    fasta_filenames = fasta_filename,
+    mcmc = mcmc,
+    beast2_jar_path = beast2_jar_path
+  )
+}
+
+## ----cache=TRUE----------------------------------------------------------
+out <- bbt_run(
+  fasta_filenames = fasta_filename,
+  mcmc = mcmc,
+  verbose = TRUE
+)
+