% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sim.morpho.R
\name{sim.morpho}
\alias{sim.morpho}
\title{Simulate characters along branches in a tree}
\usage{
sim.morpho(
  tree = NULL,
  time.tree = NULL,
  k = 2,
  trait.num,
  partition = NULL,
  br.rates = NULL,
  root.state = NULL,
  variable = FALSE,
  full.states = FALSE,
  parsimony = NULL,
  ACRV = NULL,
  alpha.gamma = 1,
  ACRV.ncats = 4,
  meanlog = NULL,
  sdlog = NULL,
  define.ACRV.rates = NULL,
  ancestral = TRUE,
  fossil = NULL,
  define.Q = NULL
)
}
\arguments{
\item{tree}{A phylogenetic tree (class \code{"phylo"}) with branches
representing genetic distance.}

\item{time.tree}{A phylogenetic tree (class \code{"phylo"}) with branches
representing time.}

\item{k}{Integer (>= 2). Number of trait states. Can be a vector if using
partitions.}

\item{trait.num}{Integer (> 0). The total number of traits to simulate.}

\item{partition}{Integer vector. Specifies the number of traits per
partition. Must sum to \code{trait.num}.}

\item{br.rates}{Numeric. Clock rates per branch. Can be a single value
(strict clock) or a numeric vector of length equal to the number of
branches in the tree, one rate per branch in the same order as
\code{tree$edge}. Custom vectors of rates can be provided directly here,
for example rates simulated using \code{simclock::relaxed.tree()}.}

\item{root.state}{Integer. The root state at the start of the simulation.
Must be within the range of states implied by \code{k}.}

\item{variable}{Logical. If \code{TRUE}, simulate only varying characters
(MkV model). Default is \code{FALSE}.}

\item{full.states}{Logical. If \code{TRUE}, ensures that all character
states specified by \code{k} are present in at least one tip for each
trait. Default is \code{FALSE}.}

\item{parsimony}{Character. If \code{"standard"}, retain only characters
where at least two states each occur in two or more taxa; autapomorphic
states are tolerated. If \code{"strict"}, every observed state must occur
in two or more taxa, excluding characters with any autapomorphic states
entirely. If \code{NULL}, no parsimony filter is applied. Default is
\code{NULL}.}

\item{ACRV}{Character. Among-character rate variation model. One of
\code{"gamma"}, \code{"lgn"}, \code{"user"}, or \code{NULL}.
\code{"gamma"} draws rates from a discretized gamma distribution (Yang
1994); requires \code{ACRV.ncats} and \code{alpha.gamma}.
\code{"lgn"} draws rates from a discretized lognormal distribution
(Wagner 2012); requires \code{ACRV.ncats}, \code{meanlog}, and
\code{sdlog}. \code{"user"} uses user-supplied rates via
\code{define.ACRV.rates}. \code{NULL} simulates all traits under the
same rate. Default is \code{NULL}.}

\item{alpha.gamma}{Numeric. Shape parameter \eqn{\alpha} for the gamma
distribution. Default is 1.}

\item{ACRV.ncats}{Integer. Number of discrete rate categories for
among-character rate variation.}

\item{meanlog}{Numeric. Mean of the lognormal distribution on the log
scale. Required when \code{ACRV = "lgn"}.}

\item{sdlog}{Numeric. Standard deviation of the lognormal distribution on
the log scale. Required when \code{ACRV = "lgn"}.}

\item{define.ACRV.rates}{Numeric vector. User-supplied rate categories.
Required when \code{ACRV = "user"}.}

\item{ancestral}{Logical. If \code{TRUE}, return the states at all
ancestral nodes. Default is \code{TRUE}.}

\item{fossil}{A fossil object from \code{FossilSim} to simulate
morphological characters for sampled ancestors.}

\item{define.Q}{Numeric matrix. A custom transition rate matrix Q for
simulation. Must be square and rows must sum to zero.}
}
\value{
An object of class `morpho`, with the following components:
\describe{
  \item{sequences}{A list containing up to 3 elements: morphological data for the `tips`
  of the tree, the `nodes`, and, if provided, the sampled ancestors (`SA`). For `SA`,
  the naming scheme differs from that of `FossilSim`: the morphological data are named
  using the specimen number (`data$fossil$specimen`) and the branch number along which
  the fossil was sampled.}

  \item{tree}{A list containing up to 3 elements: the `EvolTree` (branch lengths in
  genetic distance), the `TimeTree` (branch lengths in time units), and `BrRates`
  (the evolutionary rate per branch).}

  \item{model}{Information about the model used to simulate the data. `Specified`
  states the exact model used per partition, as well as the number of traits and
  character states respectively. `RateVar` contains the relative rates used to simulate
  the data, and `RateVarTrait` contains information about which rate category was used
  to simulate each trait. These values are listed from lowest rate (1) to highest.}

  \item{transition_history}{A list containing *n* data frames, where *n* is the number
  of simulated traits. Each data frame contains information about transitions that
  occurred for that trait, including the branch number (`edge`), the new state number (`state`),
  and the point along the branch where the transition occurred (`hmin`).}

  \item{root.states}{A vector of root states for each trait.}

  \item{fossil}{The fossil object provided to `morphsim` from `FossilSim`. The naming
  scheme therefore matches that of `FossilSim`.}
}
}
\description{
This function simulates discrete character data along the branches of a
phylogenetic tree using a continuous-time Markov chain. It implements the
Mk model and its extensions (Lewis 2001), including among-character rate
variation (ACRV) using discretized gamma distributions (Yang 1994) or
lognormal distributions (Wagner 2012), following the implementation
described in Capobianco and Hohna (2025). It can be used with either a
time tree or a tree with branch lengths in evolutionary distance. If using
a time tree, branch rates can be specified either as a single value for all
branches or as a vector with different rates per branch. If no branch rates
are specified a default of 0.1 is applied to all branches.
}
\examples{
# simulated tree
phy <- ape::rtree(10)

# simulate characters along the branches of the tree
morpho_data <-  sim.morpho(tree = phy,
                           k = c(2,3,4),
                           trait.num = 20,
                           partition = c(10,5,5),
                           ACRV = "gamma",
                           ACRV.ncats = 4,
                           variable = TRUE,
                           ancestral = TRUE,
                           define.Q = NULL)

# To simulate ordered characters:
# First define a Q-matrix. The following is for ordered characters where transitions can only occur
# between states 0 and 1 and 1 and 2

ord_Q <- matrix(c(
-0.5, 0.5, 0.0,
0.3333333, -0.6666667, 0.3333333,
0.0, 0.5, -0.5
), nrow = 3, byrow = TRUE)

# This Q matrix can be then used to simulate character data.

morpho_data <- sim.morpho(tree = phy,
                          k = 3,
                          trait.num = 20,
                          ancestral = TRUE,
                          ACRV = "gamma",
                          variable = TRUE,
                          ACRV.ncats = 4,
                         define.Q = ord_Q)
}
\references{
Lewis, P.O. (2001) A likelihood approach to estimating phylogeny from
discrete morphological character data. \emph{Systematic Biology} 50:913-925.

Yang, Z. (1994) Maximum likelihood phylogenetic estimation from DNA
sequences with variable rates over sites: approximate methods.
\emph{Journal of Molecular Evolution} 39:306-314.

Wagner, P.J. (2012) Modelling rate distributions using character
compatibility: implications for morphological evolution among fossil
invertebrates. \emph{Biology Letters} 8:143-146.

Capobianco, A. and Hohna, S. (2025) On the MkV model with
among-character rate variation. \emph{Systematic Biology}.
}
