This vignette accompanies development version 0.99.2. The benchmark
covers selected configurations, and the validation study uses 100
datasets per metric with 99 resampling draws. These small simulations
provide diagnostics; they do not establish general statistical
calibration. The local study observed 24% peak false positives, 10% peak
detection, 74.9% transfer interval coverage, and 43% drift interval
coverage in the tested scenarios. These results limit inferential use of
these methods. Report sources are scripts/benchmark.R and
scripts/validate.R.
Optical spectra are functions: a measured absorbance (or intensity,
reflectance, Raman shift) at each of hundreds or thousands of
wavelengths. The natural temptation is to run a pointwise t-test at each
wavelength and report the wavelengths where the p-value drops below
0.05. That temptation is wrong. With 1000 wavelength bins and
independent Gaussian noise the analyst expects 50 false-positive
wavelengths under the null at alpha = 0.05. With positive
autocorrelation across wavelengths the false positives cluster, and the
analysis produces spurious “regions of difference”.
This vignette walks through three crossStatR functions that are
designed for optical data: adaptive_smoothing() for noise
reduction with peak preservation, peak_evidence() for
assessing whether a candidate peak is real, and
signal_difference_regions() for identifying spectral
regions where two groups differ while controlling the family-wise error
rate.
The example simulates two groups of 12 replicate spectra each across 400-800 nm. The “treated” group has an extra Gaussian absorption peak centred at 540 nm that is absent from the control group. Noise is correlated across neighbouring wavelengths to mimic realistic spectrometer behaviour.
set.seed(404)
wavelengths <- seq(400, 800, length.out = 200)
n_per_group <- 12
make_curve <- function(group) {
base <- 0.05 + 0.0006 * (wavelengths - 400) # gentle slope
peak1 <- 0.6 * exp(-(wavelengths - 460)^2 / (2 * 15^2)) # shared peak
peak2 <- if (group == "treated")
0.8 * exp(-(wavelengths - 540)^2 / (2 * 12^2)) else 0
# Correlated noise: AR(1) across wavelengths
e <- as.numeric(stats::filter(rnorm(length(wavelengths), sd = 0.06),
filter = 0.6, method = "recursive"))
base + peak1 + peak2 + e
}
ctrl <- t(replicate(n_per_group, make_curve("control")))
trt <- t(replicate(n_per_group, make_curve("treated")))
spec_df <- data.frame(
wl = rep(wavelengths, times = 2 * n_per_group),
absorbance = c(as.vector(t(ctrl)), as.vector(t(trt))),
group = rep(c("control", "treated"), each = n_per_group * length(wavelengths)),
rep = factor(rep(rep(seq_len(n_per_group), each = length(wavelengths)), 2))
)
ggplot(spec_df, aes(x = wl, y = absorbance, group = interaction(group, rep),
colour = group)) +
geom_line(alpha = 0.5) +
labs(x = "Wavelength (nm)", y = "Absorbance") +
theme_bw()Aggressive smoothing reduces variance but biases peak heights
downward and peak widths upward. The bias propagates: a smoothed peak
height is a downward-biased estimate of the true peak height.
adaptive_smoothing() makes this tradeoff explicit by
minimising leave-one-out PRESS over a candidate grid of Savitzky-Golay
windows and vetoing any window that shrinks the global maximum by more
than 5%.
example_curve <- trt[1, ]
sm <- adaptive_smoothing(wavelengths, example_curve,
method = "sgolay", poly_order = 3L)
print(sm)
#> <crossStatR::adaptive_smoothing> method = sgolay
#> window = 7
#> PRESS = 0.5279
#> Peak height loss = 0.63%The reported peak_height_loss is the fraction of the
global maximum lost to smoothing. If it exceeds 0.05, the
peak-preservation constraint forced the function to pick a smaller
window than PRESS alone would suggest. Inspect press and
peak_height_loss together; if both are large the analyst
has a noisy signal with a sharp peak, and the analyst should consider
fitting a model to the raw data instead.
plot_df <- data.frame(
wl = rep(wavelengths, 2),
absorbance = c(example_curve, sm$smoothed),
what = rep(c("raw", "smoothed"), each = length(wavelengths))
)
ggplot(plot_df, aes(x = wl, y = absorbance, colour = what)) +
geom_line() + labs(x = "Wavelength (nm)", y = "Absorbance") +
theme_bw()Raw and smoothed spectra. The smoothed curve follows the raw data closely at the peak, at the cost of slightly more residual noise.
Given a candidate peak location, peak_evidence() reports
a Gaussian likelihood-style score and a resampling tail fraction. The
score and resampling procedure are exploratory: local simulations found
poor null calibration and low detection rates. Neither output
establishes a calibrated false-positive probability for a detected
peak.
pe <- peak_evidence(wavelengths, example_curve, method = "lr",
n_perm = 500, seed = 1)
head(pe$peaks, 5)
#> index x amplitude snr lr log_lr fpp_perm
#> 1 29 456.2814 0.4347804 4.294251 1.010004e+04 9.220294 0.001996008
#> 2 31 460.3015 0.4602392 4.545702 3.069040e+04 10.331705 0.001996008
#> 3 34 466.3317 0.4092341 4.041934 3.528455e+03 8.168615 0.001996008
#> 4 68 534.6734 0.4655394 4.598052 3.898921e+04 10.571040 0.001996008
#> 5 73 544.7236 0.7043338 6.956582 3.225751e+10 24.197017 0.001996008
#> ci_low ci_high location_uncertainty signif
#> 1 0.2363398 0.6332211 10.05025 TRUE
#> 2 0.2617985 0.6586799 10.05025 TRUE
#> 3 0.2107934 0.6076748 10.05025 TRUE
#> 4 0.2670987 0.6639801 14.07035 TRUE
#> 5 0.5058931 0.9027745 14.07035 TRUEThe score assumes a known noise SD and uses the baseline-subtracted candidate amplitude. Resampling retains a smoothing spline, shuffles its residuals, and compares a different local-contrast statistic with that amplitude. The candidate set is not re-detected within each resample. The resulting tail fraction requires methodological validation before confirmatory use. Overlapping peaks also require a joint signal model.
To ask where the two groups differ while controlling the
family-wise error rate, use signal_difference_regions().
The function builds pointwise t-statistics \hat d(x) / s(x)
and replaces the pointwise critical value with the
1 - alpha quantile of the maximum absolute t-statistic
under the null (Westfall and Young, 1993). The null distribution is
estimated by a Westfall-Young permutation scheme: group labels are
exchanged between replicate curves and the max-t statistic is recomputed
for each permutation.
sdr <- signal_difference_regions(
x = wavelengths,
y1 = ctrl, y2 = trt,
conf_level = 0.95,
method = "max-t",
n_perm = 500,
seed = 1
)
print(sdr)
#> <crossStatR::signal_difference_regions> max-t with Westfall-Young permutation (500 perms)
#> Nominal coverage: 95%
#> Critical value c_alpha = 4.1268
#> Grid size: 200 points; groups n1=12, n2=12
#>
#> Significant regions:
#> start end n_points max_abs_diff sign
#> 518.5930 562.8141 23 0.7918932 -
#> 588.9447 588.9447 1 0.1153912 +The reported regions data frame lists the contiguous
wavelength intervals where the simultaneous band excludes zero. The
function also returns the per-wavelength difference, the standard error,
and the band endpoints so the analyst can plot the band itself.
band_df <- data.frame(
wl = sdr$x_grid,
diff = sdr$diff,
low = sdr$band_low,
high = sdr$band_high
)
# Mark identified regions
regions_df <- sdr$regions
if (!is.null(regions_df) && nrow(regions_df) > 0) {
regions_df$ymin <- min(band_df$low)
regions_df$ymax <- max(band_df$high)
}
p <- ggplot(band_df, aes(x = wl, y = diff)) +
geom_ribbon(aes(ymin = low, ymax = high), alpha = 0.25) +
geom_line(colour = "black") +
geom_hline(yintercept = 0, linetype = "dashed") +
labs(x = "Wavelength (nm)", y = "Mean difference (treated - control)") +
theme_bw()
if (!is.null(regions_df) && nrow(regions_df) > 0) {
p <- p + geom_rect(data = regions_df, alpha = 0.15,
aes(xmin = start, xmax = end, ymin = ymin, ymax = ymax),
inherit.aes = FALSE, fill = "tomato")
}
pPointwise mean difference (black), 95% simultaneous confidence band (grey ribbon), and the identified significant region (shaded). Pointwise 95% intervals would include zero across most of the spectrum, falsely narrowing the apparent difference.
A pointwise 95% interval at each wavelength has 95% coverage at
that wavelength. It does not have 95% coverage for the whole
curve. With 200 wavelength bins and independent Gaussian noise the
probability that at least one pointwise interval excludes zero under the
null is roughly 1 - 0.95^200 \approx 1. The family-wise
error rate collapses.
A simultaneous 95% band controls the probability that any point on the band fails to cover the true difference, across the whole curve. The analyst can report “the two groups differ in the region 525-555 nm” with the family- wise error rate at the nominal level. Pointwise tests support no such claim; they describe each wavelength in isolation.
The cost is power. A simultaneous band is wider than the
corresponding pointwise interval at every wavelength. The Westfall-Young
permutation adjustment recovers some of that power by accounting for the
correlation structure across wavelengths, which the Bonferroni
adjustment does not. With n_perm = 0 the function falls
back to a Bonferroni-adjusted critical value, which is conservative;
with n_perm > 0 it uses the permutation distribution,
which is more powerful when neighbouring wavelengths are correlated (as
they almost always are in optical spectroscopy).
The permutation exchangeability assumption requires the two groups to
have the same noise structure. If the treated group has variance twice
that of the control, the permutation null distribution is wrong and the
band is too narrow. Inspect the group SDs across wavelengths and, if
they differ substantially, use n_perm = 0 (Bonferroni)
instead, or apply a variance-stabilising transform before calling the
function.
Region boundaries are limited by the grid resolution; sub-grid localisation requires interpolation and is not done here. For very large grids (>1000 points) the Bonferroni adjustment becomes extremely conservative; permutation is strongly recommended.
For optical spectroscopy: smooth only when the analyst must, fit
models on raw data when the analyst can, and never report pointwise
tests across a spectrum without simultaneous-band control.
signal_difference_regions() gives the band and the regions;
peak_evidence() indicates whether a candidate peak is real;
adaptive_smoothing() documents the bias it introduces.