% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rs_characterize.R
\name{rs_characterize}
\alias{rs_characterize}
\title{Characterize Response Shift Within Terminal Nodes of a Longitudinal GRM Tree}
\usage{
rs_characterize(
  object,
  node = NULL,
  item_level = TRUE,
  alpha = 0.05,
  p_adjust = "bonferroni",
  global_p_adjust = "bonferroni",
  rs_threshold = 0.3,
  verbose = TRUE,
  ...
)
}
\arguments{
\item{object}{A \code{longitudinal_grmtree} object fitted by
\code{\link{longitudinal_grmtree}}.}

\item{node}{Optional integer vector of terminal node IDs to analyze. If
\code{NULL} (default), all terminal nodes are analyzed.}

\item{item_level}{Logical. If \code{TRUE} (default), perform item-level RS
testing by sequentially freeing one item at a time from the constrained
model. Only performed for nodes where the omnibus test is significant.}

\item{alpha}{Numeric significance level for RS tests. Default is 0.05.
Used for both omnibus and item-level significance decisions (after any
p-value adjustments).}

\item{p_adjust}{Character string specifying the method for adjusting
item-level p-values \strong{within each node}. Controls the error rate
when testing multiple items for RS within a single subgroup. Options:
\code{"bonferroni"} (default), \code{"holm"}, \code{"BH"}
(Benjamini-Hochberg), \code{"BY"}, \code{"fdr"}, \code{"hochberg"},
\code{"hommel"}, or \code{"none"}. See \code{\link[stats]{p.adjust}}.}

\item{global_p_adjust}{Character string specifying the method for adjusting
omnibus RS p-values \strong{across terminal nodes}. Controls the
family-wise error rate when testing RS in multiple subgroups. Options
are the same as \code{p_adjust}. Default is \code{"bonferroni"}.
The \code{RS_detected} column in the global results is updated based
on adjusted p-values. Only applied when there are 2 or more nodes.}

\item{rs_threshold}{Numeric threshold for classifying the magnitude of
parameter change in RS type determination, on the IRT parameter scale.
Default is 0.3. A discrimination difference exceeding this threshold
indicates reprioritization; a maximum threshold difference exceeding
this indicates recalibration. Larger values produce more conservative
classifications (fewer items classified as showing meaningful RS).
Items that are statistically significant but below this threshold are
classified as \code{"Significant (small effect)"}.}

\item{verbose}{Logical. If \code{TRUE} (default), print progress messages
including log-likelihoods, LRT statistics, and RS classifications for
each node during processing.}

\item{...}{Additional arguments passed to \code{\link[mirt]{mirt}} during
model fitting.}
}
\value{
A list of class \code{"rs_characterization"} containing:
\describe{
\item{\code{global}}{A \code{data.frame} with one row per terminal node
and columns:
\describe{
\item{\code{Node}}{Terminal node ID}
\item{\code{n}}{Sample size in the node}
\item{\code{LL_constrained}}{Log-likelihood of the constrained
(no-RS) model}
\item{\code{LL_unconstrained}}{Log-likelihood of the unconstrained
(RS-allowed) model}
\item{\code{LRT_chi2}}{Likelihood ratio test statistic:
\eqn{-2(LL_{con} - LL_{uncon})}}
\item{\code{LRT_df}}{Degrees of freedom (number of freed
constraints)}
\item{\code{LRT_p}}{Raw p-value from chi-squared distribution}
\item{\code{LRT_p_adj}}{Adjusted p-value (present only if
\code{global_p_adjust != "none"} and there are 2+ nodes)}
\item{\code{RS_detected}}{Logical: whether RS is detected at
the specified \code{alpha} level (uses adjusted p if available)}
\item{\code{pseudo_R2}}{McFadden's pseudo R-squared:
\eqn{1 - LL_{uncon}/LL_{con}}}
\item{\code{AIC_diff}}{AIC difference:
\eqn{AIC_{con} - AIC_{uncon}}. Positive values indicate the
unconstrained model fits better after parsimony penalty.}
\item{\code{mu_T2}}{Latent mean shift at T2 from the constrained
model. Positive = improvement, negative = decline.}
\item{\code{sigma2_T2}}{Latent variance at T2}
\item{\code{cor_T1_T2}}{Correlation between latent traits at T1
and T2, reflecting stability of individual differences}
\item{\code{converged_constrained}}{Logical: whether the
constrained model converged}
\item{\code{converged_unconstrained}}{Logical: whether the
unconstrained model converged}
}
}
\item{\code{item_level}}{A \code{data.frame} with item-level RS test
results (one row per item per node where omnibus RS was detected),
with columns:
\describe{
\item{\code{Node}}{Terminal node ID}
\item{\code{Item}}{Item number (1 to \code{n_items})}
\item{\code{LRT_chi2}}{LRT statistic for freeing this item}
\item{\code{LRT_df}}{Degrees of freedom (1 discrimination +
thresholds for this item)}
\item{\code{LRT_p}}{Raw p-value}
\item{\code{LRT_p_adj}}{Adjusted p-value (if \code{p_adjust !=
          "none"})}
\item{\code{RS_type}}{Classification: \code{"Recalibration"},
\code{"Reprioritization"}, \code{"Both"},
\code{"Significant (small effect)"}, or \code{"None"}}
}
\code{NULL} if no nodes showed significant omnibus RS or
\code{item_level = FALSE}.
}
\item{\code{parameters}}{A named list (one element per node) of lists
containing \code{constrained} and \code{unconstrained} item parameter
matrices (IRT parameterization with discrimination \code{a1}/\code{a2}
and thresholds \code{b1}, ..., \code{bK}).}
\item{\code{n_items}}{Number of items per time point.}
\item{\code{alpha}}{Significance level used.}
\item{\code{p_adjust}}{Item-level p-value adjustment method.}
\item{\code{global_p_adjust}}{Omnibus p-value adjustment method.}
\item{\code{rs_threshold}}{RS classification threshold.}
}
}
\description{
After fitting a \code{\link{longitudinal_grmtree}} (Phase 1), this function
performs Phase 2: post-hoc response shift (RS) characterization within each
terminal node. For each subgroup identified by the tree, it compares the
constrained model (no RS: item parameters equal across time) to an
unconstrained model (item parameters free across time) using likelihood
ratio tests (LRTs), then identifies which specific items exhibit response
shift and classifies the type of shift.
}
\details{
\subsection{The Two-Phase Framework}{

The Longitudinal GRMTree operates as an integrated two-phase method:

\strong{Phase 1 (\code{\link{longitudinal_grmtree}}):} Embeds a constrained
longitudinal GRM (item parameters equal across T1 and T2) within
model-based recursive partitioning. The tree identifies patient subgroups
requiring different constrained measurement models. This ensures that
subsequent RS testing is conducted within measurement-homogeneous groups.

\strong{Phase 2 (this function):} Within each terminal node, relaxes the
equality constraint and tests whether item parameters actually change over
time. This separates between-group measurement heterogeneity (captured by
the tree) from within-group temporal change (response shift).
}

\subsection{Omnibus RS Test}{

For each terminal node, the function fits two models to the node's data:
\enumerate{
\item \strong{Constrained model:} Item parameters are equal across T1
and T2 (no response shift). This model has the same structure as the
model fitted during Phase 1.
\item \strong{Unconstrained model:} Item parameters are free to differ
between T1 and T2 (response shift allowed). All equality constraints
on discrimination and threshold parameters are removed.
}

The likelihood ratio test statistic is:
\deqn{\chi^2 = -2(LL_{constrained} - LL_{unconstrained})}

with degrees of freedom equal to the number of freed constraints
(typically \eqn{M \times K} for \eqn{M} items with \eqn{K-1} thresholds
each, plus \eqn{M} discrimination parameters).
}

\subsection{Item-Level RS Testing}{

When the omnibus test is significant, each item is tested individually by
freeing only that item's constraints while keeping all other items
constrained. The LRT compares the fully constrained model to the partially
constrained model with one item freed. This identifies which specific
items contribute to the overall response shift.
}

\subsection{RS Type Classification}{

For items showing statistically significant RS (after p-value adjustment),
the type is classified by examining the freed item's T1 vs T2 parameters
from the partially constrained model:

\describe{
\item{\strong{Recalibration}}{Maximum absolute threshold difference
exceeds \code{rs_threshold}. Interpretation: the patient's internal
standards for endorsing response categories changed over time
(Sprangers & Schwartz, 1999).}
\item{\strong{Reprioritization}}{Absolute discrimination difference
exceeds \code{rs_threshold}. Interpretation: the item's relationship
to the underlying latent construct changed over time --- the item
became more or less central to the construct.}
\item{\strong{Both}}{Both discrimination and threshold changes exceed
\code{rs_threshold}.}
\item{\strong{Significant (small effect)}}{The LRT is significant but
neither parameter change exceeds \code{rs_threshold}. The RS is
statistically detectable but small in magnitude.}
}
}

\subsection{Hierarchical P-Value Correction}{

The function implements a two-level correction strategy:
\enumerate{
\item \strong{Across nodes (omnibus):} \code{global_p_adjust} controls
the family-wise error rate for the question "in which subgroups does
RS occur?" Default is Bonferroni.
\item \strong{Within nodes (item-level):} \code{p_adjust} controls the
error rate for the question "which items exhibit RS within a given
subgroup?" Default is Bonferroni; FDR (Benjamini-Hochberg) is
recommended for exploratory analyses.
}
}

\subsection{Effect Size Measures}{

\describe{
\item{McFadden's pseudo R-squared}{\eqn{1 - LL_{uncon}/LL_{con}}.
Inherently small (~0.02) in IRT models because item parameters
account for only a fraction of the total likelihood. Values should
be compared across nodes rather than interpreted in absolute terms.}
\item{AIC difference}{\eqn{AIC_{con} - AIC_{uncon}}. Positive values
indicate the unconstrained model fits better even after penalizing
for additional parameters. Negative values suggest the constrained
model is preferred (response shift is not substantial enough to
justify the additional parameters).}
}
}
}
\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")
  )

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

  # Phase 2: characterize response shift within each subgroup
  rs <- rs_characterize(ltree, p_adjust = "fdr",
    global_p_adjust = "bonferroni")
  print(rs)

  # Phase 2: Characterize RS
  # Default: Bonferroni at both levels, threshold = 0.3
  rs <- rs_characterize(ltree)

  # Recommended: FDR for item-level, Bonferroni for omnibus
  rs <- rs_characterize(ltree,
    p_adjust = "fdr",
    global_p_adjust = "bonferroni",
    rs_threshold = 0.3
  )

  # No omnibus correction (each node tested independently)
  rs <- rs_characterize(ltree, global_p_adjust = "none")

  # More conservative RS classification
  rs <- rs_characterize(ltree, rs_threshold = 0.5)

  # View results
  print(rs)

  # Access components
  rs$global         # Omnibus results per node
  rs$item_level     # Item-level results
  rs$parameters     # Raw parameter matrices
\dontshow{\}) # examplesIf}
}
\references{
Sprangers, M. A., & Schwartz, C. E. (1999). Integrating response shift
into health-related quality of life research. \emph{Social Science &
Medicine}, 48(11), 1507--1515.

Benjamini, Y., & Hochberg, Y. (1995). Controlling the false discovery
rate: a practical and powerful approach to multiple testing. \emph{Journal
of the Royal Statistical Society: Series B}, 57(1), 289--300.
}
\seealso{
\code{\link{longitudinal_grmtree}} for Phase 1 (tree fitting),
\code{\link{print.rs_characterization}} for the print method,
\code{\link{prepare_longitudinal_data}} for data preparation,
\code{\link[stats]{p.adjust}} for p-value adjustment methods
}
\author{
Olayinka Imisioluwa Arimoro \email{olayinka.arimoro@ucalgary.ca},
Lisa M. Lix, Tolulope T. Sajobi
}
