Package {nparLD}

nparLD: Nonparametric Longitudinal Data Analysis

Description

The nparLD package provides nonparametric methods for the analysis of longitudinal and repeated-measures data in factorial experiments. It is especially useful for settings in which response distributions may be non-normal, ordinal, skewed, heteroscedastic, or affected by ties. The procedures do not require distributional assumptions, and are applicable to a variety of data types (continuous, discrete, purely ordinal, and dichotomous). The methods are also robust with respect to outliers and for small sample sizes.

Details

The main function is nparLD(), which implements inference for hypotheses in marginal distribution functions and in unweighted relative marginal effects. The package supports crossed factorial designs with whole-plot and sub-plot factors, missing observations, dependent replicate measurements, rank- and pseudo-rank-based estimation, confidence intervals, Wald-type and ANOVA-type statistics, multiple contrast procedures, and simultaneous confidence intervals.

Main function

• nparLD() performs the nonparametric analysis.

Hypotheses

The argument hypothesis = "H0F" tests hypotheses in marginal distribution functions. The argument hypothesis = "H0p" tests hypotheses in unweighted relative marginal Mann-Whitney effects and thus addresses the nonparametric Behrens-Fisher problem in factorial longitudinal designs.

Effects

The argument effect = "weighted" estimates weighted relative marginal Mann-Whitney effects using classical ranks (mid-ranks) of the observations. The argument effect = "unweighted" estimates unweighted relative marginal Mann-Whitney effects using pseudo-ranks of the data. The weighted relative marginal effect depends on sample sizes and their allocations, whereas the unweighted relative marginal effect does not.

Contrast

The argument contrast = list() estimates and tests contrasts on the given factor levels or their interaction effects using multiple contrast tests. If the null hypothesis H0p is tested, then simultaneous confidence intervals are computed.

Replicates

Dependent replicates can be specified by the replicate argument. For relative marginal effects, the cell.weights argument determines whether subject-condition cells or individual replicate observations define the target of estimation.

Author(s)

Maintainer: Frank Konietschke frank.konietschke@charite.de

Authors:

• Frank Konietschke frank.konietschke@charite.de

Other contributors:

• Kimihiro Noguchi (Original package author) [contributor]

• Mahbub Latif (Original package author) [contributor]

• Karthinathan Thangavelu (Original package author) [contributor]

• Yulia R. Gel (Original package author) [contributor]

• Edgar Brunner [contributor]

Alpha-amylase Saliva Study

Description

Measurements of alpha-amylase levels in saliva from healthy volunteers. The study illustrates a two-factor longitudinal design with two repeated measures factors.

Usage

amylase

Format

A data frame with variables:

resp

Alpha-amylase measurement.

time1

First repeated-measures factor.

time2

Second repeated-measures factor.

subject

Subject identifier.

Examples

data(amylase)

fit <- nparLD(resp ~ time1 * time2,
              data = amylase,
              subject = "subject",
              effect = "weighted",
              hypothesis = "H0F")
fit

# Dunnett-type contrasts for the levels of time2
fit <- nparLD(resp ~ time1 * time2,
              data = amylase,
              subject = "subject",
              hypothesis = "H0p",
              contrast = list("time2", "Dunnett"),
              Factor.Information = TRUE)
fit
plot(fit)
plot(fit$MCTP)

BrdU incorporation in fibroblasts

Description

BrdU incorporation in fibroblast cultures measured under four dose conditions. For each culture and dose condition, three replicate measurements are available. The data set is provided in long format and can be used to illustrate dependent replicate measurements in nparLD().

Usage

brdu

Format

A data frame with 60 rows and 4 variables:

resp

BrdU incorporation response.

dose

Dose condition, with levels 0, 0.1, 1, and 10.

culture

Culture identifier. This is the independent experimental unit.

replicate

Replicate identifier within each culture-dose condition.

Details

The original variables were CultureNo, Replic, Dose, and Brdu. In the package data set, the variables were renamed to culture, replicate, dose, and resp for consistency with the examples.

Examples

## Not run: 
data(brdu)

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

fit

## End(Not run)

Dental Growth Study

Description

Measurements of distances between the center of the pituitary and the pterygomaxillary fissure in boys. The data illustrate a one-factor longitudinal design.

Usage

dental

Format

A data frame with variables:

resp

Distance measurement in millimeters.

time

Age at measurement.

subject

Subject identifier.

Examples

data(dental)

dental$time <- factor(dental$time)

## Not run: 
fit <- nparLD(resp ~ time,
              data = dental,
              subject = "subject",
              hypothesis = "H0F")
fit

## End(Not run)

## Not run: 
fit <- nparLD(resp ~ time,
              data = dental,
              subject = "subject",
              hypothesis = "H0p",
              contrast = list("time", "Tukey"))
fit
plot(fit)
plot(fit$MCTP)

## End(Not run)

Postoperative Edema Study

Description

Skin-temperature measurements from patients after hand surgery. The study compares treatment groups and includes two repeated-measures factors.

Usage

edema

Format

A data frame with variables:

resp

Skin temperature measurement.

time1

Hand factor.

time2

Day factor.

group

Treatment group.

subject

Subject identifier.

Examples

data(edema)

## Not run: 
fit <- nparLD(resp ~ group * time1 * time2,
              data = edema,
              subject = "subject",
              hypothesis = "H0F")
fit

## End(Not run)

## Not run: 
fit <- nparLD(resp ~ group * time1 * time2,
              data = edema,
              subject = "subject",
              hypothesis = "H0p",
              contrast = list("group", "Tukey"),
              Factor.Information = TRUE)
fit
plot(fit)
plot(fit$MCTP)

## End(Not run)

Nonparametric Analysis of Longitudinal Data

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.

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

Details

The function provides rank- and pseudo-rank-based procedures for factorial longitudinal data. The argument hypothesis = "H0F" specifies hypotheses in marginal distribution functions. These hypotheses compare the complete marginal distributions and are tested by rank-based procedures.

The argument 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 contrast argument computes a multiple contrast test along with simultaneous confidence intervals for the selected model terms. A one-element specification such as 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 list("time", "Tukey") or list("time", "Dunnett") first forms the marginal relative effects for the selected term and then applies the requested multiple contrast procedure. Thus, list("time", "Tukey") gives pairwise comparisons of the marginal time effects, whereas 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 replicate argument. For hypotheses in relative marginal effects, cell.weights = "subjects" targets a typical subject-condition cell, whereas 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 hypothesis = "H0F" or hypothesis = "H0p".

Value

An object of class "nparld_fit". The object is a list containing the results of the nonparametric longitudinal analysis. The main components are:

• Design: character string describing the detected longitudinal factorial design.

• wholeplots: names of the whole-plot factors.

• subplots: names of the subplot or repeated-measures factors.

• text.ranks: character string describing the type of ranks used.

• text.hypotheses: character string describing the type of hypotheses tested.

• N.info: information on the number of subjects and observations.

• 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 hypothesis = "H0p", confidence limits are also returned.

• factor.info: optional factor-specific relative effects, standard errors, and confidence limits for main effects and interactions, returned when Factor.Information = TRUE. These summaries can be displayed with plot(fit, term = ...).

• WTS: Wald-type test statistics, degrees of freedom, and p-values for the tested main effects and interactions.

• ATS: ANOVA-type test statistics, denominator degrees of freedom, and p-values for the tested main effects and interactions.

• MCTP: multiple contrast test results, returned when 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.

• covariance.info: estimated covariance matrix used for the selected hypothesis, returned when covariance = TRUE.

• perm: permutation test results, returned when a permutation test is requested and applicable.

• hypothesis: the type of hypothesis tested, either "H0F" for hypotheses in marginal distribution functions or "H0p" for hypotheses in unweighted relative marginal effects.

• CI.method: method used for confidence intervals.

• .internal: internal objects used for computation and advanced post-processing.

Some components may be NULL depending on the selected hypothesis, contrast specification, and output options.

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.

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)

## Not run: 
fit_shoulder <- nparLD(
  resp ~ group1 * group2 * time,
  data = shoulder,
  subject = "subject",
  hypothesis = "H0p"
)

fit_shoulder

## End(Not run)

## Multiple contrast procedure for an interaction

## Not run: 
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)

## End(Not run)

## Missing response values
## Not run: 
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

## End(Not run)

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

## Not run: 
fit_brdu <- nparLD(
  resp ~ dose,
  data = brdu,
  subject = "culture",
  replicate = "replicate",
  hypothesis = "H0p",
  cell.weights = "subjects"
)

fit_brdu

## End(Not run)

## Not run: 
## Graphical displays
plot(fit_dental)
plot(fit_shoulder)
plot(fit_contrast$MCTP)

## End(Not run)

Panic Disorder Study I

Description

Clinical Global Impression scores from patients with panic disorder and agoraphobia. The data illustrate a one-factor longitudinal design with ordinal responses.

Usage

panic

Format

A data frame with variables:

resp

Clinical Global Impression score.

time

Visit or week of assessment.

subject

Patient identifier.

Examples

data(panic)

## Not run: 
fit <- nparLD(resp ~ time,
              data = panic,
              subject = "subject",
              hypothesis = "H0F", contrast =list("time", "Dunnett"))
fit

## End(Not run)

## Not run: 
fit <- nparLD(resp ~ time,
              data = panic,
              subject = "subject",
              hypothesis = "H0p",
              contrast = list("time", "Dunnett"))
fit
plot(fit)
plot(fit$MCTP)

## End(Not run)

Panic Disorder Study II

Description

Panic and agoraphobia scores from patients with panic disorder, with or without agoraphobia. The data illustrate a factorial longitudinal design with one whole-plot factor and one repeated-measures factor.

Usage

panic2

Format

A data frame with variables:

resp

Panic and agoraphobia score.

time

Visit or week of assessment.

group

Agoraphobia group.

subject

Patient identifier.

Examples

data(panic2)

## Not run: 
fit <- nparLD(resp ~ group * time,
              data = panic2,
              subject = "subject",
              hypothesis = "H0F", effect="unweighted")
fit

## End(Not run)

## Not run: 
fit <- nparLD(resp ~ group * time,
              data = panic2,
              subject = "subject",
              hypothesis = "H0p",
              contrast = list("group:time"),
              Factor.Information = TRUE,
              covariance=TRUE)
fit
plot(fit)
plot(fit$MCTP)

## End(Not run)

Plasma-renin Activity Study

Description

Plasma-renin activity measurements from a randomized study of healthy non-smokers. The data illustrate a factorial longitudinal design with one whole-plot factor and one repeated-measures factor.

Usage

plasma

Format

A data frame with variables:

resp

Plasma-renin activity measurement.

time

Measurement time.

group

Drug group.

subject

Subject identifier.

Examples

data(plasma)

## Not run: 
fit <- nparLD(resp ~ group * time,
              data = plasma,
              subject = "subject",
              hypothesis = "H0F", effect="weighted")
fit

## End(Not run)

## Not run: 
fit <- nparLD(resp ~ group * time,
              data = plasma,
              subject = "subject",
              hypothesis = "H0p",
              contrast = list("group", "Tukey"))
fit
plot(fit)
plot(fit$MCTP)

## End(Not run)

Plot nparLD results

Description

Displays graphical summaries of estimated relative effects from an nparLD() fit. By default, the method plots the cell-level relative effects stored in x$effects. If term is supplied, it plots factor-specific relative effects and confidence intervals for selected main effects or interactions. Term-specific plots require that the model was fitted with Factor.Information = TRUE.

Usage

## S3 method for class 'nparld_fit'
plot(
  x,
  term = NULL,
  xlab = NULL,
  ylab = "Relative effect",
  main = NULL,
  legend.title = NULL,
  ref.line = 0.5,
  ref.lty = "dashed",
  ref.col = "grey40",
  ...
)

Arguments

Details

The default plot displays the estimated cell-level relative effects. If term is supplied, the plot displays factor-specific relative effects and confidence intervals for the selected main effects or interactions. This requires that the model was fitted with Factor.Information = TRUE. The horizontal reference line at 0.5 indicates no tendency relative to the reference distribution. Values above 0.5 indicate a tendency toward larger responses, whereas values below 0.5 indicate a tendency toward smaller responses.

Examples

data(shoulder)

fit <- nparLD(
  resp ~ group1 * group2 * time,
  data = shoulder,
  subject = "subject",
  hypothesis = "H0p",
  Factor.Information = TRUE
)

## Cell-level relative effects
plot(fit)

## Factor-specific relative effects and confidence intervals
plot(fit, term = "time")
plot(fit, term = "group1:time")

Plot nparLD multiple contrast results

Description

Displays simultaneous confidence intervals for local contrasts from a multiple contrast test procedure. The plot shows the contrast estimates together with their simultaneous confidence limits and a vertical reference line at zero. Intervals excluding zero are highlighted by default.

Usage

## S3 method for class 'nparld_mctp'
plot(
  x,
  xlab = "Contrast effect",
  ylab = "",
  main = NULL,
  ref.line = 0,
  ref.lty = 2,
  ref.col = "gray50",
  pch = 19,
  lwd = 2,
  col = NULL,
  ...
)

Arguments

Details

Displays simultaneous confidence intervals for the local contrast results returned by the multiple contrast test procedure. The vertical reference line at zero indicates the null value for contrast effects.

Examples

data(shoulder)

fit <- nparLD(
  resp ~ group1 * group2 * time,
  data = shoulder,
  subject = "subject",
  hypothesis = "H0p",
  contrast = list("time", "Dunnett")
)

plot(fit$MCTP)

Print nparLD covariance matrix

Description

Displays the estimated covariance matrix of the relative effect estimator.

Usage

## S3 method for class 'nparld_covarianceinfo'
print(x, digits = 4, ...)

Arguments

Details

The printed matrix is the estimated covariance matrix used for the selected hypothesis. It is returned when covariance = TRUE.

Print nparLD factor information

Description

Prints factor-specific relative effects, standard errors, and confidence limits for the main effects and interactions of an nparLD() fit. Factor information is returned when the model is fitted with Factor.Information = TRUE and can also be displayed graphically with plot(fit, term = ...).

Usage

## S3 method for class 'nparld_factorinfo'
print(x, digits = 4, ...)

Arguments

Details

Factor information consists of term-specific relative effects, standard errors, and confidence limits for main effects and interactions. These summaries are returned when Factor.Information = TRUE and can be visualized with plot(fit, term = ...).

Print nparLD fit

Description

Prints the main results of a fitted nparLD() model, including the detected design, hypothesis type, ranking method, estimated relative effects, and global WTS and ATS results. Optional components such as factor-specific information, multiple contrast results, covariance matrices, and permutation tests are displayed when available.

Usage

## S3 method for class 'nparld_fit'
print(x, digits = 4, ...)

Arguments

Details

The print method displays the detected design, sample size information, hypothesis type, ranking method, estimated relative effects, and global WTS and ATS results. Optional components are printed when available, including factor-specific information, multiple contrast results, covariance matrices, and permutation test results.

Print nparLD multiple contrast results

Description

Prints the global and local results of a multiple contrast test procedure. The local results include contrast estimates, standard errors, simultaneous confidence limits, test statistics, adjusted p-values, and degrees of freedom. The contrast matrix can optionally be displayed with show.matrix = TRUE.

Usage

## S3 method for class 'nparld_mctp'
print(x, digits = 4, show.matrix = FALSE, ...)

Arguments

Details

The method prints the global multiple contrast test and the local contrast results, including estimates, standard errors, simultaneous confidence limits, test statistics, adjusted p-values, and degrees of freedom. The contrast matrix is stored in x$Contrast.Matrix and is printed only when show.matrix = TRUE.

Print summary of an nparLD fit

Description

Prints the main components of a summarized nparLD() fit, including design information, hypothesis type, estimated relative effects, and global WTS and ATS results. Optional components such as factor-specific information, multiple contrast results, covariance matrices, and permutation tests are displayed when available.

Usage

## S3 method for class 'summary.nparld_fit'
print(x, digits = 4, ...)

Arguments

Rat Growth Study

Description

Body-weight measurements from rats observed over a five-week period. The data illustrate longitudinal growth curves in several treatment groups.

Usage

rat

Format

A data frame with variables:

resp

Body weight in grams.

time

Week of measurement.

group

Treatment group.

subject

Rat identifier.

Examples

## Not run: 
data(rat)

fit <- nparLD(resp ~ group * time,
              data = rat,
              subject = "subject",
              hypothesis = "H0F")
fit

## End(Not run)

## Not run: 
fit <- nparLD(resp ~ group * time,
              data = rat,
              subject = "subject",
              hypothesis = "H0p",
              contrast = list("group:time"))
fit
plot(fit)
plot(fit$MCTP)

## End(Not run)

Respiratory Disorder Study

Description

Ordinal health-status measurements from patients with a respiratory disorder. The data include study center, treatment group, and repeated visits.

Usage

respiration

Format

A data frame with variables:

resp

Ordinal health-status response.

time

Visit number.

center

Study center.

treatment

Treatment group.

patient

Patient identifier.

Examples

## Not run: 
data(respiration)

fit <- nparLD(resp ~ center * treatment * time,
              data = respiration,
              subject = "patient",
              hypothesis = "H0F")
fit

## End(Not run)

## Not run: 
fit <- nparLD(resp ~ center * treatment * time,
              data = respiration,
              subject = "patient",
              hypothesis = "H0p",
              contrast = list("treatment", "Tukey"))
fit
plot(fit)
plot(fit$MCTP)

## End(Not run)

Shoulder Tip Pain Study

Description

Shoulder pain scores from patients after laparoscopic abdominal surgery. The study includes treatment group, gender group, and repeated pain measurements.

Usage

shoulder

Format

A data frame with variables:

resp

Shoulder pain score.

time

Measurement occasion.

group1

Treatment group.

group2

Gender group.

subject

Patient identifier.

Examples

data(shoulder)

## Not run: 
fit <- nparLD(resp ~ group1 * group2 * time,
              data = shoulder,
              subject = "subject",
              hypothesis = "H0F")
fit

## End(Not run)

## Not run: 
fit <- nparLD(resp ~ group1 * group2 * time,
              data = shoulder,
              subject = "subject",
              hypothesis = "H0p",
              contrast = list("group1:time"),
              Factor.Information=TRUE)
fit
plot(fit)
plot(fit$MCTP)

## End(Not run)

Summarize an nparLD fit

Description

Extracts the main components of a fitted nparLD() object into a structured summary object. The summary is useful for inspecting, printing, or programmatically accessing the main results without working directly with all internal components of the fitted object.

Usage

## S3 method for class 'nparld_fit'
summary(object, ...)

Arguments

Details

The summary method returns a structured list containing the main components of the fitted object. In contrast to print(), which is mainly intended for console display, summary() is useful for storing or extracting the main results programmatically.

Value

An object of class "summary.nparld_fit" containing selected components of the fitted model.

Vitality of Treetops

Description

Repeated vitality scores of treetops from three experimental areas. The data illustrate an ordinal longitudinal response in several groups.

Usage

tree

Format

A data frame with variables:

resp

Vitality score.

time

Year or measurement occasion.

group

Experimental area.

subject

Tree identifier.

Examples

data(tree)

## Not run: 
fit <- nparLD(resp ~ group * time,
              data = tree,
              subject = "subject",
              hypothesis = "H0F")
fit

## End(Not run)


## Not run: 
fit <- nparLD(resp ~ group * time,
              data = tree,
              subject = "subject",
              hypothesis = "H0p",
              contrast = list("group:time"))
fit
plot(fit)
plot(fit$MCTP)

## End(Not run)