This function does nothing. It is intended to inherit is parameters' documentation.
default_params_doc(
alignment,
alignment_params,
alignment_rng_seed,
base_frequencies,
bd_mutation_rate,
bd_tree,
bd_tree_filename,
beast2_bin_path,
beast2_input_filename,
beast2_options,
beast2_optionses,
beast2_options_inference,
beast2_options_est_evidence,
beast2_output_log_filename,
beast2_output_state_filename,
beast2_output_trees_filename,
beast2_output_trees_filenames,
beast2_path,
beast2_rng_seed,
branch_mutation_rate,
branch_subst_matrix,
brts,
burn_in_fraction,
chain_length,
check_input,
clock_model,
clock_models,
clock_model_name,
consensus,
crown_age,
df_long,
do_measure_evidence,
epsilon,
error_fun,
error_measure_params,
errors,
errors_filename,
est_evidence_mcmc,
evidence_epsilon,
evidence_filename,
exclude_model,
experiment,
experiments,
extinction_rate,
fasta_filename,
filename,
folder_name,
folder_names,
inference_model,
inference_conditions,
init_speciation_rate,
init_extinction_rate,
lambda,
log_evidence,
marg_lik_filename,
marg_liks,
max_evidence_epsilon,
max_n_tries,
mbd_l_matrix,
mbd_mutation_rate,
mbd_tree,
mcmc,
method,
model_selection,
model_type,
mrca_prior,
mu,
mutation_rate,
n_0,
n_mutations,
n_taxa,
n_replicates,
node_mutation_rate,
node_subst_matrix,
node_time,
nu,
nu_events,
os,
parameter_filename,
parameters_filename,
phylo,
phylogenies,
phylogeny,
pir_params,
pir_paramses,
pir_out,
pir_outs,
posterior_trees,
precision,
project_folder_name,
rename_fun,
result,
rng_seed,
rng_seeds,
rng_seed_twin_alignment,
rng_seed_twin_tree,
root_sequence,
run_experiment,
run_experiments,
run_if,
sample_interval,
seed,
sequence_length,
sim_phylo_fun,
sim_tral_fun,
sim_twal_fun,
sim_twin_tree_fun,
site_model,
site_models,
site_model_name,
sub_chain_length,
subst_matrix,
tree,
tree_and_model,
tree_and_models,
tree_and_model_descriptions,
tree_and_model_errors,
treelog_filename,
tree_filename,
tree_model,
tree_prior,
tree_priors,
tree_prior_name,
tree_type,
tree_types,
true_alignment,
true_phylogeny,
true_result,
twin_alignment,
twin_alignment_filename,
twin_evidence_filename,
twin_phylogeny,
twin_model,
twin_result,
twin_tree_filename,
twinning_params,
type,
verbose,
weight
)a DNA alignment, of class DNAbin
parameters to simulate an alignment, as can be created by create_alignment_params
The random number generator seed used to generate an alignment
the four base frequencies (a, c, g, t) to be specified to create the rate matrix (i.e. Q matrix) used to simulate alignments
the mutation rate when creating an alignment from a BD tree
a phylogent of class phylo, created by a Birth Death process
name of the file that stores a BD twin tree
path to BEAST2 binary file. The use of the binary BEAST2 file is required for estimation of the evidence (aka marginal likelihood). The default BEAST2 binary path can be obtained using get_default_beast2_bin_path
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.
BEAST2 options, as can be created by create_beast2_options
list of one or more BEAST2 options, as can be created by create_beast2_options
BEAST2 options, as can be created by create_beast2_options. The MCMC must be a normal MCMC, as can be created by create_mcmc.
BEAST2 options to estimate the evidence (aka marginal likelihood), as can be created by create_beast2_options. The MCMC must be a Nested Sampling MCMC, as can be created by create_ns_mcmc.
name of the log file created by BEAST2, 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. Specifying a beast2_output_log_filename allows to store that file in a more permanently stored location.
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. Specifying a beast2_output_state_filename allows to store that file in a more permanently stored location.
name of a trees files
created by BEAST2.
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
compared to a true phylogeny to obtain the inference errors.
Specifying beast2_output_trees_filename allows to store
this file in a more permanently stored location.
name of the one or more trees 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: its content is parsed and
compared to a true phylogeny to obtain the inference errors.
Specifying beast2_output_trees_filenames allows to store
these one or more files in a more permanently stored location.
Path to the
BEAST2 jar file (beast.jar)
or BEAST2 binary file '(beast)'.
Use get_default_beast2_jar_path for the default
BEAST2 jar file path.
Use get_default_beast2_bin_path for the default
BEAST2 binary file path.
The random number generator seed used by BEAST2
mutation rate along the branch. See, among others, sim_unlinked for more details
substitution matrix along the branches. See, among others, sim_unlinked for more details
numeric vector of (all postive) branching times, in time units before the present. Assuming no stem, the heighest value equals the crown age.
the fraction of the posterior trees (starting from the ones generated first) that will be discarded, must be a value from 0.0 (keep all), to 1.0 (discard all).
something
boolean to indicate if the input is checked. If set to TRUE, input is checked, resulting in a proper error message. Else, input is left unchecked, possibly resulting in unhelpful error messages.
a clock model, as created by create_clock_model
a list of one or more clock models, as created by create_clock_model
name of a clock model
the order of which the taxon labels are plotted
the fixed crown age of the posterior. Set to NA to let it be estimated
the output created by pir_run in the long form
boolean to indicate if the evidence (aka marginal likelihood) of an experiment must be measured
measure of relative accuracy when estimating a model's evidence (also known as marginal likelihood). Smaller values result in more precise estimations, that take longer to compute
function that determines the error between a given phylogeny and a the trees in a Bayesian posterior. The function must have two arguments:
the one given phylogeny, of class phylo
one or more posterior trees, of class multiphylo
The function must return as many errors as there are posterior trees given. The error must be lowest between identical trees. Example functions are:
get_gamma_error_fun: use the absolute difference in gamma statistic
get_nltt_error_fun: use the nLTT statistic
parameter set to specify how the error between the given phylogeny and the Bayesian posterior is determined. Use create_error_measure_params to create such a parameter set
a numeric vector of (positive) Bayesian inference errors. Use NA if these are not measured (yet)
baseline name for errors filenames, as created by get_temp_errors_filename
MCMC used in the estimation of the evidence (aka marginal likelihood). The MCMC must be a Nested Sampling MCMC, as can be created by create_ns_mcmc.
relative error in estimating the evidence (aka marginal likelihood).
filename to store the estimated evidences (aka marginal likelihoods), as can be created by get_temp_evidence_filename. Must be NA if there is evidence estimation (as determined by will_measure_evidence).
an inference model that has to be excluded, as can be created by create_inference_model
a pirouette experiment, as can be created by create_experiment
a list of one or more pirouette experiments, as can be created by create_experiment. If more than one experiment is provided and a "generative" experiment is part of them, the "generative" one has to be the first in the list. See also:
Use check_experiments to check the list of experiments for validity
Use create_all_experiments to create experiments with all combinations of tree model, clock model and tree priors
Use create_all_bd_experiments to create experiments with all combinations of tree model, clock model and tree priors, except for only using birth-death tree priors
Use create_all_coal_experiments to create all experiments with all combinations of tree model, clock model and tree priors, except for only coalescent tree priors
Use shorten_experiments to shorten the run time of the list of experiments
per-species extinction rate
name of a FASTA file. Use get_alignment_id to get the ID of the alignment
the file's name, without the path
name of the main folder
one or more folder names
an inference model, which is a combination of site model, clock model, tree prior and BEAST2 input and input filenames.
conditions under which the inference model is used in the inference
a speciation rate
an extinction rate
per-lineage speciation rate
the natural logarithm of the evidence (aka marginal likelihood). Can be NA if this is not measured
name of the file the marginal likelihoods (also known as 'evidences') are saved to
a data frame with marginal likelihoods/evidences. A test data frame can be created by create_test_marg_liks
set the maximum acceptable threshold for the
parameter evidence_epsilon
maximum number of tries before giving up
the L matrix of an MBD tree
the mutation rate when creating an alignment from a MBD tree
an MBD tree
MCMC options, as created by create_mcmc
determines how to create the twin tree
'random_tree' just produces a random tree;
'max_clade_cred' simulates n_replicates trees and
uses maxCladeCred to create a consensus tree;
'max_likelihood' simulates n_replicates trees
and selects the most likely;
one ways to select the models used in
inference, for example, generative picks the generative
model, where most_evidence picks the model with most
evidence. See get_model_selections for a list of
type of inference model supplied for an experiment. Possible values:
generative: the inference model is (or is assumed to be)
the inference model underlying the phylogeny
candidate: the inference model is a candidate model,
that competes with other models for having the most
evidence (aka highest marginal likelihood)
an MRCA prior, as created by create_mrca_prior
per-species extinction rate
the mutation rate per base pair per time unit. Use check_mutation_rate to check if a mutation rate is valid.
number of starting species
costrained number of mutations
number of tree tips
number of replicas to evaluate in order to create the twin tree
mutation rate on the node. See, among others, sim_unlinked for more details
substitution matrix on the nodes. See, among others, sim_unlinked for more details
amount of time spent at the nodes. See, among others, sim_unlinked for more details
the rate at which a multiple-birth specation is triggered
the number of nu-triggered events that have to be present in the simulated tree
name of the operating system, can be mac, unix
or win. Use check_os if the operating system
is valid.
full path to a 'parameters.csv' file
full path to a 'parameters.csv' file
a phylogeny of class phylo
a list of phylogenies, each phylogeny being of class phylo
a phylogeny of class phylo
the parameters of pirouette. They are created by create_pir_params.
a list of pirouette parameters, each element created by create_pir_params.
the output of pir_run
the output of pir_runs
phylogenetic trees in a BEAST2 posterior,
of class multiphylo
define the precision of the approximation.
project folder name
a function to rename a filename, as can be checked by check_rename_fun. This function should have one argument, which will be a filename or NA. The function should return one filename (when passed one filename) or one NA (when passed one NA). Example rename functions are:
get_remove_dir_fun function that removes the directory paths from the filenames, in effect turning these into local files
get_replace_dir_fun function that replaces the directory paths from the filenames
results from measurements. These are:
log_evidence the natural logarithm of the evidence (aka marginal likelihood). Can be NA if this is not measured
weight the weight of the model, compared to other (candidate) models. This weight will be between 0.0 (there is no evidence for this model) to 1.0 (all evidence indicates this is the best model). A weight of NA denotes that the weight is not measured
errors a numeric vector of (positive) Bayesian inference errors. Will be NA if these are not measured.
a random number generator seed
a vector of random number generator seeds
the random number generator seed as used in the simulation of a twin alignment
the random number generator seed as used in the simulation of a twin tree
the DNA sequence at the root of the phylogeny. By default, this will consist out of an equal amount of each letter Use check_root_sequence to check if a root sequence is valid.
one pirouette run experiment. A run experiment has these attributes:
experiment the (original) experiment
true_result the result of running the original experiment on the true phylogeny
twin_result the result of running the original experiment on the twin phylogeny
a list of one or more pirouette run experiments
the condition for an experiment's inference model to be run. Possible values:
always: always
best_candidate: if the inference model is the
candidate model with the most evidence (aka highest marginal
likelihood)
the interval at which the MCMC algorithm makes a measurement
a random number generator seed
the length of each DNA sequence in an alignment
function that, each time when called, simulates one random tree.
function to simulate a
true alignment with.
This function must have two arguments,
called true_phylogeny (which will hold the true phylogeny)
and root_sequence (which holds the DNA root sequence).
The return type must be DNAbin.
Use check_sim_tral_fun to verify if the function has the right signature and output.
Some standard functions:
Use get_sim_tral_with_std_nsm_fun to get a function (sim_tral_with_std_nsm) the use a standard site model.
Use get_sim_tral_with_lns_nsm_fun to get a function (sim_tral_with_lns_nsm) the use a linked node substitution site model.
Use get_sim_tral_with_uns_nsm_fun to get a function (sim_tral_with_uns_nsm) the use an unlinked node substitution site model.
function to simulate a
twin alignment with.
This function must have two arguments called twin_phylogeny (which
will hold the twin phylogeny) and true_alignment (which will
hold the alignment simulated from the true phylogeny). The
return type must be DNAbin.
Use check_sim_twal_fun to verify if the function has the right signature and output.
Some standard functions:
Use get_copy_tral_fun to get a function (copy_true_alignment) that copies a true to alignment to create a twin alignment
Use get_sim_twal_with_std_nsm_fun to get a function (sim_twal_with_std_nsm) that simulates a twin alignment using a standard site model
Use get_sim_twal_same_n_muts_fun to get a function (sim_twal_with_same_n_mutation) that simulates -using a standard model- a twin alignment with as much mutations compared to the root sequence as the true alignment has
Use sim_twal_with_lns_nsm that simulates a twin alignment using a linked node substitution model
Use sim_twal_with_uns_nsm that simulates a twin alignment using an unlinked node substitution model
function to simulate a twin tree with.
This function must have one argument called phylogeny
of type phylo and have a return type of type phylo
as well.
Some standard functions:
Use create_sim_yule_twin_tree_fun to use a Yule (aka Pure Birth) process
Use create_copy_twtr_from_true_fun to for a function that copies the true tree
Use get_sim_bd_twin_tree_fun to use a Birth-Death process
a nucleotide substitution model, which can be:
A standard nucloetide substitution model, as created by create_site_model
lns: a linked node-substitution model
uns: an unlinked node-substitution model
a list of one or more site models, as created by create_site_model
name of a site model
length of the sub-chain used by the Nested Sampling algorithm to estimate the marginal likelihood
nucleotide substitution matrix
an ultrametric phylogenetic tree of class phylo
one combination of a tree and model, as created by get_tree_and_model_values
one or more combination of a tree and model, as created by get_tree_and_model_values
tabular data that maps
a tree_and_model (e.g. generative_true) to
a description (e.g. "Generative, true"),
as created by get_tree_and_model_descriptions
a tibble of a tree_and_model
and errors, which passes check_tree_and_model_errors
name of the MCMC's treelog file,
which is $(tree).trees by default.
Use complete_treelog_filename to obtain the complete path to
the MCMC's treelog file.
name of the phylogeny file
model used to simulate the tree
a tree prior, as created by create_tree_prior
a list of one or more tree priors, as created by create_tree_prior
name of a tree prior
type of tree, can be true for the true
phylogeny, and twin for its twin tree
types of tree, a vector of true for a true
phylogeny, and twin for a twin tree
a DNA alignment, of class DNAbin
the true phylogeny; the actual evolutionary history of the species, of class phylo
result obtained from using the true tree
a DNA alignment, of class DNAbin
name of the FASTA file the twin alignment will be saved to
filename to store the estimated evidences (aka marginal likelihoods) of the twin tree
a phylogeny of class phylo
the model you want to use to generate the twin tree:
birth_death: birth death
yule: Yule or pure-birth
copy_true: use a copy of the true tree in the twinning
pipeline
See get_twin_models to see all possible
values of twin_model
result obtained from using the twin tree
name of the (.newick) file the twin
tree will be saved to
can be NA if no twinning is desired,
or can be the twinning parameters,
as can be created by create_twinning_params
one or more ways to select the models used in inference:
"generative": pick the generative model
most_evidence picks the model with most evidence
See get_model_selections for a list.
if TRUE, show more output
the weight of the model, compared to other (candidate) models. This weight will be between 0.0 (there is no evidence for this model) to 1.0 (all evidence indicates this is the best model). A weight of NA denotes that the weight is not measured
Documentation by Giovanni Laudanno, use of this function by Richèl J.C. Bilderbeek