compute_qf_smd: Compute the SMD of the Network Quadratic Form for Matched...

In scNPM: Single-Cell Network Propensity Matching

Compute the SMD of the Network Quadratic Form for Matched Cluster Pairs

Description

In all-reference mode (version 1.0.3), this helper returns one row per matched pair and reference network, using the exact final network features. The additional column 'network_feature' identifies each reference. The legacy vector interface below remains supported for older results.

Usage

compute_qf_smd(result_list)

Arguments

result_list

Output of [run_scNPM()] (as saved with [save()]).

Details

The legacy network quadratic form qf_i = \theta_i' \Omega_{k(i)} \theta_i enters the propensity score model as an additional covariate. This helper reports the matched-pair SMD of the quadratic form using the same formula as 'smd_covariate_results':

SMD = |mean_t - mean_c| / sqrt((var_t + var_c) / 2)

Two modes are supported (returned in the attribute 'mode'):

• **exact**: 'result_list' contains 'qf_global' and 'final_group_label' (scNPM >= 1.0.1). The helper uses the quadratic forms and labels from the internal final matching call.

• **posterior-approx**: for results saved by older versions (with the heavy 'Result' element stripped), the quadratic form is recomputed from stored sampling summaries ('theta_est', 'invcov_treat_est', 'invcov_ctrl_est', 'group_est'). The legacy mode name is retained for compatibility; these summaries need not approximate the final matching state closely.

Value

A data frame with columns 'treat_cluster', 'matched_control_cluster' and 'qf_smd', rounded to four decimal places. All-reference results additionally include 'network_feature' and contain K * (2 * K) rows; their mode attribute is 'exact-all-reference'. Unmatched or empty pairs have NA. Singleton samples have variance zero. At the numerical zero-variance boundary, equal means give zero and unequal means give infinity, using the matching routine's tolerances.

Examples

# Small synthetic example (exact mode), runs in well under 5 seconds
set.seed(1)
G <- 5; K <- 2; nT <- 30; nC <- 30
invT <- array(diag(G), c(G, G, K)); invC <- array(diag(G), c(G, G, K))
thT <- matrix(rnorm(nT * G), nT, G)
thC <- matrix(rnorm(nC * G, mean = 0.5), nC, G)
qfT <- rowSums((thT %*% invT[, , 1]) * thT)
qfC <- rowSums((thC %*% invC[, , 2]) * thC)
rl <- list(
  K = K,
  matching_result_df = data.frame(treatment_cluster = 1:K,
                                  matched_control_cluster = c(2, 1)),
  qf_global = c(qfT, qfC),
  final_group_label = c(rep(0, nT), rep(K + 1, nC))
)
compute_qf_smd(rl)

scNPM documentation built on Oct. 19, 2026, 5:10 p.m.