optM: optM function

In OptM: Estimating the Optimal Number of Migration Edges from 'Treemix'

Description

Load a folder of .llik files from the program Treemix and determine the optimal number of migration edges to include

Usage

optM(
  folder,
  orientagraph = F,
  tsv = NULL,
  method = "Evanno",
  ignore = NULL,
  thresh = 0.05,
  ...
)

Arguments

folder	A character string of the path to a directory containing .llik, .cov.gz and .modelcov.gz files produced by Treemix
orientagraph	A logical indicating whether the files were produced from Treemix (FALSE) or OrientAGraph (TRUE). Default = F
tsv	a string defining the name of the tab-delimited output file. If NULL (default), then no data file is produced.
method	a string containing the method to use, either "Evanno", "linear", or "SiZer". Default is "Evanno".
ignore	a numeric vector of whole numbers indicating migration edges to ignore. Useful when running Treemix on a prebuilt tree (ignore = 0). Default is NULL.
thresh	a numeric value between 0 and 1 for the threshold to use for the proportion of increase in likelihood that defines when a plateau is reached. Default is 0.05 (5%), only applicable for method = "linear".
...	other options sent to the function "SiZer" - see the R package 'SiZer'

Value

If method = "Evanno": A data frame with 17 columns summarizing the results for each migration edge (rows).

The columns are: "m" - number of migration edges from the model; "runs" = number of iterations for "m"; "mean(Lm)" - mean log likelihood across runs; "sd(Lm)" - standard deviation of log likelihood across runs; "min(Lm)" - minimum log likelihood across runs; "max(Lm)" - maximum log likelihood across runs; "L'(m)" - first-order rate of change in log likelihood; "sdL'(m)" - standard deviation of first-order rate of change in log likelihood; "minL'(m)" - minimum first-order rate of change in log likelihood; "maxL'(m)" - maximum first-order rate of change in log likelihood; "L”(m)" - second-order rate of change in log likelihood; "sdL”(m)" - standard deviation of the second-order rate of change in log likelihood; "minL”(m)" - minimum second-order rate of change in log likelihood; "maxL”(m)" - maximum second-order rate of change in log likelihood; "Deltam" - the ad hoc deltaM statistic (secord order rate of change in log likelihood); "mean(f)" - mean proportion of variation explained by the models; "sd(f)" - standard deviation of the proportion of variation explained by the models

If method = "linear": A list containing 5 elements:

$out - a data frame with the name of each model, the degrees of freedom (df), the Akaike information criterion (AIC), the deltaAIC, and the optimal estimate for m based on the model.

$PiecewiseLinear - the piecewise linear model object

$BentCable - the bent cable model object

$SimpleExponential - the simple exponential model object

$NonLinearLeastSquares - the NLS model object

If method = "SiZer": an object of class "SiZer" (see the R package 'SiZer' for more information)

Examples

# Load a folder of simulated test data for m = 3
folder <- system.file("extdata", package = "OptM")
test.optM = optM(folder)

# To view the various linear modeling estimates:
   # test.linear = optM(folder, method = "linear")

# To view the results from the SiZer package:
   # test.sizer = optM(folder, method = "SiZer")

Example output

Finished reading .llik, .modelcov.goz, and .cov.gz files.

No output file will be saved. To save an output file, run with 'tsv = "file.tsv"'

m ranges between 0 and 10.

The average number of iterations per m (not including m = 0) was 10.

Make sure these values are correct...

Analyzing the treemix results using the Evanno method.

Finished calculating delta m.

The maximum value for delta m was 73.4671 at m = 3 edges.

Finished all calculations for the Evanno method.

OptM documentation built on Oct. 1, 2021, 1:06 a.m.