Title: | Model Comparison Using 'babette' |
---|---|
Description: | 'BEAST2' (<https://www.beast2.org>) is a widely used Bayesian phylogenetic tool, that uses DNA/RNA/protein data and many model priors to create a posterior of jointly estimated phylogenies and parameters. 'mcbette' allows to do a Bayesian model comparison over some site and clock models, using 'babette' (<https://github.com/ropensci/babette/>). |
Authors: | Richèl J.C. Bilderbeek [aut, cre]
|
Maintainer: | Richèl J.C. Bilderbeek <[email protected]> |
License: | GPL-3 |
Version: | 1.15.3 |
Built: | 2024-08-29 22:59:35 UTC |
Source: | https://github.com/ropensci/mcbette |
Calculate the weights for each marginal likelihood
calc_weights(marg_liks)
calc_weights(marg_liks)
marg_liks |
(non-log) marginal likelihood estimates |
the weight of each marginal likelihood estimate, which will sum up to 1.0
Richèl J.C. Bilderbeek
# Evidences (aka marginal likelihoods) can be very small evidences <- c(0.0001, 0.0002, 0.0003, 0.0004) # Sum will be 1.0 calc_weights(evidences) beastier::remove_beaustier_folders() beastier::check_empty_beaustier_folders()
# Evidences (aka marginal likelihoods) can be very small evidences <- c(0.0001, 0.0002, 0.0003, 0.0004) # Sum will be 1.0 calc_weights(evidences) beastier::remove_beaustier_folders() beastier::check_empty_beaustier_folders()
Can 'mcbette' run? Will return TRUE if:
(1) Running on Linux or MacOS
(2) BEAST2 is installed
(3) The BEAST2 NS package is installed
can_run_mcbette(beast2_folder = beastier::get_default_beast2_folder())
can_run_mcbette(beast2_folder = beastier::get_default_beast2_folder())
beast2_folder |
the folder where the BEAST2 is installed. Note that this is not the folder where the BEAST2 executable is installed: the BEAST2 executable is in a subfolder. Use get_default_beast2_folder to get the default BEAST2 folder. Use get_default_beast2_bin_path to get the full path to the default BEAST2 executable. Use get_default_beast2_jar_path to get the full path to the default BEAST2 jar file. |
Richèl J.C. Bilderbeek
can_run_mcbette() beastier::remove_beaustier_folders() beastier::check_empty_beaustier_folders()
can_run_mcbette() beastier::remove_beaustier_folders() beastier::check_empty_beaustier_folders()
Checks if the BEAST2 'NS' package is installed. Will stop if not
check_beast2_ns_pkg(beast2_bin_path = beastier::get_default_beast2_bin_path())
check_beast2_ns_pkg(beast2_bin_path = beastier::get_default_beast2_bin_path())
beast2_bin_path |
path to the the BEAST2 binary file |
marg_liks
are of the same type as returned
by est_marg_liks.stop if not.
check_marg_liks(marg_liks)
check_marg_liks(marg_liks)
marg_liks |
a table of (estimated) marginal likelihoods, as, for example, created by est_marg_liks. This data.frame has the following columns:
Use get_test_marg_liks to get a test |
mcbette_state
is valid.Check if the mcbette_state
is valid.
Will stop otherwise.
check_mcbette_state(mcbette_state)
check_mcbette_state(mcbette_state)
mcbette_state |
the mcbette state, which is a list with the following elements: |
Richèl J.C. Bilderbeek
Documentation of general function arguments. This function does nothing. It is intended to inherit function argument documentation.
default_params_doc( beast2_bin_path, beast2_folder, beast2_working_dir, beast2_options, beast2_optionses, clock_model, clock_models, epsilon, fasta_filename, inference_model, inference_models, marg_liks, mcbette_state, mcmc, os, rng_seed, site_model, site_models, tree_prior, tree_priors, verbose )
default_params_doc( beast2_bin_path, beast2_folder, beast2_working_dir, beast2_options, beast2_optionses, clock_model, clock_models, epsilon, fasta_filename, inference_model, inference_models, marg_liks, mcbette_state, mcmc, os, rng_seed, site_model, site_models, tree_prior, tree_priors, verbose )
beast2_bin_path |
path to the the BEAST2 binary file |
beast2_folder |
the folder where the BEAST2 is installed. Note that this is not the folder where the BEAST2 executable is installed: the BEAST2 executable is in a subfolder. Use get_default_beast2_folder to get the default BEAST2 folder. Use get_default_beast2_bin_path to get the full path to the default BEAST2 executable. Use get_default_beast2_jar_path to get the full path to the default BEAST2 jar file. |
beast2_working_dir |
folder in which BEAST2 will run and produce intermediate files. By default, this is a temporary folder |
beast2_options |
a |
beast2_optionses |
list of one or more |
clock_model |
a clock model, as can be created by create_clock_model |
clock_models |
a list of one or more clock models, as can be created by create_clock_models |
epsilon |
measure of relative accuracy. Smaller values result in longer, more precise estimations |
fasta_filename |
name of the FASTA file |
inference_model |
an inference model, as can be created by create_inference_model |
inference_models |
a list of one or more inference models, as can be created by create_inference_model |
marg_liks |
a table of (estimated) marginal likelihoods, as, for example, created by est_marg_liks. This data.frame has the following columns:
Use get_test_marg_liks to get a test |
mcbette_state |
the mcbette state, which is a list with the following elements: |
mcmc |
an MCMC for the Nested Sampling run, as can be created by create_mcmc_nested_sampling |
os |
name of the operating system,
must be |
rng_seed |
a random number generator seed used for the BEAST2 inference |
site_model |
a site model, as can be created by create_site_model |
site_models |
a list of one or more site models, as can be created by create_site_models |
tree_prior |
a tree prior, as can be created by create_tree_prior |
tree_priors |
a list of one or more tree priors, as can be created by create_tree_priors |
verbose |
if TRUE show debug output |
This is an internal function, so it should be marked with
@noRd
. This is not done, as this will disallow all
functions to find the documentation parameters
Richèl J.C. Bilderbeek
Estimate the marginal likelihood for an inference model.
est_marg_lik( fasta_filename, inference_model = beautier::create_ns_inference_model(), beast2_options = beastier::create_mcbette_beast2_options(), os = rappdirs::app_dir()$os )
est_marg_lik( fasta_filename, inference_model = beautier::create_ns_inference_model(), beast2_options = beastier::create_mcbette_beast2_options(), os = rappdirs::app_dir()$os )
fasta_filename |
name of the FASTA file |
inference_model |
an inference model, as can be created by create_inference_model |
beast2_options |
a |
os |
name of the operating system,
must be |
a list showing the estimated marginal likelihoods (and its estimated error), its items are::
marg_log_lik
: estimated marginal (natural) log likelihood
marg_log_lik_sd
: estimated error of marg_log_lik
esses
the Effective Sample Size
Richèl J.C. Bilderbeek
can_run_mcbette: see if 'mcbette' can run
est_marg_liks: estimate multiple marginal likelihoods
if (can_run_mcbette()) { # An example FASTA file fasta_filename <- system.file("extdata", "simple.fas", package = "mcbette") # A testing inference model with inaccurate (thus fast) marginal # likelihood estimation inference_model <- beautier::create_ns_inference_model() # Shorten the run, by doing a short (dirty, unreliable) MCMC inference_model$mcmc <- beautier::create_test_ns_mcmc() # Setup the options for BEAST2 to be able to call BEAST2 packages beast2_options <- beastier::create_mcbette_beast2_options() # Estimate the marginal likelihood est_marg_lik( fasta_filename = fasta_filename, inference_model = inference_model, beast2_options = beast2_options ) beastier::remove_beaustier_folders() }
if (can_run_mcbette()) { # An example FASTA file fasta_filename <- system.file("extdata", "simple.fas", package = "mcbette") # A testing inference model with inaccurate (thus fast) marginal # likelihood estimation inference_model <- beautier::create_ns_inference_model() # Shorten the run, by doing a short (dirty, unreliable) MCMC inference_model$mcmc <- beautier::create_test_ns_mcmc() # Setup the options for BEAST2 to be able to call BEAST2 packages beast2_options <- beastier::create_mcbette_beast2_options() # Estimate the marginal likelihood est_marg_lik( fasta_filename = fasta_filename, inference_model = inference_model, beast2_options = beast2_options ) beastier::remove_beaustier_folders() }
Estimate the marginal likelihoods (aka evidence)
for one or more inference models, based on a single alignment.
Also, the marginal likelihoods are compared, resulting in a
relative weight for each model, where a relative weight of a model
close to 1.0
means that that model is way likelier than
the others.
est_marg_liks( fasta_filename, inference_models = list(beautier::create_inference_model(mcmc = beautier::create_ns_mcmc())), beast2_optionses = rep(list(beastier::create_mcbette_beast2_options()), times = length(inference_models)), verbose = FALSE, os = rappdirs::app_dir()$os )
est_marg_liks( fasta_filename, inference_models = list(beautier::create_inference_model(mcmc = beautier::create_ns_mcmc())), beast2_optionses = rep(list(beastier::create_mcbette_beast2_options()), times = length(inference_models)), verbose = FALSE, os = rappdirs::app_dir()$os )
fasta_filename |
name of the FASTA file |
inference_models |
a list of one or more inference models, as can be created by create_inference_model |
beast2_optionses |
list of one or more |
verbose |
if TRUE show debug output |
os |
name of the operating system,
must be |
In the process, multiple (temporary) files are created (where
[x]
denotes the index in a list)
beast2_optionses[x]$input_filename
path to the the BEAST2 XML input file
beast2_optionses[x]$output_state_filename
path to the BEAST2 XML state file
inference_models[x]$mcmc$tracelog$filename
path to the BEAST2 trace file with parameter estimates
inference_models[x]$mcmc$treelog$filename
path to the BEAST2 trees
file with the posterior trees
inference_models[x]$mcmc$screenlog$filename
path to the BEAST2 screen output file
These file can be deleted manually by bbt_delete_temp_files, else these will be deleted automatically by the operating system.
a data.frame showing the estimated marginal likelihoods (and its estimated error) per combination of models. Columns are:
site_model_name
: name of the site model
clock_model_name
: name of the clock model
tree_prior_name
: name of the tree prior
marg_log_lik
: estimated marginal (natural) log likelihood
marg_log_lik_sd
: estimated error of marg_log_lik
weight
: relative model weight, a value from 1.0 (all
evidence is in favor of this model combination) to 0.0 (no
evidence in favor of this model combination)
ess
: effective sample size of the marginal likelihood
estimation
Richèl J.C. Bilderbeek
can_run_mcbette: see if 'mcbette' can run
est_marg_liks: estimate multiple marginal likelihood of a single inference mode
if (can_run_mcbette()) { # Use an example FASTA file fasta_filename <- system.file("extdata", "simple.fas", package = "mcbette") # Create two inference models inference_model_1 <- beautier::create_ns_inference_model( site_model = beautier::create_jc69_site_model() ) inference_model_2 <- beautier::create_ns_inference_model( site_model = beautier::create_hky_site_model() ) # Shorten the run, by doing a short (dirty, unreliable) MCMC inference_model_1$mcmc <- beautier::create_test_ns_mcmc() inference_model_2$mcmc <- beautier::create_test_ns_mcmc() # Combine the inference models inference_models <- list(inference_model_1, inference_model_2) # Create the BEAST2 options, that will write the output # to different (temporary) filanems beast2_options_1 <- beastier::create_mcbette_beast2_options() beast2_options_2 <- beastier::create_mcbette_beast2_options() # Combine the two BEAST2 options sets, # use reduplicated plural beast2_optionses <- list(beast2_options_1, beast2_options_2) # Compare the models marg_liks <- est_marg_liks( fasta_filename, inference_models = inference_models, beast2_optionses = beast2_optionses ) # Interpret the results interpret_marg_lik_estimates(marg_liks) beastier::remove_beaustier_folders() beastier::check_empty_beaustier_folders() }
if (can_run_mcbette()) { # Use an example FASTA file fasta_filename <- system.file("extdata", "simple.fas", package = "mcbette") # Create two inference models inference_model_1 <- beautier::create_ns_inference_model( site_model = beautier::create_jc69_site_model() ) inference_model_2 <- beautier::create_ns_inference_model( site_model = beautier::create_hky_site_model() ) # Shorten the run, by doing a short (dirty, unreliable) MCMC inference_model_1$mcmc <- beautier::create_test_ns_mcmc() inference_model_2$mcmc <- beautier::create_test_ns_mcmc() # Combine the inference models inference_models <- list(inference_model_1, inference_model_2) # Create the BEAST2 options, that will write the output # to different (temporary) filanems beast2_options_1 <- beastier::create_mcbette_beast2_options() beast2_options_2 <- beastier::create_mcbette_beast2_options() # Combine the two BEAST2 options sets, # use reduplicated plural beast2_optionses <- list(beast2_options_1, beast2_options_2) # Compare the models marg_liks <- est_marg_liks( fasta_filename, inference_models = inference_models, beast2_optionses = beast2_optionses ) # Interpret the results interpret_marg_lik_estimates(marg_liks) beastier::remove_beaustier_folders() beastier::check_empty_beaustier_folders() }
Get the current state of mcbette
get_mcbette_state(beast2_folder = beastier::get_default_beast2_folder())
get_mcbette_state(beast2_folder = beastier::get_default_beast2_folder())
beast2_folder |
the folder where the BEAST2 is installed. Note that this is not the folder where the BEAST2 executable is installed: the BEAST2 executable is in a subfolder. Use get_default_beast2_folder to get the default BEAST2 folder. Use get_default_beast2_bin_path to get the full path to the default BEAST2 executable. Use get_default_beast2_jar_path to get the full path to the default BEAST2 jar file. |
a list with the following elements:
beast2_installed TRUE if BEAST2 is installed, FALSE otherwise
ns_installed TRUE if the BEAST2 NS package is installed FALSE if the BEAST2 or the BEAST2 NS package is not installed
get_mcbette_state() beastier::remove_beaustier_folders() beastier::check_empty_beaustier_folders()
get_mcbette_state() beastier::remove_beaustier_folders() beastier::check_empty_beaustier_folders()
marg_liks
Get testing marg_liks
get_test_marg_liks()
get_test_marg_liks()
get_test_marg_liks() beastier::remove_beaustier_folders() beastier::check_empty_beaustier_folders()
get_test_marg_liks() beastier::remove_beaustier_folders() beastier::check_empty_beaustier_folders()
Interpret a Bayes factor, using the interpretation from [1].
interpret_bayes_factor(bayes_factor)
interpret_bayes_factor(bayes_factor)
bayes_factor |
Bayes factor to be interpreted |
[1] H. Jeffreys (1961). The Theory of Probability (3rd ed.). Oxford. p. 432
a string with the interpretation in English
Richèl J.C. Bilderbeek
interpret_bayes_factor(0.5) beastier::remove_beaustier_folders() beastier::check_empty_beaustier_folders()
interpret_bayes_factor(0.5) beastier::remove_beaustier_folders() beastier::check_empty_beaustier_folders()
Interpret the marginal likelihood estimates as created by est_marg_liks.
interpret_marg_lik_estimates(marg_liks)
interpret_marg_lik_estimates(marg_liks)
marg_liks |
a table of (estimated) marginal likelihoods, as, for example, created by est_marg_liks. This data.frame has the following columns:
Use get_test_marg_liks to get a test |
Richèl J.C. Bilderbeek
marg_liks
is validDetermine if the marg_liks
is valid
is_marg_liks(marg_liks, verbose = FALSE)
is_marg_liks(marg_liks, verbose = FALSE)
marg_liks |
a table of (estimated) marginal likelihoods, as, for example, created by est_marg_liks. This data.frame has the following columns:
Use get_test_marg_liks to get a test |
verbose |
if TRUE show debug output |
TRUE if the argument is a valid marg_liks
,
FALSE otherwise
Create a mcbette report, to be used when reporting bugs
mcbette_report(beast2_folder = beastier::get_default_beast2_folder())
mcbette_report(beast2_folder = beastier::get_default_beast2_folder())
beast2_folder |
the folder where the BEAST2 is installed. Note that this is not the folder where the BEAST2 executable is installed: the BEAST2 executable is in a subfolder. Use get_default_beast2_folder to get the default BEAST2 folder. Use get_default_beast2_bin_path to get the full path to the default BEAST2 executable. Use get_default_beast2_jar_path to get the full path to the default BEAST2 jar file. |
nothing. It is intended that the output (not the return value) is copy-pasted from screen.
Richèl J.C. Bilderbeek
if(beautier::is_on_ci()) { mcbette_report() }
if(beautier::is_on_ci()) { mcbette_report() }
Performs a minimal mcbette run
mcbette_self_test(beast2_folder = beastier::get_default_beast2_folder())
mcbette_self_test(beast2_folder = beastier::get_default_beast2_folder())
beast2_folder |
the folder where the BEAST2 is installed. Note that this is not the folder where the BEAST2 executable is installed: the BEAST2 executable is in a subfolder. Use get_default_beast2_folder to get the default BEAST2 folder. Use get_default_beast2_bin_path to get the full path to the default BEAST2 executable. Use get_default_beast2_jar_path to get the full path to the default BEAST2 jar file. |
marg_liks
Plot the marg_liks
plot_marg_liks(marg_liks)
plot_marg_liks(marg_liks)
marg_liks |
a table of (estimated) marginal likelihoods, as, for example, created by est_marg_liks. This data.frame has the following columns:
Use get_test_marg_liks to get a test |
a ggplot
plot_marg_liks(get_test_marg_liks()) beastier::remove_beaustier_folders() beastier::check_empty_beaustier_folders()
plot_marg_liks(get_test_marg_liks()) beastier::remove_beaustier_folders() beastier::check_empty_beaustier_folders()
Set the mcbette state to having BEAST2 installed with or without installing the BEAST2 NS package.
set_mcbette_state( mcbette_state, beast2_folder = beastier::get_default_beast2_folder(), verbose = FALSE )
set_mcbette_state( mcbette_state, beast2_folder = beastier::get_default_beast2_folder(), verbose = FALSE )
mcbette_state |
the mcbette state, which is a list with the following elements: |
beast2_folder |
the folder where the BEAST2 is installed. Note that this is not the folder where the BEAST2 executable is installed: the BEAST2 executable is in a subfolder. Use get_default_beast2_folder to get the default BEAST2 folder. Use get_default_beast2_bin_path to get the full path to the default BEAST2 executable. Use get_default_beast2_jar_path to get the full path to the default BEAST2 jar file. |
verbose |
if TRUE show debug output |
In newer versions of BEAST2, BEAST2 comes pre-installed with the BEAST2 NS package. For such a version, one cannot install BEAST2 without NS. A warning will be issues if one intends to only install BEAST2 (i.e. without the BEAST2 NS package) and gets the BEAST2 NS package installed as a side effect as well.
Also, installing or uninstalling a BEAST2 package from a BEAST2 installation will affect all installations.
Use get_mcbette_state to get the current mcbette state
Use check_mcbette_state to check the current mcbette state