ms {phyclust}

Generating Samples under a Wright-Fisher Neutral Model of Genetic Variation

Description

This function modifies the original standalone code of ms() developed by Hudson (2002) for generating samples/coalescent trees under a Wright-Fisher neutral model.

Usage

ms(nsam = NULL, nreps = 1, opts = NULL, temp.file = NULL,
   tbs.matrix = NULL)

Arguments

nsam

number of samples/coalescent trees, usually greater than 2.

nreps

number of replications.

opts

options as the standalone version.

temp.file

temporary file for ms output.

tbs.matrix

a matrix for 'tbs' options given in opts.

Details

This function directly reuses the C code of ms by arguments as input from the opts. The options opts is followed from the original ms except nsam and nreps. Note that stdin, stdout, and pipe are all disable from opts.

For examples, options commonly used in phyclust are:

• "-T": generate trees in a neutral model.

• "-G": generate trees with a population growth rate, e.g. "-G 0.5".

These will return trees in a NEWICK format which can be read by the read.tree() of ape and passed to seqgen() to generate sequences.

temp.file allows users to specify ms output file themselves, but this file will not be deleted nor converted into R after the call to ms(). Users should take care the readings. By default, ms() uses a system temp file to store the output which is converted into R after the call and is deleted after converting.

tbs.matrix is a matrix to specify the values of tbs given in opts. See demo('simu_ms_tbs') for an example how to use this additional option. This option has been slightly tweaked by utilizing tbs options in the standalone ms. However, the output format is not the same as that in the standalone ms. Post-process is required with caution.

Value

This function returns a vector, and each element stores one line of STDOUT of ms() separated by newline. The vector stores in a class ms. The details of output format can found on the website http://home.uchicago.edu/~rhudson1/source.html and its manual.

Warning(s)

Carefully read the ms's original document before using the ms() function.

Author(s)

Hudson, R.R. (2002).

Maintain: Wei-Chen Chen [e-mail]

References

Phylogenetic Clustering Website: https://snoweye.github.io/phyclust/

Hudson, R.R. (2002) “Generating Samples under a Wright-Fisher Neutral Model of Genetic Variation”, Bioinformatics, 18, 337-338. http://home.uchicago.edu/~rhudson1/source.html

See Also

print.ms(), read.tree(), bind.tree(), seqgen().

Examples

## Not run: 
library(phyclust, quiet = TRUE)

ms()

# an ancestral tree
set.seed(1234)
(ret.ms <- ms(nsam = 3, opts = "-T -G 0.1"))
(tree.anc <- read.tree(text = ret.ms[3]))
tree.anc$tip.label <- paste("a", 1:K, sep = "")

# adjacent descendant trees to the ancestral tree
K <- 3
N <- 12
N.k <- c(3, 4, 5)
ms.dec <- NULL         # a list to store trees of ms
tree.dec <- NULL       # a list to store the trees in phylo class
tree.joint <- tree.anc
for(k in 1:K){
  ms.dec[[k]] <- ms(N.k[k], opts = "-T -G 1.0")
  tree.dec[[k]] <- read.tree(text = ms.dec[[k]][3])
  tree.dec[[k]]$tip.label <- paste("d", k, ".", 1:N.k[k], sep = "")
  tree.joint <- bind.tree(tree.joint, tree.dec[[k]],
                          where = which(tree.joint$tip.label ==
                                        paste("a", k, sep = "")))
}
str(tree.joint)

# plot trees
par(mfrow = c(2, 3))
plot(tree.anc, main = paste("anc (", K, ")", sep = ""))
axis(1)
for(k in 1:K){
  plot(tree.dec[[k]], main = paste("dec", k, " (", N.k[k], ")", sep = ""))
  axis(1)
}
plot(tree.joint, main = paste("joint (", N, ")", sep = ""))
axis(1)

# use tbs option (an example from msdoc.pdf by Hudson, R.R.)
tbs.matrix <- matrix(c(3.0, 3.5, 5.0, 8.5), nrow = 2)
ret <- ms(nsam = 5, nreps = 2, opts = "-t tbs -r tbs 1000",
          tbs.matrix = tbs.matrix)
print(ret)

## End(Not run)