% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/long-grmtree-plot.R
\name{plot.longitudinal_grmtree}
\alias{plot.longitudinal_grmtree}
\title{Plot Method for Longitudinal GRM Tree Objects}
\usage{
\method{plot}{longitudinal_grmtree}(
  x,
  type = "regions",
  tnex = 2L,
  drop_terminal = TRUE,
  names = FALSE,
  abbreviate = TRUE,
  ...
)
}
\arguments{
\item{x}{A \code{longitudinal_grmtree} object.}

\item{type}{Type of terminal node plot. Currently only \code{"regions"}
is supported for the longitudinal model.}

\item{tnex}{Numeric scaling factor for terminal node extension (default: 2).}

\item{drop_terminal}{Logical indicating whether to drop terminal node IDs
(default: TRUE).}

\item{names}{Logical or character vector. If \code{TRUE}, use item names
from the response matrix. If a character vector, use as custom labels.
If \code{FALSE} (default), use numeric indices 1 through n_items.}

\item{abbreviate}{Logical or numeric. If \code{TRUE}, abbreviate item
names. If numeric, abbreviate to that many characters.}

\item{...}{Additional arguments passed to the terminal panel function.}
}
\value{
Invisibly returns the tree object. Called for its side effect of
producing a plot.
}
\description{
Visualizes a longitudinal GRM tree with threshold region plots in terminal
nodes. Unlike the cross-sectional \code{\link[grmtree]{plot.grmtree}},
this method displays only the unique item parameters (T1 items), since
the constrained longitudinal model enforces equal parameters across T1
and T2 within each node.
}
\details{
The region plot displays threshold parameters as colored horizontal bands
for each item within each terminal node. Darker shading represents lower
response categories and lighter shading represents higher categories.
The height of each band corresponds to the range of the latent trait
over which that response category is most likely.

Because the constrained longitudinal GRM enforces
\eqn{a_{m,T1} = a_{m,T2}} and \eqn{b_{k,m,T1} = b_{k,m,T2}}, the T1
and T2 item parameters are identical. The plot therefore shows only the
\code{n_items} unique items rather than all \code{2 * n_items} columns
in the response matrix.
}
\examples{
\dontshow{if (interactive()) withAutoprint(\{ # examplesIf}
library(grmtree)

# Load the synthetic longitudinal data
data("grmtree_long_data", package = "grmtree")

  # Prepare the wide-format response matrix
  items_t1 <- c("MOS_Listen", "MOS_Info", "MOS_Advice_Crisis", "MOS_Confide",
                "MOS_Advice_Want", "MOS_Fears", "MOS_Personal", "MOS_Understand")
  ld <- prepare_longitudinal_data(
    data = grmtree_long_data,
    items_t1 = items_t1,
    items_t2 = paste0(items_t1, "_year1"),
    covariates = c("sex", "age", "residency", "job",
                   "education", "comorbidity_count", "ever_smoker")
  )

  # Phase 1: fit the longitudinal GRM tree
  ltree <- longitudinal_grmtree(
    resp_wide ~ sex + age + residency + job +
      education + comorbidity_count + ever_smoker,
    data = ld, n_items = 8,
    control = grmtree.control(minbucket = 200)
  )

  # Region plot with numeric labels
  plot(ltree)

  # Region plot with item names
  plot(ltree, names = TRUE)

  # Custom labels
  plot(ltree, names = c("Listen", "Info", "Crisis",
    "Confide", "Advice", "Fears", "Personal", "Understand"))
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link{longitudinal_grmtree}} for fitting the tree,
\code{\link[grmtree]{plot.grmtree}} for cross-sectional tree plots
}
