R: Generating Samples under a Wright-Fisher Neutral Model of...

ms {phyclust} | R Documentation

## 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 wccsnow@gmail.com

### 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)

[Package phyclust version 0.1-30 Index]