PLD_interface: Model parameters and internal locations estimations

In phyloland: Modelling Competitive Exclusion and Limited Dispersal in a Statistical Phylogeographic Framework

Description

Function that estimates model parameters, genealogies and internal locations through Bayesian Markov chain Monte Carlo (MCMC) algorithm.

Usage

PLD_interface(fileTREES, fileDATA, num_step = 1e+05, freq = 100, 
burnin = 0, ess_lim = 100, sigma = NA, lambda = NA, tau = NA, 
num_step_sigma = 1, num_step_lambda = 1, num_step_tau = 1, 
id_filena = NA, pattern_trees_likelihood = "treeLikelihood", 
names_locations = NA)

Arguments

fileTREES	a character string that specifies the name of the file containing the phylogenetic trees. A Nexus file (e.g. BEAST output) with tips names (no space characters allowed), the phylogenetic trees and the trees likelihood. If only one tree is contained in the file, the genealogies are not sampled in the MCMC.
fileDATA	a character string that specifies the name of the file containing the tips locations : a text file with 3 columns (separated by tabs). The first one with the tips names (the same as in fileTrees), the second one with the location latitudes and the last one with the location longitudes (both in decimal degrees). No header.
num_step	a strictly positive integer specifying the length of the Markov Chain (the number of MCMC steps). Suggested values : 50 000 - 100 000.
freq	a strictly positive integer specifying how often the sampled model parameters and the locations are saved. Suggested values : 50 - 100.
burnin	a strictly positive integer specifying the number of trees dropped from the file fileTREES. Suggested value : 10% of the total number of trees, 0 in case of only one tree.
ess_lim	a strictly positive integer specifying the Effective Sample Size. The MCMC stops when the ess of all parameters reach this value.
sigma	a vector of two elements, strictly positive values specifying the standard deviation of the normal distribution for dispersal steps in each dimension. Default is NA: the 2 sigma parameters are estimated in the MCMC. Alternatively, if values are specified the sigma parameters are not estimated by the MCMC.
lambda	a strictly positive value specifying the probability of migrating to an occupied location. Default is NA: the lambda parameter is estimated in the MCMC. Alternatively, if a value is specified the lambda parameter is not estimated by the MCMC. A lambda value equal to 1 indicates that competitive exclusion did not impact the colonization process.
tau	a strictly positive value specifying the overall dispersal rate. Default is NA: the tau parameter is estimated in the MCMC. Alternatively, if a value specified the tau parameter is not estimated by the MCMC.
num_step_sigma	a strictly positive integer specifying how many times the sigma parameters are sampled at each MCMC step.
num_step_lambda	a strictly positive integer specifying how many times the lambda parameter is sampled at each MCMC step.
num_step_tau	a strictly positive integer specifying how many times the tau parameter is sampled at each MCMC step.
id_filena	an optional character string specifying the ID for the output files.
pattern_trees_likelihood	a character string specifying the text pattern to retrieve the trees likelihood in fileTREES.
names_locations	a vector of character strings that specifies the location names, in the same order as in fileDATA.

Details

MCMC runs stop when the num_step is reached or when the ess of all estimated parameters equal ess_lim.

The respective ess for estimating convergence of the chains regarding each parameter is calculated by monitoring the autocorrelation between successive sampled states in the MCMC.

Value

an object of class "phyloland" with the following components:

trees	an object of class "multiPhylo" or "phylo" (package ape) containing the trees sampled in the MCMC. If the ess_lim is not reached, the number of trees is num_step/freq.
locations	a matrix containing the internal locations sampled in the MCMC and the tips locations (columns) for each sampled tree(rows).
tips	a vector of character strings containing the tips names (from fileTREES and fileDATA).
space	a matrix containing the unique locations from fileDATA.
mcmc	a list containing the posterior distributions of each parameters.
sigma_limit	a vector indicating the threshold for sigma below which limited dispersal occurs.

phyloland documentation built on May 2, 2019, 6:46 a.m.