Run every between-condition discriminability metric

Convenience orchestrator that runs rel_cluster_test() and rel_dissimilarity() on two condition signal matrices and wraps both results in an rcisignal_rel_report for joint printing / plotting.

Use this when you want both the spatial-pattern test and the overall magnitude test in one call.

Usage

run_discriminability(
  signal_matrix_a,
  signal_matrix_b,
  img_dims = NULL,
  n_permutations = 2000L,
  n_boot = 2000L,
  cluster_threshold = 2,
  alpha = 0.05,
  ci_level = 0.95,
  mask = NULL,
  seed = NULL,
  progress = TRUE,
  acknowledge_scaling = FALSE
)

Arguments

signal_matrix_a, signal_matrix_b: Pixels x participants, base-subtracted. Row counts must match.
img_dims: Integer c(nrow, ncol). If NULL, inferred from attr(signal_matrix_a, "img_dims").
n_permutations: Passed to rel_cluster_test(). Default 2000.
n_boot: Passed to rel_dissimilarity(). Default 2000.
cluster_threshold: Passed to rel_cluster_test(). Default 2.0.
alpha: Passed to rel_cluster_test(). Default 0.05.
ci_level: Passed to rel_dissimilarity(). Default 0.95.
mask: Optional logical vector of length nrow(signal_matrix_a) (column-major) threaded through to both downstream calls. Build with make_face_mask() (parametric oval and sub-regions) or read_face_mask() (PNG/JPEG mask).
seed: Optional integer.
progress: Show cli progress bars.
acknowledge_scaling: Logical. Forwarded.

Value

Object of class rcisignal_rel_report with $results = named list of two result objects (cluster_test, dissimilarity) and $method = "discriminability".

Reading the result

$results$cluster_test and $results$dissimilarity, one result object each, fields as in the standalone functions. $method = "discriminability".

Reading the plot

Calling plot(result) lays out one panel per child result (cluster t-map with FWE-significant contours; bootstrap dissimilarity histograms). To plot one panel at a time, call plot(result$results$cluster_test) or plot(result$results$dissimilarity) directly. Color convention on the cluster panel matches the rest of the package: blue = condition A larger; red = condition B larger; black contours bound FWE-significant clusters.

Testing the dissimilarity against chance

The bundled rel_dissimilarity() runs with its default null = "none", so the dissimilarity panel here reports the bootstrap precision interval only. That interval is biased upward by producer resampling and almost always excludes zero even when the two conditions do not differ, so it is not a test of "are these conditions distinguishable?" (see rel_dissimilarity()). For an above-chance test of overall magnitude, call rel_dissimilarity(signal_matrix_a, signal_matrix_b, null = "permutation") directly and read $d_z / $d_ratio and a permutation p against the permutation null. The cluster test in this report is already an FWER-controlled permutation test, so the spatial panel does test against chance.

Reliability metrics expect raw masks

Both downstream metrics are scale-sensitive: the cluster test uses variance-based Welch t, and Euclidean distance in rel_dissimilarity() is sensitive to any scaling. Inputs with attr(., "source") == "rendered" error unless acknowledge_scaling = TRUE.

Examples

if (FALSE) { # \dontrun{
# Two-condition pipeline with signal planted in different face regions
# (eyes vs mouth). The orchestrator runs the cluster test and the
# bootstrap dissimilarity in one call; significant pixels should
# localise around the eye and mouth regions.
sim_eyes  <- simulate_briefrc_data(
  n_per_condition = 20, n_trials = 60, conditions = "x",
  signal_region = "eyes", signal_strength = "strong", seed = 1
)
sim_mouth <- simulate_briefrc_data(
  n_per_condition = 20, n_trials = 60, conditions = "x",
  signal_region = "mouth", signal_strength = "strong", seed = 2
)
sig_eyes  <- ci_from_responses_briefrc(
  sim_eyes$data, noise_matrix = sim_eyes$noise_matrix)$signal_matrix
sig_mouth <- ci_from_responses_briefrc(
  sim_mouth$data, noise_matrix = sim_mouth$noise_matrix)$signal_matrix
res <- run_discriminability(sig_eyes, sig_mouth,
                             n_permutations = 500L, n_boot = 500L,
                             seed = 1)
print(res)
# Whole report (cluster panel + dissimilarity panel side by side):
plot(res)
# Or each panel on its own:
plot(res$results$cluster_test,
     main = "Eyes vs Mouth — cluster test")
plot(res$results$dissimilarity,
     main = "Eyes vs Mouth — dissimilarity")
} # }