Package {scTenifoldKnk}

Type:	Package
Title:	In-Silico Knockout Experiments from Single-Cell Gene Regulatory Networks
Version:	1.1
Description:	A workflow based on 'scTenifoldNet' to perform in-silico knockout experiments using single-cell RNA sequencing (scRNA-seq) data from wild-type (WT) control samples as input. First, the package constructs a single-cell gene regulatory network (scGRN) and knocks out a target gene from the adjacency matrix of the WT scGRN by setting the gene’s outdegree edges to zero. Then, it compares the knocked out scGRN with the WT scGRN to identify differentially regulated genes, called virtual-knockout perturbed genes, which are used to assess the impact of the gene knockout and reveal the gene’s function in the analyzed cells.
URL:	https://github.com/cailab-tamu/scTenifoldKnk
BugReports:	https://github.com/cailab-tamu/scTenifoldKnk/issues
License:	GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Encoding:	UTF-8
RoxygenNote:	7.3.3
Imports:	Matrix, methods, stats, MASS, scTenifoldNet (≥ 1.4), cli, enrichR, igraph, reshape2, grDevices
Suggests:	testthat (≥ 2.1.0), locfdr
NeedsCompilation:	no
Packaged:	2026-09-02 16:22:43 UTC; dcosorioh
Author:	Daniel Osorio [aut, cre], Yan Zhong [aut, ctb], Guanxun Li [aut, ctb], Qian Xu [aut, ctb], Yongjian Yang [aut, ctb], Yanan Tian [aut, ctb], Robert Chapkin [aut, ctb], Jianhua Huang [aut, ctb], James J. Cai [aut, ctb, ths]
Maintainer:	Daniel Osorio <dcosorioh@gmail.com>
Repository:	CRAN
Date/Publication:	2026-09-02 17:20:02 UTC

Evaluates gene differential regulation based on manifold alignment distances.

Description

Using the output of the non-linear manifold alignment, this function computes the Euclidean distance between the coordinates for the same gene in both conditions. Calculated distances are then transformed using Box-Cox power transformation, and standardized to ensure normality. P-values are assigned following the chi-square distribution over the fold-change of the squared distance computed with respect to the expectation, or, when empiricalNull = TRUE, using Efron's empirical null estimated from the Z-scores with locfdr.

Usage

dRegulation(manifoldOutput, empiricalNull = FALSE)

Arguments

Value

A data frame with 6 columns as follows:

• gene A character vector with the gene id identified from the manifoldAlignment output.

• distance A numeric vector of the Euclidean distance computed between the coordinates of the same gene in both conditions.

• Z A numeric vector of the Z-scores computed after Box-Cox power transformation.

• FC A numeric vector of the FC computed with respect to the expectation.

• p.value A numeric vector of the p-values associated to the fold-changes, probabilities are assigned as P[X > x] using the Chi-square distribution with one degree of freedom.

• p.adj A numeric vector of adjusted p-values using Benjamini & Hochberg (1995) FDR correction.

References

• Benjamini, Y., and Yekutieli, D. (2001). The control of the false discovery rate in multiple testing under dependency. Annals of Statistics, 29, 1165-1188. doi: 10.1214/aos/1013699998.

Examples

library(scTenifoldKnk)

# Simulating a dataset following a negative binomial distribution with high sparsity (~67%)
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))

# Performing single-cell quality control
qcOutput <- scQC(
  X = X,
  minLibSize = 30,
  removeOutlierCells = TRUE,
  minPCT = 0.05,
  maxMTratio = 0.1
)

# Computing 3 gene regulatory networks from subsamples of 500 cells
xNetworks <- scTenifoldNet::makeNetworks(
  X = qcOutput,
  nNet = 3,
  nCells = 500,
  nComp = 3,
  scaleScores = TRUE,
  symmetric = FALSE,
  q = 0.95
)

# Computing a K = 3 CANDECOMP/PARAFAC (CP) Tensor Decomposition
tdOutput <- scTenifoldNet::tensorDecomposition(xNetworks, K = 3, maxError = 1e5, maxIter = 1e3)

## Not run: 
# Computing the manifold alignment
maOutput <- scTenifoldNet::manifoldAlignment(tdOutput$X, tdOutput$X)

# Evaluating differential regulation
drOutput <- dRegulation(maOutput)
head(drOutput)

# Plotting — genes with FDR < 0.05 colored in red
geneColor <- ifelse(drOutput$p.adj < 0.05, 'red', 'black')
qqnorm(drOutput$Z, main = 'Standardized Distance', pch = 16, col = geneColor)
qqline(drOutput$Z)

## End(Not run)

Plot KO network

Description

Generate and plot a KO-centered subnetwork from the output of scTenifoldKnk. The function selects genes with significant differential regulation (FDR < 0.05), extracts their interactions from the reconstructed WT network, filters edges by weight quantile, and displays the network using igraph. When annotate = TRUE the function queries enrichment databases via enrichR and overlays category pies on nodes with a legend of significant terms.

Usage

plotKO(
  X,
  gKO,
  q = 0.99,
  annotate = TRUE,
  nCategories = 20,
  fdrThreshold = 0.05
)

Arguments

Value

Invisibly returns NULL. Called for the side effect of plotting the network.

Examples

## Not run: 
library(scTenifoldKnk)

# Load example data
scRNAseq <- system.file("single-cell/example.csv", package = "scTenifoldKnk")
scRNAseq <- read.csv(scRNAseq, row.names = 1)

# Run scTenifoldKnk
output <- scTenifoldKnk(countMatrix = scRNAseq, gKO = "G100", qc_minLibSize = 0)

# Plot the KO-centered subnetwork with enrichment annotation
plotKO(output, gKO = "G100")

# Plot without enrichment annotation
plotKO(output, gKO = "G100", annotate = FALSE)

## End(Not run)

Performs single-cell data quality control

Description

This function performs quality control filters over the provided input matrix. It checks for minimum cell library size, mitochondrial ratio, outlier cells, and the fraction of cells where a gene is expressed.

Usage

scQC(
  X,
  minLibSize = 1000,
  removeOutlierCells = TRUE,
  minPCT = 0.05,
  maxMTratio = 0.1,
  label = NULL
)

Arguments

Value

A dgCMatrix object with the cells and the genes that pass the quality control filters.

References

Ilicic, Tomislav, et al. "Classification of low quality cells from single-cell RNA-seq data." Genome biology 17.1 (2016): 29.

Examples

library(scTenifoldKnk)

# Simulating a dataset following a negative binomial distribution with high sparsity (~67%)
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))

# Performing single-cell quality control
qcOutput <- scQC(
  X = X,
  minLibSize = 30,
  removeOutlierCells = TRUE,
  minPCT = 0.05,
  maxMTratio = 0.1
)

# Comparing dimensions before and after QC
dim(X)
dim(qcOutput)

scTenifoldKNK

Description

Predict gene perturbations using in-silico knockout experiments from single-cell gene regulatory networks.

Usage

scTenifoldKnk(
  countMatrix,
  gKO = NULL,
  transcriptomeWide = FALSE,
  qc = TRUE,
  qc_minLibSize = 1000,
  qc_removeOutlierCells = TRUE,
  qc_minPCT = 0.05,
  qc_maxMTratio = 0.1,
  nc_lambda = 0,
  nc_nNet = 10,
  nc_nCells = 500,
  nc_nComp = 3,
  nc_scaleScores = TRUE,
  nc_symmetric = FALSE,
  nc_q = 0.9,
  nc_priorNetwork = NULL,
  td_K = 3,
  td_maxIter = 1000,
  td_maxError = 1e-05,
  td_nDecimal = 3,
  ma_nDim = 2,
  dr_empiricalNull = FALSE,
  nCores = parallel::detectCores()
)

Arguments

Value

In single knockout mode (transcriptomeWide = FALSE), a list with 3 slots as follows:

• tensorNetworks: The WT and KO weight-averaged denoised gene regulatory networks.

• manifoldAlignment: The generated low-dimensional features result of the non-linear manifold alignment.

• diffRegulation: The results of the differential regulation analysis.

In transcriptome-wide mode (transcriptomeWide = TRUE), a list with 2 slots as follows:

• tensorNetworks: A list with the WT weight-averaged denoised gene regulatory network.

• perturbationDistances: A numeric matrix of manifold-alignment distances with the perturbed genes as rows and all genes in the WT network as columns.

Author(s)

Daniel Osorio <dcosorioh@gmail.com>

Examples

library(scTenifoldKnk)

# Simulating a dataset following a negative binomial distribution with high sparsity (~67%)
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))

## Not run: 
# Running scTenifoldKnk — simulating knockout of gene ng10
output <- scTenifoldKnk(
  countMatrix = X,
  gKO = "ng10",
  nc_nNet = 10,
  nc_nCells = 500,
  td_K = 3,
  qc_minLibSize = 30
)

# 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
twOutput <- scTenifoldKnk(
  countMatrix = X,
  transcriptomeWide = TRUE,
  nc_nNet = 10,
  nc_nCells = 500,
  td_K = 3,
  qc_minLibSize = 30
)

# Matrix of distances: perturbed genes (rows) by all genes (columns)
dim(twOutput$perturbationDistances)
twOutput$perturbationDistances[1:5, 1:5]

## End(Not run)