% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nparLD.R
\name{nparLD}
\alias{nparLD}
\title{Nonparametric Analysis of Longitudinal Data}
\usage{
nparLD(
  formula,
  data,
  subject,
  replicate = NULL,
  cell.weights = c("subjects", "observations"),
  effect = c("unweighted", "weighted"),
  hypothesis = c("H0F", "H0p"),
  contrast = NULL,
  sci.method = c("fisher", "multi.t"),
  Factor.Information = FALSE,
  CI.method = c("logit", "normal"),
  alpha = 0.05,
  covariance = FALSE,
  perm.test = FALSE,
  B = 1000
)
}
\arguments{
\item{formula}{A model formula of the form \code{response ~ factors}. Factors
on the right-hand side may contain crossed whole-plot and subplot factors
and their interactions.}

\item{data}{A data frame containing the response, subject variable, design
factors, and optionally a replicate variable.}

\item{subject}{Character string specifying the subject identifier.}

\item{replicate}{Optional character string specifying the replicate identifier.
Replicates can be dependent within subject-condition cells.}

\item{cell.weights}{Character string specifying how dependent replicates are
weighted. Use \code{"subjects"} for subject-level cell weighting and
\code{"observations"} for observation-level cell weighting.
For dependent replicates under \code{hypothesis = "H0F"},
\code{cell.weights = "subjects"} averages rank scores within
subject-condition cells before covariance estimation, whereas
\code{cell.weights = "observations"} uses the sums of the observed rank
scores within subject-condition cells and therefore gives more weight to
subjects with more observed replicate measurements.The default is
\code{"subjects"}.}

\item{effect}{Character string specifying whether weighted or unweighted
relative effects are used. Use \code{"weighted"} for effects based on
ordinary ranks and a sample-size weighted reference distribution. Use
\code{"unweighted"} for effects based on pseudo-ranks and an equally
weighted factorial-cell reference distribution. Weighted effects depend on
the sample-size allocation and are mainly descriptive. Unweighted effects
are the inferential target for \code{hypothesis = "H0p"}. In balanced
designs, both effect definitions coincide. The default is
\code{effect = "unweighted"}.}

\item{hypothesis}{Character string specifying the hypothesis type. Use
\code{"H0F"} for hypotheses in marginal distribution functions and
\code{"H0p"} for hypotheses in unweighted relative marginal effects.
The latter permits unequal variances or higher-order distributional
differences under the null hypothesis and is related to the nonparametric
Behrens-Fisher problem.}

\item{contrast}{Optional list specifying a factor or interaction term for
simultaneous inference. A one-element specification such as
\code{list("time")} uses the standard hypothesis matrix for the selected
model term, that is, the same contrast structure underlying the WTS and ATS
for that term. A two-element specification such as
\code{list("time", "Tukey")} or \code{list("time", "Dunnett")} applies the
named multiple contrast procedure to the marginal relative effects of the
selected term. A numeric vector or matrix may be supplied as the second
element for user-defined contrasts.}

\item{sci.method}{Character string specifying the method for simultaneous
confidence intervals. Available choices are \code{"fisher"} and \code{"multi.t"}.
The default is \code{"fisher"}.}

\item{Factor.Information}{Logical. If \code{TRUE}, factor-specific relative
effects, standard errors, and confidence intervals are returned. These
summaries can also be displayed with \code{plot(fit, term = ...)}.}

\item{CI.method}{Character string specifying the method for confidence intervals for
relative effects. Available choices are \code{"logit"} and \code{"normal"}. The default is \code{"logit"}.}

\item{alpha}{Significance level for tests and confidence intervals. The
default is \code{alpha = 0.05}.}

\item{covariance}{Logical. If \code{TRUE}, the estimated covariance matrix
used for the selected hypothesis is included in the output. The default is
\code{FALSE}.}

\item{perm.test}{Logical. Should the paired two-time-point permutation test be
used when applicable? This option is only available for paired designs with
two time points.}

\item{B}{Number of permutation samples used for the paired permutation test.}
}
\value{
An object of class \code{"nparld_fit"}. The object is a list containing the
results of the nonparametric longitudinal analysis. The main components are:
\itemize{
\item \code{Design}: character string describing the detected longitudinal
factorial design.
\item \code{wholeplots}: names of the whole-plot factors.
\item \code{subplots}: names of the subplot or repeated-measures factors.
\item \code{text.ranks}: character string describing the type of ranks used.
\item \code{text.hypotheses}: character string describing the type of
hypotheses tested.
\item \code{N.info}: information on the number of subjects and observations.
\item \code{effects}: a data frame with estimated relative effects. This
includes the factor-level combinations, the number of contributing
subjects and observations, the number of missing observations, the mean
rank or pseudo-rank score, the estimated relative effect, and its
standard error. For \code{hypothesis = "H0p"}, confidence limits are also
returned.
\item \code{factor.info}: optional factor-specific relative effects,
standard errors, and confidence limits for main effects and interactions,
returned when \code{Factor.Information = TRUE}. These summaries can be
displayed with \code{plot(fit, term = ...)}.
\item \code{WTS}: Wald-type test statistics, degrees of freedom, and
p-values for the tested main effects and interactions.
\item \code{ATS}: ANOVA-type test statistics, denominator degrees of
freedom, and p-values for the tested main effects and interactions.
\item \code{MCTP}: multiple contrast test results, returned when
\code{contrast} is specified. These include the selected factor or
interaction, the simultaneous confidence interval method, the global
multiple contrast test, local contrast estimates with standard errors,
simultaneous confidence limits, test statistics, p-values, degrees of
freedom, and the corresponding contrast matrix.
\item \code{covariance.info}: estimated covariance matrix used for the
selected hypothesis, returned when \code{covariance = TRUE}.
\item \code{perm}: permutation test results, returned when a permutation
test is requested and applicable.
\item \code{hypothesis}: the type of hypothesis tested, either \code{"H0F"}
for hypotheses in marginal distribution functions or \code{"H0p"} for
hypotheses in unweighted relative marginal effects.
\item \code{CI.method}: method used for confidence intervals.
\item \code{.internal}: internal objects used for computation and advanced
post-processing.
}

Some components may be \code{NULL} depending on the selected hypothesis,
contrast specification, and output options.
}
\description{
Performs nonparametric inference for longitudinal or repeated-measures data
from crossed factorial experiments. The function can be used to test hypotheses in
marginal distribution functions or hypotheses in unweighted relative
marginal effects. It allows crossed whole-plot and sub-plot factors,
missing values, and dependent replicate measurements.
}
\details{
The function provides rank- and pseudo-rank-based procedures for factorial
longitudinal data. The argument \code{hypothesis = "H0F"} specifies
hypotheses in marginal distribution functions. These hypotheses compare the
complete marginal distributions and are tested by rank-based procedures.

The argument \code{hypothesis = "H0p"} specifies hypotheses in unweighted
relative marginal effects. These effects describe the relative position of
each marginal distribution with respect to a common unweighted reference
distribution and are particularly useful for effect interpretation, multiple
contrast procedures, simultaneous confidence intervals, and graphical
summaries.

The \code{contrast} argument computes a multiple contrast test along with simultaneous
confidence intervals for the selected model terms. A one-element specification such as
\code{list("time")} uses the same hypothesis matrix as the global test procedures (Wald-
and ANOVA-type statistics) for the selected term. This
provides simultaneous inference for the components of the corresponding
global null hypothesis. A two-element specification such as
\code{list("time", "Tukey")} or \code{list("time", "Dunnett")} first forms
the marginal relative effects for the selected term and then applies the
requested multiple contrast procedure. Thus, \code{list("time", "Tukey")}
gives pairwise comparisons of the marginal time effects, whereas
\code{list("time", "Dunnett")} compares the marginal time effects with the
first time point. User-defined contrast vectors or matrices can be supplied
as the second list element.

Missing observations are allowed. Incomplete subject-condition cells
contribute where observations are available, and covariance estimation is
based on the independent subject-level units. Dependent replicate
measurements can be specified using the \code{replicate} argument. For
hypotheses in relative marginal effects, \code{cell.weights = "subjects"}
targets a typical subject-condition cell, whereas
\code{cell.weights = "observations"} targets a typical replicate observation.
For hypotheses in marginal distribution functions, dependent replicates are
handled by averaging rank or pseudo-rank scores within subject-condition
cells.
In case of bivariate data (e.g., before and after measurements), the function implements
a studentized permutation test for testing either \code{hypothesis = "H0F"} or
\code{hypothesis = "H0p"}.
}
\examples{
## One repeated-measures factor: dental data
data(dental)

fit_dental <- nparLD(
  resp ~ time,
  data = dental,
  subject = "subject",
  hypothesis = "H0p"
)

fit_dental

## Crossed factorial longitudinal design: shoulder data
data(shoulder)

\dontrun{
fit_shoulder <- nparLD(
  resp ~ group1 * group2 * time,
  data = shoulder,
  subject = "subject",
  hypothesis = "H0p"
)

fit_shoulder
}

## Multiple contrast procedure for an interaction

\dontrun{
fit_contrast <- nparLD(
  resp ~ group1 * group2 * time,
  data = shoulder,
  subject = "subject",
  hypothesis = "H0p",
  contrast = list("group1:time")
)

fit_contrast$MCTP
print(fit_contrast$MCTP, show.matrix = TRUE)
}

## Missing response values
\dontrun{
dat_miss <- dental
dat_miss$resp[c(2, 7, 12)] <- NA

fit_miss <- nparLD(
  resp ~ time,
  data = dat_miss,
  subject = "subject",
  hypothesis = "H0p"
)

fit_miss
}

## Dependent replicate measurements: BrdU data
data(brdu)

\dontrun{
fit_brdu <- nparLD(
  resp ~ dose,
  data = brdu,
  subject = "culture",
  replicate = "replicate",
  hypothesis = "H0p",
  cell.weights = "subjects"
)

fit_brdu
}

\dontrun{
## Graphical displays
plot(fit_dental)
plot(fit_shoulder)
plot(fit_contrast$MCTP)
}


}
\references{
Akritas, M. G., & Brunner, E. (1997). A unified approach to rank tests for mixed models.
Journal of Statistical Planning and Inference, 61(2), 249-277.

Brunner, E., Bathke, A.C., Konietschke, F. Rank and Pseudo-Rank Procedures
for Independent Observations in Factorial Designs. Springer International Publishing, 2018.

Brunner, E., Domhof, S., & Langer, F. (2002). Nonparametric analysis of longitudinal data in factorial experiments. Wiley, New York

Brunner, E., Konietschke, F., Pauly, M., Puri, M. L. (2017). Rank-based procedures in factorial designs:
Hypotheses about non-parametric treatment effects. Journal of the Royal Statistical Society: Series B
(Statistical Methodology), 79(5), 1463-1485.

Domhof, S., Brunner, E., Osgood, D. W. (2002). Rank procedures for repeated measures with missing values.
Sociological methods & research, 30(3), 367-393.

Konietschke, F., Bathke, A. C., Hothorn, L. A., & Brunner, E. (2010).
Testing and estimation of purely nonparametric effects in repeated measures designs.
Computational Statistics & Data Analysis, 54(8), 1895-1905.

Konietschke, F., Hothorn, L. A., Brunner, E. (2012). Rank-based multiple test procedures and simultaneous confidence intervals. Electronic Journal of Statistics,
6, 738-759.

Rubarth, K., Pauly, M., & Konietschke, F. (2022). Ranking procedures for repeated measures designs with missing data:
estimation, testing and asymptotic theory.
Statistical Methods in Medical Research, 31(1), 105-118.

Rubarth, K., Sattler, P., Zimmermann, H. G., & Konietschke, F. (2021).
Estimation and testing of Wilcoxon–Mann–Whitney effects in factorial clustered data designs.
Symmetry, 14(2), 244.
}
