The primary goal of this vignette is to validate that discoveries of scale-dependent entropic index × group interactions from Scale-Adaptive Interaction Tests (SAIT) generalize to non-parametric statistical frameworks with minimal assumptions.
Method 1: Generalized Additive Mixed Models (GAMM) with ARIMA-Ordered Measurement Structure.
mgcv::gamm() limitations with extended families in paired designs.mgcv::gamm() limitations.Method 2: Aligned Rank Transform (ART) — State-of-the-art non-parametric interaction testing, with Hochberg Step-Up Correction. Falls back to Conover-Iman Rank Transform via method='rt' if needed.
Statistical testing in transcriptomics faces a fundamental challenge: no single method is universally optimal. Different approaches trade-off power for robustness:
| Aspect | Parametric (GAMM) | Non-Parametric (ART) |
|---|---|---|
| Assumptions | Normality, homoscedasticity | None; aligned ranks, fully non-parametric |
| Power | Highest (if assumptions hold) | Good; reduced but robust to violations |
| Interaction testing | Standard ANOVA-type | Proper interaction tests via alignment (Puri and Sen 1971) |
| Robustness | Moderate | Highest |
| Outlier sensitivity | Moderate potential for bias | Minimal; inherently resistant |
Validation strategy: Concordance between both methods confirms robustness across statistical frameworks.
This section initializes the analysis environment by loading required packages, setting a random seed for reproducibility, and preparing the test dataset.
suppressPackageStartupMessages({
library(ggplot2)
library(SummarizedExperiment)
library(dplyr)
library(gridExtra)
})
set.seed(42)
if (!requireNamespace("devtools", quietly = TRUE)) {
stop("Please install devtools to run this vignette against the local package source.")
}
if ("package:TSENAT" %in% search()) {
detach("package:TSENAT", unload = TRUE, character.only = TRUE)
}
pkg_root <- normalizePath("..", mustWork = FALSE)
devtools::load_all(pkg_root)
# Load preprocessed dataset
data(readcounts)
readcounts <- as.matrix(readcounts)
mode(readcounts) <- "numeric"
# Load metadata
metadata_df <- read.table(
system.file("extdata", "metadata.tsv", package = "TSENAT"),
header = TRUE, sep = "\t"
)
gff3_dataset <- system.file("extdata", "annotation.gff3.gz", package = "TSENAT")
# Configure analysis parameters first (best practice: fail-fast validation)
config <- TSENAT_config(
sample_col = "sample",
condition_col = "condition",
subject_col = "paired_samples",
q = seq(0, 2, by = 0.05),
nthreads = 3,
paired = TRUE,
control = "normal"
)
# Build analysis object: creates SummarizedExperiment and initializes TSENATAnalysis
analysis <- build_analysis(
readcounts = readcounts,
tx2gene = gff3_dataset,
metadata = metadata_df,
tpm = tpm,
effective_length = effective_length,
config = config
)
# Apply filtering for quality control
analysis <- filter_analysis(
analysis,
stringency = "medium"
)
Pseudocounts are critical for statistical robustness when applying non-parametric tests to sparse RNA-seq count data. RNA-seq experiments typically contain many zero or near-zero counts, which creates two problems for rank-based methods:
Ties in rankings: Sparse counts produce many tied values (especially zeros), which reduces the discriminatory power of rank tests. Rank-based statistics depend on unique orderings; when many observations are identical, the test statistic contains less information, reducing statistical power.
Library size artifacts: Small count differences due to sequencing depth variations overshadow true biological differences. Normalized library sizes (accounting for sequencing depth) ensure that entropy estimates reflect true biological diversity rather than technical artifacts (Robinson, McCarthy, and Smyth 2010; Love, Huber, and Anders 2014).
By adding small pseudocounts proportional to library size, we achieve two benefits:
The calculate_diversity() function implements automatic pseudocount selection, scaling pseudocount magnitude and diversity estimates by median library size to ensure robust statistical inference across the range of sequencing depths in your dataset.
# Compute diversity using S4 wrapper with bootstrap confidence intervals
analysis <- calculate_diversity(
analysis,
norm = TRUE,
pseudocount = "auto"
)
TSENAT uses the Aligned Rank Transform (ART) as the default non-parametric method for testing Q×Condition interactions. ART is the state-of-the-art for non-parametric factorial analysis, implemented via the ARTool R package (Kay et al. 2021; Wobbrock et al. 2011). The classical Conover-Iman Rank Transform remains available via method='rt' as a fallback (Conover and Iman 1981).
Tsallis entropy values exhibit inherent distributional properties that often violate parametric assumptions:
ART avoids these issues through alignment and ranking — stripping main effects before ranking preserves interaction structure while eliminating distributional dependence. The aligned ranks are uniformly distributed and contain no outliers, making the method valid for ANY continuous distribution (Puri and Sen 1971; Wobbrock et al. 2011). Critically, rank ordering is unaffected by normalization choice; whether entropy is normalized, log-transformed, or left raw, the test produces identical results (Conover and Iman 1981).
Tsallis entropy has a fundamental sequential property: entropy curves are smooth functions of q. As q increases from 0 (rare-species-emphasizing) to ∞ (common-species-emphasizing), entropy values change systematically. This ordered structure is critical to interpreting q-dependent patterns and exhibits AR(1) autocorrelation: consecutive q-values produce correlated entropy estimates.
ART handles this structure through its alignment step: within-subject ranking after stripping main effects preserves the pairing structure while removing the influence of AR(1) dependence (Puri and Sen 1971; Wobbrock et al. 2011). Autocorrelation in the original entropy values does NOT affect aligned rank ordering or the validity of inference — this property, known as the exchangeability property of rank-based tests, ensures that rank-based inference is valid under any correlation pattern (Ernst 2004; Song 2007).
The implementation uses two-way ANOVA applied to ranks (the modern computational approach):
\[F_{q \times \text{condition}} = \frac{MS_{\text{interaction}}}{MS_{\text{residual}}}\]
where:
This directly tests the core biological question: “Does entropy q-dependence differ between groups?” The aligned rank ANOVA is the modern state-of-the-art approach for non-parametric interaction testing, validated across balanced and unbalanced designs (Wobbrock et al. 2011).
To ensure valid statistical inference, we verify key data assumptions across multiple dimensions.
# Validate statistical assumptions (including GAMM diagnostics)
analysis <- calculate_assumptions(
analysis,
checks = "all" # Include core checks + GAMM diagnostics
)
# Get assumptions
assumptions_text <- results(analysis, type = "assumptions")
print(assumptions_text)
| Test | Result | Interpretation |
|---|---|---|
| Exchangeability (Permutation test) | p=0e+00 | Ordering detected |
| Monotonicity (Spearman rho) | r=0.259 | Heterogeneous |
| Consistency (Kendall’s W / ICC) | W=0e+00, ICC=0.108 | Low |
| Concurvity (Smooth collinearity) | 0.000 | Low |
| EDF Ratio (Smoothing) | 0.024 | Over-smoothed |
| Non-linearity (Delta R^2 vs LM) | 0.0% | Use linear |
| Basis Dimension (Spline basis) | k=10 | Adequate |
| Correlation fit | Observed autocorr=-0.007; independence suitable | Good fit |
| Cluster variation | Mean size=77.0 | Homogeneous |
| Independence | Mean within-cluster residual correlation=-0.018 | Independent |
| Scale parameter | phi=0.100 | Under-dispersed (rare) |
| Variance components | ICC=0.119; B=0.006, W=0.048 | Lmm justified |
| Normality | p=3.57e-27 | Non-normal |
| Homogeneity | p=3.14e-128; CV=0.439 | Heterogeneous |
| Influence | Outliers=778, Extreme=0, Influential=26.6% | Many outliers |
| Variance adequacy | Components for 90%=10, 95%=13, 99%=17 | Poor reduction |
| Bootstrap stability | Bootstrap SE=0.200; Stable CIs=100% | Moderate stability |
Interpretation of Results: The exchangeability test detects strong serial correlation (p ≈ 0), indicating that consecutive samples are more correlated than expected by chance. This violation is not problematic for the Aligned Rank Transform because ART’s alignment step removes main effects before ranking, and rank-based inference satisfies the exchangeability property — a principle ensuring that rank statistics depend only on value ordering, not on correlations in the original data (Conover and Iman 1981; Puri and Sen 1971; Saulsbury 2020). The three reasons outlined above (distributional robustness, paired ordered structure handling, and proper interaction testing via alignment) together make ART ideally suited for multi-q entropy validation without requiring strong distributional assumptions.
Now we use the Aligned Rank Transform (ART, default) — the state-of-the-art non-parametric method for interaction testing — combined with Hochberg step-up correction for multiple testing across genes. ART properly handles factorial interactions by stripping main effects before ranking, providing more reliable Type I error control than classical rank-transform methods.
# Run Aligned Rank Transform (ART, default method)
# This preserves the GAMM results in 'analysis' for later concordance comparison
# Run ART for q × condition interaction
analysis_rank <- calculate_rank_transform(
analysis,
multicorr = "hochberg"
)
# Extract ALL results (no filtering) for summary statistics
rank_transform_results_all <- results(analysis_rank, type = "rank_test", rankBy = "pvalue")
# Extract top significant genes for display
rank_transform_results <- results(analysis_rank, type = "rank_test", rankBy = "pvalue", n = 20, filterFDR = 0.05)
print(head(rank_transform_results, n = 10))
| Metric | Value |
|---|---|
| Genes tested | 77 |
| Significant (p < 0.05) | 3 |
| Significant (adj_p < 0.05, FWER-controlled) | 3 |
| NAs | 0 |
| Mean effect size (\(\eta^2\)) | 0.8% |
| Median effect size (\(\eta^2\)) | 0.4% |
| Strong effect genes (\(\eta^2\) > 10%) | 0 |
| Gene | P-value | Adj. P-value | F-Statistic | Effect Size (η²) | Interaction Class |
|---|---|---|---|---|---|
| CXCL12 | 2.6e-34 | 2e-32 | 9.7609 | 0.0657 | Moderately q-dependent |
| PLP1 | 4.5e-15 | 3.4e-13 | 4.6613 | 0.0364 | Moderately q-dependent |
| LINC03040 | 1.7e-10 | 1.3e-08 | 3.5894 | 0.0470 | Moderately q-dependent |
| EXOC1 | 0.062250 | 1 | 1.4028 | 0.0051 | Robust across q |
| ING3 | 0.069535 | 1 | 1.3854 | 0.0247 | Robust across q |
| METTL26 | 0.081721 | 1 | 1.3593 | 0.0169 | Robust across q |
| RAP1GDS1 | 0.128620 | 1 | 1.2825 | 0.0187 | Robust across q |
| FAM114A2 | 0.317423 | 1 | 1.1030 | 0.0234 | Robust across q |
| ZNF714 | 0.375444 | 1 | 1.0630 | 0.0201 | Robust across q |
| ATG5 | 0.386207 | 1 | 1.0559 | 0.0204 | Robust across q |
Visualize q-curves for top genes:
# Plot top genes from Aligned Rank Transform (ART) (using all genes, not just significant ones)
# This ensures the plot displays n_top genes regardless of significance threshold
top_genes_plot <- plot_diversity_spectrum(analysis, sait_res = rank_transform_results_all, n_top = 4)
print(top_genes_plot)
Figure 1: Supplementary Figure 1 | Aligned Rank Transform (ART) results for scale-dependent isoform switching. Q-curves for top genes identified by ART; compare visual patterns with GAMM results (main vignette Figure 2) to assess method agreement
This section loads precomputed GAMM results generated in the main vignette (TSENAT.Rmd).
# Load precomputed GAMM analysis object from RDS file
analysis_sait <- readRDS(
system.file("extdata", "analysis_sait.rds", package = "TSENAT")
)
# Extract GAMM results for inspection using accessor function
sait_results <- results(analysis_sait, type = "sait", rankBy = "pvalue")
print(sait_results)
| Metric | Value |
|---|---|
| Genes tested | 76 |
| Significant (p < 0.05) | 49 |
| Concordant (p < 0.05 AND adj_p < 0.05) | 33 |
| NAs | 0 |
| Mean effect size | 21.3% |
| Median effect size | 16.7% |
| Strong effect genes (effect_size > 30%) | 19 |
| Model convergence rate | 100.0% |
| Gene | p (interaction) | Adjusted p | Effect size | Test statistic | df |
|---|---|---|---|---|---|
| CXCL12 | 4.63e-88 | 3.52e-86 | 81.6% | 6.00 | 640 |
| THY1 | 3.80e-32 | 2.85e-30 | 60.5% | 3.48 | 640 |
| MEF2A | 1.32e-23 | 9.79e-22 | 20.0% | 0.93 | 642 |
| RAP1GDS1 | 6.85e-20 | 5.00e-18 | 55.2% | 0.85 | 644 |
| GSKIP | 1.40e-18 | 1.01e-16 | 31.1% | 1.01 | 639 |
| DUOXA2 | 5.40e-12 | 3.83e-10 | 30.6% | 8.66 | 560 |
| ING3 | 6.95e-12 | 4.86e-10 | 35.9% | 0.68 | 644 |
| EXOC1 | 1.24e-10 | 8.56e-09 | 23.8% | 0.59 | 643 |
| THOC6 | 1.69e-10 | 1.15e-08 | 14.6% | 1.64 | 642 |
| HDAC2 | 2.64e-10 | 1.77e-08 | 29.0% | 0.61 | 642 |
A critical validation step is to compare whether the Aligned Rank Transform (ART) and GAMM produce consistent results. High concordance between methods (i.e., genes significant in both approaches) provides strong evidence that discoveries are robust to methodological choice. Discordant genes — those significant in only one method — warrant closer inspection: they may represent genuine biological signals revealed by one method’s specific advantages, or artifacts of that method’s assumptions. This section quantifies agreement between approaches and identifies high-confidence genes significant across both statistical frameworks.
# Compute concordance analysis using new two-object API
rank_results <- results(analysis_rank, type = "rank_test")
if (is.null(rank_results) || length(rank_results) == 0) {
stop("Cannot run calculate_concordance(): rank_test results are empty. Ensure calculate_rank_transform() completed successfully.")
}
analysis_rank <- calculate_concordance(
analysis_sait = analysis_sait,
analysis_rank = analysis_rank,
verbose = TRUE
)
# Extract concordance results with list format for component display
concordance_results <- results(analysis_rank, type = "concordance", format = "list")
| Metric | Value |
|---|---|
| Total genes compared | 76 |
| Spearman correlation (p-values) | rho = 0.1097 |
| Both methods significant (p < 0.05) | 1 (1.3%) |
| SAIT only significant | 32 (42.1%) |
| Rank test only significant | 1 (1.3%) |
| Neither significant | 42 (55.3%) |
| Concordance rate | 1.3% |
| Discordance rate | 43.4% |
| Agreement Category | Number of Genes | Percentage |
|---|---|---|
| Both significant | 1 | 1.3% |
| SAIT only | 32 | 42.1% |
| Rank test only | 1 | 1.3% |
| Neither significant | 42 | 55.3% |
| Gene | SAIT adj p | Rank test adj p | SAIT Effect | Rank test rho^2 |
|---|---|---|---|---|
| CXCL12 | 3.52e-86 | 2.020e-32 | 81.6% | 0.066 |
The striking discordance between GAMM and ART results (42.1% significant in GAMM only, 1.3% in ART only, and 1.3% in both methods significant) reflects a fundamental trade-off in statistical methodology: parametric methods maximize power when assumptions hold, while non-parametric methods sacrifice power for robustness to assumption violations.
GAMM’s superior power derives from two factors:
Distributional assumptions: GAMM assumes approximately normal residuals and homogeneous variance, which are reasonable after appropriate transformation for entropy data. Under these assumptions, parametric methods are theoretically optimal, achieving maximum power for a given type I error rate. ART is assumption-free but necessarily discards quantitative information through alignment and ranking, which reduces statistical power when the underlying data are approximately normal.
Model flexibility with penalty: GAMM uses thin-plate splines with smoothness penalties that simultaneously fit nonlinear patterns while controlling degrees of freedom. This flexibility allows GAMM to detect subtle entropic index × group interactions across all q-values. ART operates on aligned rank patterns, which is inherently less sensitive to continuous relationships across q-values but provides superior Type I error control for interaction terms.
This complementary approach—combining high-power parametric tests with robust nonparametric alternatives—provides confidence that discoveries are methodologically sound rather than artifacts of statistical assumptions.
Visual comparison of concordance patterns provides intuitive assessment of which genes align between methods and which are method-specific. The following plots display significance calls, effect sizes, and agreement metrics in a format that facilitates interpretation of both robust discoveries and method-specific findings.
# Create comparison plot using S4 wrapper
# Concordance analysis results are stored in analysis metadata after calculate_concordance()
p <- plot_concordance(analysis_rank, verbose = TRUE)
grid::grid.draw(p)
Figure 2: Supplementary Figure 2 | Method concordance visualization comparing Aligned Rank Transform (ART) and GAMM approaches for detecting q × condition interactions. Scatter plot showing overlap in genes identified as significant by each method; reveals parametric-non-parametric agreement patterns
sessionInfo()
#> R version 4.6.1 (2026-06-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.4 LTS
#>
#> Matrix products: default
#> BLAS: /home/biocbuild/bbs-3.24-bioc/R/lib/libRblas.so
#> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.12.0 LAPACK version 3.12.0
#>
#> locale:
#> [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
#> [3] LC_TIME=en_GB LC_COLLATE=C
#> [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
#> [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
#> [9] LC_ADDRESS=C LC_TELEPHONE=C
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
#>
#> time zone: America/New_York
#> tzcode source: system (glibc)
#>
#> attached base packages:
#> [1] stats4 stats graphics grDevices utils datasets methods
#> [8] base
#>
#> other attached packages:
#> [1] TSENAT_0.99.33 testthat_3.3.2
#> [3] gridExtra_2.3.1 knitr_1.51
#> [5] dplyr_1.2.1 SummarizedExperiment_1.43.0
#> [7] Biobase_2.73.1 GenomicRanges_1.65.1
#> [9] Seqinfo_1.3.0 IRanges_2.47.2
#> [11] S4Vectors_0.51.5 BiocGenerics_0.59.10
#> [13] generics_0.1.4 MatrixGenerics_1.25.0
#> [15] matrixStats_1.5.0 ggplot2_4.0.3
#> [17] kableExtra_1.4.1 BiocStyle_2.41.0
#>
#> loaded via a namespace (and not attached):
#> [1] Rdpack_2.6.6 sandwich_3.1-2 rlang_1.3.0
#> [4] magrittr_2.0.5 multcomp_1.4-31 otel_0.2.0
#> [7] compiler_4.6.1 mgcv_1.9-4 systemfonts_1.3.2
#> [10] vctrs_0.7.3 stringr_1.6.0 pkgconfig_2.0.3
#> [13] fastmap_1.2.0 backports_1.5.1 ellipsis_0.3.3
#> [16] magick_2.9.1 XVector_0.53.0 labeling_0.4.3
#> [19] rmarkdown_2.31 tzdb_0.5.0 sessioninfo_1.2.4
#> [22] nloptr_2.2.1 tinytex_0.60 purrr_1.2.2
#> [25] xfun_0.60 cachem_1.1.0 jsonlite_2.0.0
#> [28] DelayedArray_0.39.3 BiocParallel_1.47.0 broom_1.0.13
#> [31] parallel_4.6.1 R6_2.6.1 bslib_0.11.0
#> [34] stringi_1.8.7 RColorBrewer_1.1-3 pkgload_1.5.3
#> [37] car_3.1-5 boot_1.3-32 brio_1.1.5
#> [40] jquerylib_0.1.4 estimability_2.0.0 Rcpp_1.1.2
#> [43] bookdown_0.47 usethis_3.2.1 zoo_1.8-15
#> [46] readr_2.2.0 Matrix_1.7-6 splines_4.6.1
#> [49] tidyselect_1.2.1 rstudioapi_0.19.0 dichromat_2.0-1
#> [52] abind_1.4-8 yaml_2.3.12 codetools_0.2-20
#> [55] pkgbuild_1.4.8 lattice_0.22-9 tibble_3.3.1
#> [58] plyr_1.8.9 withr_3.0.3 S7_0.2.2
#> [61] coda_0.19-4.1 evaluate_1.0.5 desc_1.4.3
#> [64] survival_3.8-9 xml2_1.6.0 pillar_1.11.1
#> [67] BiocManager_1.30.27 carData_3.0-6 reformulas_0.4.4
#> [70] rprojroot_2.1.1 hms_1.1.4 scales_1.4.0
#> [73] minqa_1.2.8 ARTool_0.11.2 xtable_1.8-8
#> [76] glue_1.8.1 pheatmap_1.0.13 emmeans_2.0.4
#> [79] tools_4.6.1 lme4_2.0-6 fs_2.1.0
#> [82] mvtnorm_1.4-2 cowplot_1.2.0 grid_4.6.1
#> [85] tidyr_1.3.2 rbibutils_2.4.1 devtools_2.5.2
#> [88] nlme_3.1-170 Formula_1.2-5 cli_3.6.6
#> [91] textshaping_1.0.5 S4Arrays_1.13.0 viridisLite_0.4.3
#> [94] geepack_1.3.13 svglite_2.2.2 gtable_0.3.6
#> [97] sass_0.4.10 digest_0.6.39 SparseArray_1.13.2
#> [100] TH.data_1.1-5 farver_2.1.2 memoise_2.0.1
#> [103] htmltools_0.5.9 lifecycle_1.0.5 MASS_7.3-66