Package {funbootband}


Title: Simultaneous Prediction and Confidence Bands for Functional Data
Version: 0.3.1
Description: Computes simultaneous prediction and confidence bands for densely sampled functional data on a common grid. Supports independent curves and repeated curves from multiple subjects. For clustered data, an intact-subject bootstrap gives each subject equal weight. Clustered prediction targets one future curve from a new subject, whereas confidence bands target the subject-weighted population mean. Curves are represented by finite Fourier series, and an 'Rcpp' backend performs bootstrap calibration.
License: GPL-3
URL: https://github.com/koda86/funbootband-cran
BugReports: https://github.com/koda86/funbootband-cran/issues
Depends: R (≥ 3.5)
Imports: Rcpp, stats
LinkingTo: Rcpp
Suggests: testthat (≥ 3.0.0), knitr, rmarkdown
VignetteBuilder: knitr
Encoding: UTF-8
SystemRequirements: C++17
Config/testthat/edition: 3
ByteCompile: true
Config/roxygen2/version: 8.1.0
NeedsCompilation: yes
Packaged: 2026-11-10 09:55:45 UTC; daniel
Author: Daniel Koska ORCID iD [aut, cre, cph]
Maintainer: Daniel Koska <dkoska@proton.me>
Repository: CRAN
Date/Publication: 2026-11-16 08:00:11 UTC

Simultaneous Bands for Functional Data

Description

Create simultaneous bootstrap bands for dense functional data (rows are time points, columns are curves). For clustered designs, subjects are treated as the independent sampling units and are resampled intact.

Usage

band(
  data,
  type = c("prediction", "confidence"),
  alpha = 0.05,
  iid = TRUE,
  id = NULL,
  B = 1000L,
  k.coef = 50L
)

Arguments

data

Numeric matrix with T rows (time) and n columns (curves). A data.frame of numeric columns is also accepted and coerced to a matrix.

type

Character, either "prediction" or "confidence".

alpha

Numeric in (0, 1). Use 0.05 for 95% bands.

iid

Logical; if FALSE, use an intact-cluster bootstrap (requires id or infers clusters from column-name prefixes). The clustered prediction target is one future curve from a new subject. Subjects are weighted equally, and curves are weighted equally within subject.

id

Optional integer/factor vector of length ncol(data) giving a cluster id for each curve (used when iid = FALSE). If NULL and iid = FALSE, clusters are inferred from column names by prefix (up to the first underscore, hyphen, or dot).

B

Integer, number of bootstrap iterations (e.g., 1000 for final results; use smaller values in examples/tests).

k.coef

Integer; number of Fourier harmonics (default 50). Automatically clamped to \lfloor (T-2)/2 \rfloor based on the grid length. This keeps sine/cosine harmonics in complete pairs on the periodic grid. Larger values fit more high-frequency detail; smaller values smooth more.

Details

For iid = FALSE, the clustered prediction band is marginal over the subject population. It targets one curve from an independent new subject; it is not conditional on an already observed subject and does not target joint coverage of several future curves. The construction assumes independent subjects and exchangeable repeated curves within subject. Since calibration follows Fourier preprocessing, the formal target is the future curve in the same Fourier-reconstructed representation, rather than raw pointwise measurement noise that the chosen basis does not retain.

The i.i.d. calibration follows the curve-level functional-bootstrap target of Lenhoff et al. (1999). The clustered construction implemented here is an intact-subject bootstrap with subject-first empirical weighting. It is a revision of, rather than a literal implementation of, the hierarchical resampling description in Koska et al. (2023). Clustered confidence inference treats subject mean curves as the independent units and studentizes every bootstrap replicate with its own pointwise standard error.

Very small numbers of independent sampling units can produce bootstrap replicates with zero pointwise scale. band() reports an error when the chance of drawing only one distinct independent unit could dominate the requested calibration tail. Independent units are curves for i.i.d. data and subjects for clustered data.

Value

An object of class funbootband, implemented as a list with elements lower, mean, upper (each of length T) and meta. Existing code can continue to access these components with $. For clustered prediction, meta$target records the estimand "new_subject_new_curve" and meta$weighting records the subject-first weighting convention.

References

Koska, D., Oriwol, D., & Maiwald, C. (2023). Comparison of statistical models for characterizing continuous differences between two biomechanical measurement systems. Journal of Biomechanics, 149, 111506. https://doi.org/10.1016/j.jbiomech.2023.111506

Lenhoff, M. W., Santner, T. J., Otis, J. C., Peterson, M. G. E., Williams, B. J., & Backus, S. I. (1999). Bootstrap prediction and confidence bands: a superior statistical method for analysis of gait data. Gait & Posture, 9(1), 10–17. https://doi.org/10.1016/S0966-6362(98)00043-5

Davison, A. C., & Hinkley, D. V. (1997). Bootstrap Methods and Their Application. Cambridge University Press. https://doi.org/10.1017/cbo9780511802843

Examples

## Independent-curve example

set.seed(1)
T <- 101L
n <- 30L
x <- seq(0, 1, length.out = T)
mu_true <- 0.7 * sin(2 * pi * x) - 0.2 * cos(4 * pi * x)

generate_curve <- function() {
  mu_true +
    rnorm(1, sd = 0.35) +
    rnorm(1, sd = 0.30) * sin(2 * pi * x) +
    rnorm(1, sd = 0.20) * cos(2 * pi * x) +
    rnorm(1, sd = 0.15) * sin(4 * pi * x)
}

Y <- replicate(n, generate_curve())

fit_pred <- band(Y, type = "prediction", alpha = 0.10,
                 iid = TRUE, B = 500L, k.coef = 4L)
fit_conf <- band(Y, type = "confidence", alpha = 0.10,
                 iid = TRUE, B = 500L, k.coef = 4L)

ylim <- range(c(Y, fit_pred$lower, fit_pred$upper), finite = TRUE)
plot(x, fit_pred$mean, type = "n", ylim = ylim,
     xlab = "Normalized time", ylab = "Value",
     main = "Simultaneous bands (i.i.d.)")
matlines(x, Y, col = grDevices::adjustcolor("gray40", 0.25), lty = 1)
polygon(c(x, rev(x)), c(fit_pred$lower, rev(fit_pred$upper)),
        col = grDevices::adjustcolor("steelblue", 0.25), border = NA)
polygon(c(x, rev(x)), c(fit_conf$lower, rev(fit_conf$upper)),
        col = grDevices::adjustcolor("darkorange", 0.30), border = NA)
lines(x, fit_pred$mean, lwd = 2)
lines(x, mu_true, col = "red", lwd = 2, lty = 2)
## Clustered example: repeated curves nested within subjects

set.seed(2)
T <- 101L
x <- seq(0, 1, length.out = T)

# Twelve independent subjects contribute unequal numbers of repeated curves.
K_subject <- 12L
m <- rep(c(2L, 3L, 4L), length.out = K_subject)
id <- rep(seq_len(K_subject), m)

mu_true <- 0.7 * sin(2 * pi * x) - 0.2 * cos(4 * pi * x)

# Smooth subject-specific deviations from the population mean.
subject_effect <- sapply(seq_len(K_subject), function(i) {
  rnorm(1, sd = 0.35) +
    rnorm(1, sd = 0.30) * sin(2 * pi * x) +
    rnorm(1, sd = 0.20) * cos(2 * pi * x)
})

# Smooth curve-to-curve deviations within a subject.
within_subject_effect <- function() {
  rnorm(1, sd = 0.18) * sin(4 * pi * x) +
    rnorm(1, sd = 0.12) * cos(4 * pi * x)
}

Y <- sapply(seq_along(id), function(j) {
  mu_true + subject_effect[, id[j]] + within_subject_effect()
})

trial <- ave(id, id, FUN = seq_along)
colnames(Y) <- paste0("subject", id, "_trial", trial)

# The prediction target is one Fourier-reconstructed curve from a new subject.
fit_pred <- band(Y, type = "prediction", alpha = 0.10,
                 iid = FALSE, id = id, B = 500L, k.coef = 4L)

# The confidence target is the equally subject-weighted population mean curve.
fit_conf <- band(Y, type = "confidence", alpha = 0.10,
                 iid = FALSE, id = id, B = 500L, k.coef = 4L)

fit_pred$meta[c("target", "weighting", "bootstrap_unit", "n_clusters")]

# Plot the results.
ylim <- range(c(Y, fit_pred$lower, fit_pred$upper), finite = TRUE)
plot(x, fit_pred$mean, type = "n", ylim = ylim,
     xlab = "Normalized time", ylab = "Value",
     main = "Simultaneous bands (clustered)")
matlines(x, Y, col = grDevices::adjustcolor("gray40", 0.20), lty = 1)
polygon(c(x, rev(x)), c(fit_pred$lower, rev(fit_pred$upper)),
        col = grDevices::adjustcolor("steelblue", 0.25), border = NA)
polygon(c(x, rev(x)), c(fit_conf$lower, rev(fit_conf$upper)),
        col = grDevices::adjustcolor("darkorange", 0.30), border = NA)
lines(x, fit_pred$mean, lwd = 2)
lines(x, mu_true, col = "red", lwd = 2, lty = 2)

Methods for funbootband objects

Description

Convenient display, summary, and plotting methods for objects returned by band(). The underlying object remains a list, so the lower, mean, upper, and meta components remain directly accessible.

Usage

## S3 method for class 'funbootband'
print(x, ...)

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

## S3 method for class 'summary.funbootband'
print(x, ...)

## S3 method for class 'funbootband'
plot(
  x,
  grid = NULL,
  ylim = NULL,
  xlab = NULL,
  ylab = "Value",
  main = NULL,
  band.col = grDevices::adjustcolor("steelblue", alpha.f = 0.25),
  border = NA,
  mean.col = "black",
  mean.lwd = 2,
  ...
)

Arguments

x

A funbootband object.

...

Additional arguments. For plot(), these are passed to graphics::plot.default(). They are currently ignored by print() and summary().

object

A funbootband object.

grid

Optional numeric vector giving the horizontal coordinates. By default, the method uses x$meta$grid when available and otherwise the integer sequence along the band.

ylim

Optional numeric vector of length two giving the vertical plot limits. By default, the range of the lower and upper bands is used.

xlab, ylab

Axis labels.

main

Plot title. By default, the title reports the nominal coverage and band type.

band.col

Fill color for the band.

border

Border color for the band polygon. The default is no border.

mean.col

Color for the estimated mean curve.

mean.lwd

Line width for the estimated mean curve.

Value

print() returns x invisibly. summary() returns an object of class summary.funbootband containing the inferential target, design and computation settings, and summaries of band width. plot() returns x invisibly after drawing the band. The print method for a summary object returns that object invisibly.