scTenifoldKnk

scTenifoldKnk

scTenifoldKnk is an R package for performing virtual knockout experiments on single-cell gene regulatory networks (scGRNs). It uses single-cell RNA-seq (scRNA-seq) data from wild-type (WT) control samples to construct a scGRN, then simulates a gene knockout by zeroing the target gene’s outdegree edges in the adjacency matrix. The resulting knocked-out scGRN is compared with the WT scGRN to identify differentially regulated genes, or virtual-knockout perturbed genes, which reveal the functional impact of the knocked-out gene in the analyzed cell population.

Implementations in other languages are also available:

• Python: scTenifoldpy
• MATLAB: scGEAToolbox

Installation

scTenifoldKnk is available on CRAN:

install.packages("scTenifoldKnk")

To install the development version from GitHub:

# install.packages("remotes")
remotes::install_github("cailab-tamu/scTenifoldKnk")

Pipeline Overview

The scTenifoldKnk() function orchestrates a virtual knockout pipeline built on top of the scTenifoldNet framework. Each step reports progress to the console via the cli package.

Individual functions are exported and fully documented, allowing users to run or modify any step independently.

Input

The required input is a raw counts matrix with genes as rows and cells (barcodes) as columns. Data should be unnormalized when qc = TRUE (the default). The modular design allows users to substitute custom preprocessing at any step.

Operating Modes

scTenifoldKnk() supports two modes, selected with the transcriptomeWide argument:

• Single knockout (transcriptomeWide = FALSE, default) — Knocks out one target gene (gKO) and returns the WT/KO networks, the manifold alignment, and the differential regulation table.
• Transcriptome-wide perturbation (transcriptomeWide = TRUE) — Builds the WT network once, then knocks out every gene in the network (or a user-supplied subset passed through gKO), running the manifold alignment and distance calculation for each. It returns a matrix of perturbation distances instead of a single differential regulation table. Because it performs one alignment per perturbed gene, running time scales with the number of genes.

Function Reference

All functions below are exported and individually documented (?functionName).

scTenifoldKnk()

Main entry point running the full virtual knockout pipeline.

scQC()

Standalone single-cell quality control. Arguments: X (raw counts matrix), minLibSize, removeOutlierCells, minPCT, maxMTratio, and an optional label for progress messages. Returns a dgCMatrix containing the cells and genes that pass the filters.

dRegulation()

Differential regulation testing from a manifold alignment. Arguments: manifoldOutput (the labeled manifoldAlignment matrix, X_ genes followed by Y_ genes in the same order) and empiricalNull (if TRUE, estimate the null distribution of the Z-scores with Efron’s empirical null via the locfdr package instead of the theoretical chi-square null). Returns the six-column differential regulation table described under Output.

plotKO()

Plots the KO-centered subnetwork from a scTenifoldKnk() result.

See also: plotKO() — Frequently Asked Questions

Output

Single knockout mode (transcriptomeWide = FALSE)

scTenifoldKnk() returns a list with three elements:

• tensorNetworks — Weight-averaged denoised gene regulatory networks after CP tensor decomposition, containing:
  • WT: The network for the wild-type condition (a Matrix object).
  • KO: The network for the knocked-out condition (a Matrix object).
• manifoldAlignment — A data frame of low-dimensional features from the non-linear manifold alignment, with 2 × n genes rows and d columns (default d = 2).
• diffRegulation — A data frame with six columns:
  • gene: Gene identifier.
  • distance: Euclidean distance between the gene’s coordinates in the two conditions.
  • Z: Z-score after Box-Cox power transformation.
  • FC: Fold change with respect to the expectation.
  • p.value: P-value from the chi-square distribution with one degree of freedom, or from Efron’s empirical null when dr_empiricalNull = TRUE.
  • p.adj: Adjusted p-value (Benjamini & Hochberg FDR correction).

Transcriptome-wide mode (transcriptomeWide = TRUE)

scTenifoldKnk() returns a list with two elements:

• tensorNetworks — A list with the WT weight-averaged denoised gene regulatory network (WT).
• perturbationDistances — A numeric matrix of manifold-alignment distances. Rows are the perturbed genes, columns are all genes in the WT network, and each entry is the distance of a gene under the corresponding knockout.

Running Time

Running time is largely determined by the network construction step and scales with the number of cells and genes. Representative benchmarks:

Example

Simulating a dataset

We create a sparse count matrix of 2,000 cells and 100 genes drawn from a negative binomial distribution (~67 % zeros). The last ten genes are prefixed with mt- to simulate mitochondrial genes.

library(scTenifoldKnk)

nCells <- 2000
nGenes <- 100
set.seed(1)
X <- rnbinom(n = nGenes * nCells, size = 20, prob = 0.98)
X <- round(X)
X <- matrix(X, ncol = nCells)
rownames(X) <- c(paste0('ng', 1:90), paste0('mt-', 1:10))

Running the virtual knockout

output <- scTenifoldKnk(
  countMatrix   = X,
  gKO           = "ng10",
  nc_nNet       = 10,
  nc_nCells     = 500,
  td_K          = 3,
  qc_minLibSize = 30
)

Exploring the output

# Structure of the output
str(output)

# Accessing the WT and KO gene regulatory networks
dim(output$tensorNetworks$WT)
dim(output$tensorNetworks$KO)

# Accessing the manifold alignment result
head(output$manifoldAlignment)

# Differential regulation results — top perturbed genes
head(output$diffRegulation, n = 10)

# Plotting the KO-centered subnetwork
plotKO(output, gKO = "ng10")

Transcriptome-wide perturbation

Knock out every gene in the WT network and collect the manifold-alignment distances for each perturbation:

twOutput <- scTenifoldKnk(
  countMatrix       = X,
  transcriptomeWide = TRUE,
  nc_nNet           = 10,
  nc_nCells         = 500,
  td_K              = 3,
  qc_minLibSize     = 30
)

# Distance matrix: perturbed genes (rows) by all genes (columns)
dim(twOutput$perturbationDistances)
twOutput$perturbationDistances[1:5, 1:5]

To restrict the perturbation to a subset of genes, pass them through gKO:

subset <- scTenifoldKnk(
  countMatrix       = X,
  gKO               = c("ng10", "ng20"),
  transcriptomeWide = TRUE,
  qc_minLibSize     = 30
)

Citation

Osorio, D., Zhong, Y., Li, G., Xu, Q., Yang, Y., Tian, Y., Chapkin, R., Huang, J. Z., & Cai, J. J. (2022). scTenifoldKnk: An Efficient Virtual Knockout Tool for Gene Function Predictions via Single-Cell Gene Regulatory Network Perturbation. Patterns, 3(3), 100434. doi:10.1016/j.patter.2022.100434

BibTeX:

@Article{osorio2022sctenifoldknk,
  title   = {scTenifoldKnk: An Efficient Virtual Knockout Tool for Gene Function
             Predictions via Single-Cell Gene Regulatory Network Perturbation},
  author  = {Daniel Osorio and Yan Zhong and Guanxun Li and Qian Xu and
             Yongjian Yang and Yanan Tian and Robert Chapkin and
             Jianhua Z. Huang and James J. Cai},
  journal = {Patterns},
  year    = {2022},
  volume  = {3},
  number  = {3},
  pages   = {100434},
  issn    = {2666-3899},
  doi     = {10.1016/j.patter.2022.100434},
}

© The Texas A&M University System. All rights reserved.