% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/martin_lof.R
\name{RMdimMartinLof}
\alias{RMdimMartinLof}
\title{Martin-Löf Test of Unidimensionality}
\usage{
RMdimMartinLof(
  data,
  partition,
  iterations = 1000L,
  stopping = c("none", "sequential"),
  h = 50L,
  alpha = 0.05,
  parallel = TRUE,
  n_cores = NULL,
  verbose = FALSE,
  seed = NULL
)
}
\arguments{
\item{data}{A data.frame or matrix of item responses (0-based,
non-negative integers). Rows with any \code{NA} are dropped.}

\item{partition}{The hypothesised partition of items into subscales. One of:
\itemize{
\item a \strong{list} of column-name or column-index vectors, e.g.
\code{list(c("I1","I2","I3"), c("I4","I5","I6"))};
\item a \strong{vector} of length \code{ncol(data)} indicating each item's subscale
(factor, character, or integer), e.g. \code{c(1,1,1,2,2,2)}.
Each subscale must contain at least two items. Subscales must not
overlap; items not assigned to any subscale are dropped with a warning.
}}

\item{iterations}{Integer. Maximum number of Monte Carlo iterations
(default \code{1000}).}

\item{stopping}{Character. \code{"none"} (default) runs all iterations.
\code{"sequential"} uses Besag & Clifford's (1991) sequential rule: stop as
soon as \code{h} simulated statistics have exceeded the observed value. The
sequential strategy substantially reduces compute time when H0 holds
but cannot be parallelised.}

\item{h}{Integer. Sequential-stopping count threshold (default \code{50}).
Ignored when \code{stopping = "none"}.}

\item{alpha}{Numeric in (0, 1). Nominal significance level used only for
the \code{rejected} flag in the result; default \code{0.05}.}

\item{parallel}{Logical. Use parallel processing via \code{mirai} (default
\code{TRUE}). Ignored when \code{stopping = "sequential"}.}

\item{n_cores}{Integer or \code{NULL}. Number of parallel workers. When \code{NULL},
\code{getOption("mc.cores")} is checked first; if neither is set, falls back
to sequential with a warning.}

\item{verbose}{Logical. Show a progress bar (default \code{FALSE}).}

\item{seed}{Integer or \code{NULL}. Random seed for reproducibility. Items
are processed internally in a fixed (alphabetical) order, so the same
seed reproduces the same p-value regardless of how the data's columns
are arranged.}
}
\value{
A list with components:
\describe{
\item{\code{T_obs}}{Observed Martin-Löf likelihood-ratio statistic.}
\item{\code{p_value}}{Monte Carlo p-value with \code{(n_exceed + 1) / (n + 1)}
correction. The attainable p-values are \code{k / (n + 1)} for
\verb{k = 1, ..., n + 1}, so the p-value's resolution is limited by the
number of iterations: with 100 iterations the smallest attainable
value is \code{1/101 = 0.0099}. A reported p-value \emph{equal to the floor}
(see \code{p_value_floor}) means no simulated statistic reached the
observed one and should be read as "p < floor" -- the true p-value
may be much smaller; increase \code{iterations} for finer resolution.}
\item{\code{p_value_floor}}{The smallest attainable p-value,
\code{1 / (actual_iterations + 1)}.}
\item{\code{actual_iterations}}{Number of successful MC iterations
completed.}
\item{\code{rejected}}{Logical: is \code{p_value < alpha}?}
\item{\code{partition}}{Normalised partition (list of integer indices).}
\item{\code{n_subscales}}{Number of subscales.}
\item{\code{is_polytomous}}{Whether a PCM was fitted.}
\item{\code{sample_n}}{Number of complete cases analysed.}
\item{\code{n_items}}{Number of items.}
\item{\code{stopping}}{The stopping strategy used.}
\item{\code{h}}{The sequential-stopping count, or \code{NA} for \code{stopping = "none"}.}
\item{\code{T_rep}}{Numeric vector of successful MC test statistics.}
\item{\code{wle_scores}}{data.frame with one row per person and one column
per subscale (\code{subscale_1_wle}, ..., \code{subscale_D_wle}), giving Warm's
Weighted Likelihood Estimate of theta from a CML fit on each subscale
alone. Persons whose subscore equals the minimum or maximum on a
subscale produce non-finite WLEs (\code{Inf} / \code{-Inf}) and are excluded
from \code{wle_correlation} pairwise.}
\item{\code{wle_correlation}}{data.frame of pairwise Pearson correlations
between subscale WLEs, with columns \code{subscale_a}, \code{subscale_b}, \code{r},
\code{ci_lower}, \code{ci_upper} (95\% CI from \code{stats::cor.test}), \code{p_value},
and \code{n} (number of persons with finite WLEs on both subscales). One
row per pair; for D = 2, a single row. Useful as an effect-size
companion to \code{p_value} -- a rejected test with \code{r} near 1 indicates a
small effect; \code{r} clearly below 1 indicates substantive
multidimensionality.}
}
}
\description{
Likelihood-ratio test of unidimensionality against an \emph{a priori} specified
multidimensional alternative, generalised to polytomous Rasch / partial
credit models (Christensen, Bjorner, Kreiner, & Petersen, 2002). The
p-value is obtained by parametric-bootstrap (Monte Carlo) sampling under
the unidimensional null, following Christensen & Kreiner (2007), because
the asymptotic chi-square approximation is biased toward conservatism for
realistic sample sizes -- especially with polytomous items, where the
degrees of freedom can be very large.
}
\details{
This is \strong{not} a routine screening tool. The test requires an \emph{a priori}
partition of items into subscales; using it post-hoc on, e.g., the
partition suggested by \code{RMdimResidualPCA()}'s PC1 sign would inflate the
Type-I error rate. Both source papers state this explicitly.

\strong{Test statistic.} With items partitioned into D subscales, total score
\eqn{t} and subscores \eqn{(t_1, \ldots, t_D)} (Christensen et al. 2002,
eq. 22):
\deqn{T = 2\Bigl[\sum_{t_1, \ldots, t_D}
  n_{t_1, \ldots, t_D}\log(n_{t_1, \ldots, t_D}/N)
  - \sum_t n_t\log(n_t/N)
  - \ell_C(\hat{\epsilon}) + \sum_d \ell_C(\hat{\epsilon}^{(d)})\Bigr]}
where \eqn{\ell_C} is the conditional log-likelihood and the
\eqn{\hat{\epsilon}^{(d)}} are CML estimates on the d-th subscale alone.
CML fits use \code{psychotools::raschmodel()} (RM) or \code{psychotools::pcmodel()}
(PCM) for speed.

\strong{Monte Carlo sampling under H0.} Following Christensen & Kreiner (2007):
(a) sample N total scores from the empirical score distribution
\eqn{n_t/N}; (b) for each sampled score, sample an item-response vector
from the conditional distribution \eqn{p(x \mid t, \hat{\epsilon})} given
by eq. 4 of the paper. For dichotomous data the fast algorithm of
Christensen & Kreiner (2007, p. 23) is used (sample without replacement
weighted by item easinesses). For polytomous data the recursive
\eqn{\gamma}-function approach is used, with each item's response sampled
conditional on the remaining items' joint score distribution (computed via
\code{psychotools::elementary_symmetric_functions()}).

Iterations that fail (e.g., simulated dataset has an empty category for an
item) are silently dropped.

Item parameters are estimated once on the observed data and held fixed
across MC iterations. Christensen & Kreiner (2007) use the extended
likelihood function (Tjur, 1982) with the empirical score distribution as
a non-parametric estimate of the latent distribution, so no distributional
assumption about \eqn{\theta} is needed.
}
\examples{
\donttest{
set.seed(1)
# Build 2-dimensional polytomous data: 4 items per subscale, 5 categories
n     <- 400
theta1 <- rnorm(n)
theta2 <- 0.6 * theta1 + sqrt(1 - 0.6^2) * rnorm(n)
make_pcm <- function(theta, n_items, taus) {
  sapply(seq_len(n_items), function(j) {
    # ... toy simulation here
    sample(0:4, n, replace = TRUE)
  })
}
dat <- cbind(make_pcm(theta1, 4, NULL), make_pcm(theta2, 4, NULL))
colnames(dat) <- paste0("I", 1:8)

# Few iterations for a fast example; use 1000+ in real analyses
RMdimMartinLof(dat,
            partition = list(c("I1","I2","I3","I4"),
                             c("I5","I6","I7","I8")),
            iterations = 100, parallel = FALSE, seed = 1)

# Sequential stopping: stop as soon as h = 25 simulated statistics exceed
# the observed one (cuts compute time under H0).
RMdimMartinLof(dat,
            partition = c(1,1,1,1,2,2,2,2),
            iterations = 200, stopping = "sequential", h = 25,
            seed = 1)
}
}
\references{
Christensen, K. B., Bjorner, J. B., Kreiner, S., & Petersen, J. H. (2002).
Testing unidimensionality in polytomous Rasch models. \emph{Psychometrika,
67}(4), 563-574. \doi{10.1007/BF02295132}

Christensen, K. B., & Kreiner, S. (2007). A Monte Carlo approach to
unidimensionality testing in polytomous Rasch models. \emph{Applied
Psychological Measurement, 31}(1), 20-30.
\doi{10.1177/0146621605286204}

Besag, J., & Clifford, P. (1991). Sequential Monte Carlo p-values.
\emph{Biometrika, 78}(2), 301-304. \doi{10.1093/biomet/78.2.301}
}
\seealso{
\code{\link{RMdimResidualPCA}}, \code{\link{RMdimResidualPCACutoff}}
}
