man/skyline.Rd

   1 \name{skyline}
   2 \alias{skyline}
   3 \alias{skyline.phylo}
   4 \alias{skyline.coalescentIntervals}
   5 \alias{skyline.collapsedIntervals}
   6 \alias{find.skyline.epsilon}
   7
   8 \title{Skyline Plot Estimate of Effective Population Size}
   9 \usage{
  10 skyline(x, \dots)
  11 \method{skyline}{phylo}(x, \dots)
  12 \method{skyline}{coalescentIntervals}(x, epsilon=0, \dots)
  13 \method{skyline}{collapsedIntervals}(x, old.style=FALSE, \dots)
  14 find.skyline.epsilon(ci, GRID=1000, MINEPS=1e-6, \dots)
  15 }
  16 \arguments{
  17   \item{x}{Either an ultrametric tree (i.e. an object of class
  18     \code{"phylo"}), or coalescent intervals (i.e. an object of class
  19     \code{"coalescentIntervals"}), or collapsed coalescent intervals
  20     (i.e. an object of class \code{"collapsedIntervals"}).}
  21   \item{epsilon}{collapsing parameter that controls the amount of smoothing
  22     (allowed range: from \code{0} to \code{ci$total.depth}, default value: 0). This is the same parameter as in
  23     \link{collapsed.intervals}.}
  24
  25   \item{old.style}{Parameter to choose between two slightly different variants of the
  26      generalized skyline plot (Strimmer and Pybus, pers. comm.). The default value \code{FALSE} is
  27      recommended.}
  28
  29   \item{ci}{coalescent intervals (i.e. an object of class \code{"coalescentIntervals"})}
  30
  31   \item{GRID}{Parameter for the grid search for \code{epsilon} in \code{find.skyline.epsilon}.}
  32
  33   \item{MINEPS}{Parameter for the grid search for \code{epsilon} in \code{find.skyline.epsilon}.}
  34
  35   \item{\dots}{Any of the above parameters.}
  36
  37 }
  38 \description{
  39
  40  \code{skyline} computes the \emph{generalized skyline plot} estimate of effective population size
  41  from an estimated phylogeny.  The demographic history is approximated by
  42  a step-function.  The number of parameters of the skyline plot (i.e. its smoothness)
  43  is controlled by a parameter \code{epsilon}.
  44
  45  \code{find.skyline.epsilon} searches for an optimal value of the \code{epsilon} parameter,
  46  i.e. the value that maximizes the AICc-corrected log-likelihood (\code{logL.AICc}).
  47 }
  48
  49 \details{
  50 \code{skyline} implements the \emph{generalized skyline plot}  introduced in
  51 Strimmer and Pybus (2001).  For \code{epsilon = 0} the
  52 generalized skyline plot degenerates to the
  53 \emph{classic skyline plot} described in
  54 Pybus et al. (2000).  The latter is in turn directly related to lineage-through-time plots
  55 (Nee et al., 1995).
  56 }
  57
  58 \value{
  59 \code{skyline} returns an object of class \code{"skyline"} with the following entries:
  60
  61   \item{time}{ A vector with the time at the end of each coalescent
  62     interval (i.e. the accumulated interval lengths from the beginning of the first interval
  63     to the end of an interval)}
  64
  65   \item{interval.length}{ A vector with the length of each
  66     interval.}
  67
  68   \item{population.size}{A vector with the effective population size of each interval.}
  69
  70   \item{parameter.count}{ Number of free parameters in the skyline plot.}
  71   \item{epsilon}{The value of the underlying smoothing parameter.}
  72
  73   \item{logL}{Log-likelihood of skyline plot (see Strimmer and Pybus, 2001).}
  74
  75   \item{logL.AICc}{AICc corrected log-likelihood (see Strimmer and Pybus, 2001).}
  76
  77 \code{find.skyline.epsilon} returns the value of the \code{epsilon} parameter
  78    that maximizes \code{logL.AICc}.
  79 }
  80
  81 \author{Korbinian Strimmer (\url{http://www.stat.uni-muenchen.de/~strimmer/})}
  82
  83 \seealso{
  84 \code{\link{coalescent.intervals}}, \code{\link{collapsed.intervals}},
  85 \code{\link{skylineplot}}, \code{\link{ltt.plot}}.
  86 }
  87
  88
  89 \references{
  90   Strimmer, K. and Pybus, O. G. (2001) Exploring the demographic history
  91   of DNA sequences using the generalized skyline plot. \emph{Molecular
  92     Biology and Evolution}, \bold{18}, 2298--2305.
  93
  94   Pybus, O. G, Rambaut, A. and Harvey, P. H. (2000) An integrated
  95   framework for the inference of viral population history from
  96   reconstructed genealogies. \emph{Genetics}, \bold{155}, 1429--1437.
  97
  98   Nee, S., Holmes, E. C., Rambaut, A. and Harvey, P. H. (1995) Inferring
  99   population history from molecular phylogenies. \emph{Philosophical
 100     Transactions of the Royal Society of London. Series B. Biological
 101     Sciences}, \bold{349}, 25--31.
 102 }
 103
 104 \examples{
 105 # get tree
 106 data("hivtree.newick") # example tree in NH format
 107 tree.hiv <- read.tree(text = hivtree.newick) # load tree
 108
 109 # corresponding coalescent intervals
 110 ci <- coalescent.intervals(tree.hiv) # from tree
 111
 112 # collapsed intervals
 113 cl1 <- collapsed.intervals(ci,0)
 114 cl2 <- collapsed.intervals(ci,0.0119)
 115
 116
 117 #### classic skyline plot ####
 118 sk1 <- skyline(cl1)        # from collapsed intervals
 119 sk1 <- skyline(ci)         # from coalescent intervals
 120 sk1 <- skyline(tree.hiv)   # from tree
 121 sk1
 122
 123 plot(skyline(tree.hiv))
 124 skylineplot(tree.hiv) # shortcut
 125
 126 plot(sk1, show.years=TRUE, subst.rate=0.0023, present.year = 1997)
 127
 128 #### generalized skyline plot ####
 129
 130 sk2 <- skyline(cl2)              # from collapsed intervals
 131 sk2 <- skyline(ci, 0.0119)       # from coalescent intervals
 132 sk2 <- skyline(tree.hiv, 0.0119) # from tree
 133 sk2
 134
 135 plot(sk2)
 136
 137
 138 # classic and generalized skyline plot together in one plot
 139 plot(sk1, show.years=TRUE, subst.rate=0.0023, present.year = 1997, col=c(grey(.8),1))
 140 lines(sk2,  show.years=TRUE, subst.rate=0.0023, present.year = 1997)
 141 legend(.15,500, c("classic", "generalized"), col=c(grey(.8),1),lty=1)
 142
 143
 144 # find optimal epsilon parameter using AICc criterion
 145 find.skyline.epsilon(ci)
 146
 147 sk3 <- skyline(ci, -1) # negative epsilon also triggers estimation of epsilon
 148 sk3$epsilon
 149 }
 150 \keyword{manip}