% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/longitree.R
\name{longitree}
\alias{longitree}
\alias{summary.longitree}
\alias{print.longitree}
\alias{predict.longitree}
\alias{plot.longitree}
\title{Construction of a Decision Tree for Longitudinal Data}
\usage{
longitree(
  formula,
  time,
  random,
  weight = "w",
  data,
  alpha = "no",
  gamma = "no",
  cv = "no",
  maxdepth = 5,
  minbucket = 5,
  minsplit = 20,
  xval = 10
)

\method{summary}{longitree}(object, ...)

\method{print}{longitree}(x, ...)

\method{predict}{longitree}(object, ...)

\method{plot}{longitree}(x, ...)
}
\arguments{
\item{formula}{A formula specifying the model.
The response variable should be on the left side and covariates on the
right side.  Use \code{response ~ .} to include all covariates except the
time variable and the random effect, or select specific covariates such as
\code{response ~ x1 + x2}.  Time-invariant (baseline) covariates are
assumed.}

\item{time}{Character string giving the column name of the time variable.
All individuals are assumed to be observed at the same time points.}

\item{random}{Character string giving the column name of the random effect
(subject identifier).}

\item{weight}{Weight for balancing the main effect of a covariate and
its interaction with time.  A value in
\eqn{\{0.0, 0.1, \ldots, 1.0\}}: \code{1.0} evaluates only the
mean difference in the response variable between the two groups and
\code{0.0} evaluates only the difference in change over time of the
response variable between the two groups.
Set \code{weight = "w"} (the default) to select the optimal weight
from the same grid at each node.}

\item{data}{A data frame containing the variables in \code{formula} together
with the time and random-effect variables.}

\item{alpha}{Significance level used as the stopping rule for tree
growth.  A smaller value produces a more conservative (smaller) tree.
Specify a numeric value or \code{"no"} (default) if not used.
Corresponds to ST2.}

\item{gamma}{Complexity parameter for pruning.  A larger value prunes
more aggressively, yielding a smaller and simpler tree; a smaller
value retains more branches.  Specify a numeric value or \code{"no"}
(default) if not used.  Corresponds to ST3.}

\item{cv}{Set \code{"yes"} to construct the decision tree using
cross-validation, or \code{"no"} (default) otherwise.
Corresponds to ST1.}

\item{maxdepth}{Maximum depth of the tree (default 5).}

\item{minbucket}{Minimum number of subjects in a terminal node (default 5).}

\item{minsplit}{Minimum number of subjects required to attempt a split
(default 20).}

\item{xval}{Number of cross-validation folds (default 10).  Used to
compute the cross-validated coefficient of determination
(\eqn{R^2_{\mathrm{CV}}}); when \code{cv = "yes"}, also used for
final tree selection.}

\item{object}{A \code{longitree} object.}

\item{...}{Additional arguments passed to \code{\link{treeplot}}.}

\item{x}{A \code{longitree} object.}
}
\value{
An object of class \code{"longitree"}.  Use
\code{\link{summary.longitree}}, \code{\link{predict.longitree}},
or \code{\link{plot.longitree}} to inspect the results.
}
\description{
Constructs a single decision tree for longitudinal data.
The method evaluates both the main effect of a covariate and its
interaction with time, incorporating a weighting mechanism to balance
the two effects.  Three single-tree construction procedures (ST1, ST2,
ST3) are available; see Details.  For the underlying methodology, refer
to Obata and Sugimoto (2026).
}
\details{
Exactly one of \code{alpha}, \code{gamma}, or \code{cv} must be specified.
Specifying more than one will result in an error.  These correspond to the
three single-tree construction procedures:
\describe{
\item{ST1 (\code{cv = "yes"})}{Tree growth, pruning, and final tree
selection via cross-validation.}
\item{ST2 (\code{alpha})}{Tree growth with a significance threshold.
No pruning or final tree selection via cross-validation.}
\item{ST3 (\code{gamma})}{Tree growth followed by pruning with a
pre-specified complexity parameter.  No final tree selection via
cross-validation.}
}

Since the time variable is not used as a splitting variable, each terminal
node (leaf) contains the full longitudinal responses for every subject
assigned to it, allowing direct evaluation of longitudinal trajectories
within each leaf.
}
\section{Methods (by generic)}{
\itemize{
\item \code{summary(longitree)}: Print a brief summary of a \code{longitree}
object.

\item \code{print(longitree)}: Print method (calls \code{summary}).

\item \code{predict(longitree)}: Extract predicted values and terminal node
assignments from a \code{longitree} object.  Returns a data frame
with columns \code{predict} (predicted values) and
\code{terminalnode} (terminal node assignments).

\item \code{plot(longitree)}: Plot a \code{longitree} object.
A convenience wrapper around \code{\link{treeplot}}.

}}
\examples{
data(ltreedata)
# ST1: tree construction via cross-validation
result_st1 <- longitree(y ~ ., time = "time", random = "subject",
                           weight = 0.7, data = ltreedata, cv = "yes")
summary(result_st1)
predict(result_st1)
plot(result_st1)

# ST2: tree growth with a significance threshold
result_st2 <- longitree(y ~ ., time = "time", random = "subject",
                           weight = 0.1, data = ltreedata, alpha = 0.05)
summary(result_st2)
predict(result_st2)
plot(result_st2)

# ST3: pruning with a complexity parameter
result_st3 <- longitree(y ~ ., time = "time", random = "subject",
                           weight = "w", data = ltreedata, gamma = 3)
summary(result_st3)
predict(result_st3)
plot(result_st3)

}
\references{
Obata, R. and Sugimoto, T. (2026). A decision tree analysis for
longitudinal measurement data and its applications.
\emph{Advances in Data Analysis and Classification}.
\doi{10.1007/s11634-025-00665-2}
}
\seealso{
\code{\link{treeplot}}, \code{\link{longitrees}}
}
