default_params_doc: This function does nothing. It is intended to inherit is...

In richelbilderbeek/pirouette: Create a Bayesian Posterior from a Phylogeny

This function does nothing. It is intended to inherit is parameters' documentation.

Description

This function does nothing. It is intended to inherit is parameters' documentation.

Usage

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
)

Arguments

alignment	a DNA alignment, of class DNAbin
alignment_params	parameters to simulate an alignment, as can be created by create_alignment_params
alignment_rng_seed	The random number generator seed used to generate an alignment
base_frequencies	the four base frequencies (a, c, g, t) to be specified to create the rate matrix (i.e. Q matrix) used to simulate alignments
bd_mutation_rate	the mutation rate when creating an alignment from a BD tree
bd_tree	a phylogent of class phylo, created by a Birth Death process
bd_tree_filename	name of the file that stores a BD twin tree
beast2_bin_path	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
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.
beast2_options	BEAST2 options, as can be created by create_beast2_options
beast2_optionses	list of one or more BEAST2 options, as can be created by create_beast2_options
beast2_options_inference	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_est_evidence	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.
beast2_output_log_filename	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.
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. Specifying a beast2_output_state_filename allows to store that file in a more permanently stored location.
beast2_output_trees_filename	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.
beast2_output_trees_filenames	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.
beast2_path	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.
beast2_rng_seed	The random number generator seed used by BEAST2
branch_mutation_rate	mutation rate along the branch. See, among others, sim_unlinked for more details
branch_subst_matrix	substitution matrix along the branches. See, among others, sim_unlinked for more details
brts	numeric vector of (all postive) branching times, in time units before the present. Assuming no stem, the heighest value equals the crown age.
burn_in_fraction	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).
chain_length	something
check_input	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.
clock_model	a clock model, as created by create_clock_model
clock_models	a list of one or more clock models, as created by create_clock_model
clock_model_name	name of a clock model
consensus	the order of which the taxon labels are plotted
crown_age	the fixed crown age of the posterior. Set to NA to let it be estimated
df_long	the output created by pir_run in the long form
do_measure_evidence	boolean to indicate if the evidence (aka marginal likelihood) of an experiment must be measured
epsilon	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
error_fun	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
error_measure_params	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
errors	a numeric vector of (positive) Bayesian inference errors. Use NA if these are not measured (yet)
errors_filename	baseline name for errors filenames, as created by get_temp_errors_filename
est_evidence_mcmc	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.
evidence_epsilon	relative error in estimating the evidence (aka marginal likelihood).
evidence_filename	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).
exclude_model	an inference model that has to be excluded, as can be created by create_inference_model
experiment	a pirouette experiment, as can be created by create_experiment
experiments	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
extinction_rate	per-species extinction rate
fasta_filename	name of a FASTA file. Use get_alignment_id to get the ID of the alignment
filename	the file's name, without the path
folder_name	name of the main folder
folder_names	one or more folder names
inference_model	an inference model, which is a combination of site model, clock model, tree prior and BEAST2 input and input filenames.
inference_conditions	conditions under which the inference model is used in the inference
init_speciation_rate	a speciation rate
init_extinction_rate	an extinction rate
lambda	per-lineage speciation rate
log_evidence	the natural logarithm of the evidence (aka marginal likelihood). Can be NA if this is not measured
marg_lik_filename	name of the file the marginal likelihoods (also known as 'evidences') are saved to
marg_liks	a data frame with marginal likelihoods/evidences. A test data frame can be created by create_test_marg_liks
max_evidence_epsilon	set the maximum acceptable threshold for the parameter evidence_epsilon
max_n_tries	maximum number of tries before giving up
mbd_l_matrix	the L matrix of an MBD tree
mbd_mutation_rate	the mutation rate when creating an alignment from a MBD tree
mbd_tree	an MBD tree
mcmc	MCMC options, as created by create_mcmc
method	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;
model_selection	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
model_type	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)
mrca_prior	an MRCA prior, as created by create_mrca_prior
mu	per-species extinction rate
mutation_rate	the mutation rate per base pair per time unit. Use check_mutation_rate to check if a mutation rate is valid.
n_0	number of starting species
n_mutations	costrained number of mutations
n_taxa	number of tree tips
n_replicates	number of replicas to evaluate in order to create the twin tree
node_mutation_rate	mutation rate on the node. See, among others, sim_unlinked for more details
node_subst_matrix	substitution matrix on the nodes. See, among others, sim_unlinked for more details
node_time	amount of time spent at the nodes. See, among others, sim_unlinked for more details
nu	the rate at which a multiple-birth specation is triggered
nu_events	the number of nu-triggered events that have to be present in the simulated tree
os	name of the operating system, can be mac, unix or win. Use check_os if the operating system is valid.
parameter_filename	full path to a 'parameters.csv' file
parameters_filename	full path to a 'parameters.csv' file
phylo	a phylogeny of class phylo
phylogenies	a list of phylogenies, each phylogeny being of class phylo
phylogeny	a phylogeny of class phylo
pir_params	the parameters of pirouette. They are created by create_pir_params.
pir_paramses	a list of pirouette parameters, each element created by create_pir_params.
pir_out	the output of pir_run
pir_outs	the output of pir_runs
posterior_trees	phylogenetic trees in a BEAST2 posterior, of class multiphylo
precision	define the precision of the approximation.
project_folder_name	project folder name
rename_fun	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
result	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.
rng_seed	a random number generator seed
rng_seeds	a vector of random number generator seeds
rng_seed_twin_alignment	the random number generator seed as used in the simulation of a twin alignment
rng_seed_twin_tree	the random number generator seed as used in the simulation of a twin tree
root_sequence	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.
run_experiment	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
run_experiments	a list of one or more pirouette run experiments
run_if	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)
sample_interval	the interval at which the MCMC algorithm makes a measurement
seed	a random number generator seed
sequence_length	the length of each DNA sequence in an alignment
sim_phylo_fun	function that, each time when called, simulates one random tree.
sim_tral_fun	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.
sim_twal_fun	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
sim_twin_tree_fun	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
site_model	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
site_models	a list of one or more site models, as created by create_site_model
site_model_name	name of a site model
sub_chain_length	length of the sub-chain used by the Nested Sampling algorithm to estimate the marginal likelihood
subst_matrix	nucleotide substitution matrix
tree	an ultrametric phylogenetic tree of class phylo
tree_and_model	one combination of a tree and model, as created by get_tree_and_model_values
tree_and_models	one or more combination of a tree and model, as created by get_tree_and_model_values
tree_and_model_descriptions	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
tree_and_model_errors	a tibble of a tree_and_model and errors, which passes check_tree_and_model_errors
treelog_filename	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.
tree_filename	name of the phylogeny file
tree_model	model used to simulate the tree
tree_prior	a tree prior, as created by create_tree_prior
tree_priors	a list of one or more tree priors, as created by create_tree_prior
tree_prior_name	name of a tree prior
tree_type	type of tree, can be true for the true phylogeny, and twin for its twin tree
tree_types	types of tree, a vector of true for a true phylogeny, and twin for a twin tree
true_alignment	a DNA alignment, of class DNAbin
true_phylogeny	the true phylogeny; the actual evolutionary history of the species, of class phylo
true_result	result obtained from using the true tree
twin_alignment	a DNA alignment, of class DNAbin
twin_alignment_filename	name of the FASTA file the twin alignment will be saved to
twin_evidence_filename	filename to store the estimated evidences (aka marginal likelihoods) of the twin tree
twin_phylogeny	a phylogeny of class phylo
twin_model	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
twin_result	result obtained from using the twin tree
twin_tree_filename	name of the (.newick) file the twin tree will be saved to
twinning_params	can be NA if no twinning is desired, or can be the twinning parameters, as can be created by create_twinning_params
type	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.
verbose	if TRUE, show more output
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

Note

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

Author(s)

Documentation by Giovanni Laudanno, use of this function by Richèl J.C. Bilderbeek

richelbilderbeek/pirouette documentation built on Oct. 18, 2023, 3:09 p.m.