SCORPION (version 1.3.3)

testEdges: Test edges from SCORPION networks

Description

Performs statistical testing of network edges from runSCORPION output. Supports single-sample tests (testing if edges differ from zero) and two-sample tests (comparing edges between two groups).

Usage

testEdges(
  networksDF,
  testType = c("single", "two.sample"),
  group1,
  group2 = NULL,
  paired = FALSE,
  alternative = c("two.sided", "greater", "less"),
  padjustMethod = "BH",
  minLog2FC = 0,
  moderateVariance = TRUE,
  empiricalNull = TRUE,
  nCores = 1L,
  batchSize = NULL
)

Value

A data.frame containing:

• tf: Transcription factor

• target: Target gene

• meanEdge: Mean edge weight

• SE: Raw, unmoderated sampling standard error

• tStatistic: Test statistic

• pValue: Raw p-value

• pAdj: Adjusted p-value

• For two-sample tests: meanGroup1, meanGroup2, cohensD, log2FoldChange (Group1 - Group2)

Arguments

networksDF

A data.frame output from runSCORPION containing TF-target pairs as rows and network identifiers as columns.

testType

Character specifying the test type. Options are:

• "single": Single-sample test (one-sample t-test against zero)

• "two.sample": Two-sample comparison (t-test between two groups)

group1

Character vector of column names in networksDF representing the first group (or the only group for single-sample tests).

group2

Character vector of column names in networksDF representing the second group. Required for two-sample tests, ignored for single-sample tests.

paired

Logical indicating whether to perform a paired t-test. Default FALSE. When TRUE, group1 and group2 must have the same length and be in matched order (e.g., group1[1] is paired with group2[1]). Useful for comparing matched samples such as Tumor vs Normal from the same patient.

alternative

Character specifying the alternative hypothesis. Options: "two.sided" (default), "greater", or "less".

padjustMethod

Character specifying the p-value adjustment method for multiple testing correction. See p.adjust for options. Default "BH" (Benjamini-Hochberg FDR).

minLog2FC

Numeric threshold for minimum absolute log2 fold change to include in testing. For two-sample and paired tests, edges with |log2FoldChange| below this threshold are excluded. Not applicable for single-sample tests. Default 0.

moderateVariance

Logical indicating whether to apply SAM-style variance moderation. When TRUE, adds a fudge factor (s0, the median of all standard errors) to the denominator of the t-statistic. This prevents edges with very small variance from producing extreme t-statistics, resulting in volcano plots more similar to limma output. Default TRUE.

empiricalNull

Logical indicating whether to estimate the null distribution empirically from the observed t-statistics. When TRUE, uses the median and MAD (median absolute deviation) of all t-statistics to recenter and rescale them, then computes p-values from the standard normal. This is Efron's empirical null correction (as in locfdr) and is essential when testing millions of correlated edges. Runs in O(n) time. Default TRUE.

nCores

Integer specifying the number of parallel workers. Default 1 (sequential processing). When greater than 1, edges are split into batches and processed in parallel using furrr::future_map_dfr. Requires the furrr and future packages to be installed.

batchSize

Integer specifying the number of edges (rows) per batch for parallel processing. Default NULL, which auto-calculates as ceiling(nrow(networksDF) / nCores). Only used when nCores > 1. Smaller batch sizes use less memory per worker but add communication overhead.

Author

Daniel Osorio <[e-mail]>

Details

For single-sample tests, the function tests whether the mean edge weight across replicates significantly differs from zero using a one-sample t-test.

For two-sample tests, the function compares edge weights between two groups using Welch's t-test (unequal variances assumed).

For paired tests, the function calculates the difference between matched pairs and performs a one-sample t-test on the differences (testing if mean difference differs from zero). This is appropriate when samples are matched (e.g., Tumor and Normal from the same patient).

The returned SE is the raw sampling standard error before optional SAM-style variance moderation. It is intended for downstream effect-size meta-analysis. The moderated SE is used only internally for calculating the test statistic and p-value.

Edges are tested independently, and p-values are adjusted for multiple testing using the specified method.

The function uses fully vectorized computations for efficiency, making it suitable for large-scale analyses with millions of edges. T-statistics and p-values are calculated using matrix operations without iteration.

See Also

runSCORPION, maEdges, circosEdges

Examples

if (FALSE) {
# Load test data and build networks by donor and region
# Note: T = Tumor, N = Normal, B = Border regions
data(scorpionTest)
nets <- runSCORPION(
  gexMatrix = scorpionTest$gex,
  tfMotifs = scorpionTest$tf,
  ppiNet = scorpionTest$ppi,
  cellsMetadata = scorpionTest$metadata,
  groupBy = c("donor", "region")
)

# Single-sample test: Test if edges in Tumor region differ from zero
tumor_nets <- grep("--T$", colnames(nets), value = TRUE)
results_single <- testEdges(
  networksDF = nets,
  testType = "single",
  group1 = tumor_nets
)

# Two-sample test: Compare Tumor vs Border regions
tumor_nets <- grep("--T$", colnames(nets), value = TRUE)
border_nets <- grep("--B$", colnames(nets), value = TRUE)
results_tumor_vs_border <- testEdges(
  networksDF = nets,
  testType = "two.sample",
  group1 = tumor_nets,
  group2 = border_nets
)

# View top differential edges (Tumor vs Border)
head(results_tumor_vs_border[order(results_tumor_vs_border$pAdj), ])

# Compare Tumor vs Normal regions
normal_nets <- grep("--N$", colnames(nets), value = TRUE)
results_tumor_vs_normal <- testEdges(
  networksDF = nets,
  testType = "two.sample",
  group1 = tumor_nets,
  group2 = normal_nets
)

# Filter by minimum log2 fold change for focused analysis
results_filtered <- testEdges(
  networksDF = nets,
  testType = "two.sample",
  group1 = tumor_nets,
  group2 = normal_nets,
  minLog2FC = 0.5
)

# Paired t-test: Compare matched Tumor vs Normal samples
tumor_nets_ordered <- c("P31--T", "P32--T", "P33--T")
normal_nets_ordered <- c("P31--N", "P32--N", "P33--N")
results_paired <- testEdges(
  networksDF = nets,
  testType = "two.sample",
  group1 = tumor_nets_ordered,
  group2 = normal_nets_ordered,
  paired = TRUE
)
}