repository·master·Indexed 42 days ago
https://github.com/cailab-tamu/sctenifoldknkAn R package for performing virtual knockout experiments on single-cell gene regulatory networks (scGRNs). It simulates the functional impact of knocking out specific genes using wild-type scRNA-seq data through a pipeline involving quality control, normalization, network construction via principal component regression, CP tensor decomposition for denoising, and non-linear manifold alignment to identify differentially regulated genes.
scTenifoldKnk is a component of the scGEAToolbox. You can find the source code for the MATLAB version within the scGEAToolbox repository.The scTenifoldKnk() function orchestrates a virtual knockout pipeline that simulates gene knockouts on single-cell gene regulatory networks (scGRNs). The pipeline follows these steps:
scQC): Filters cells by library size, outlier detection, minimum gene expression fraction, and mitochondrial read ratio.cpmNormalization): Performs Counts-per-million (CPM) normalization.makeNetworks): Builds networks from subsampled cells using principal component regression (pcNet).tensorDecomposition): Uses CANDECOMP/PARAFAC (CP) tensor decomposition to denoise the networks.strictDirection): Enforces directionality in the reconstructed adjacency matrix.manifoldAlignment): Performs non-linear manifold alignment of the WT (wild-type) and KO (knockout) denoised networks.dRegulation): Tests for differential regulation using Box-Cox transformation and chi-square statistics.You can install the stable version of scTenifoldKnk from CRAN or the development version from GitHub using the remotes package.
From CRAN:
install.packages("scTenifoldKnk")From GitHub:
# install.packages("remotes")
remotes::install_github("cailab-tamu/scTenifoldKnk")install.packages("scTenifoldKnk")To perturb every gene in the network (or a specific subset) and measure the impact, set transcriptomeWide = TRUE.
Operating Modes:
gKO = NULL, every gene in the WT network is knocked out sequentially.gKO to only perturb those specific genes.Output Structure: Returns a list containing:
tensorNetworks: A list containing only the WT weight-averaged denoised network.perturbationDistances: A numeric matrix where rows are perturbed genes and columns are all genes in the WT network, representing the manifold-alignment distance for each perturbation.# Perturb every gene
twOutput <- scTenifoldKnk(
countMatrix = X,
transcriptomeWide = TRUE,
nc_nNet = 10,
nc_nCells = 500,
td_K = 3,
qc_minLibSize = 30
)
# Perturb a specific subset
subset <- scTenifoldKnk(
countMatrix = X,
gKO = c("ng10", "ng20"),
transcriptomeWide = TRUE,
qc_minLibSize = 30
)The Python implementation of scTenifoldKnk is maintained in a separate repository. If you require a Python-based workflow instead of the R version, use scTenifoldpy.
Access the Python version here: https://github.com/qwerty239qwe/scTenifoldpy
To perform a single gene knockout, use scTenifoldKnk() with transcriptomeWide = FALSE (the default). You must provide a countMatrix (genes as rows, cells as columns) and specify the target gene symbol in gKO.
Output Structure: Returns a list containing:
tensorNetworks: A list with WT and KO denoised networks (as Matrix objects).manifoldAlignment: A data frame of low-dimensional features from the manifold alignment.diffRegulation: A data frame containing gene, distance, Z, FC, p.value, and p.adj for the differentially regulated genes.output <- scTenifoldKnk(
countMatrix = X,
gKO = "ng10",
nc_nNet = 10,
nc_nCells = 500,
td_K = 3,
qc_minLibSize = 30
)The plotKO() function and the diffRegulation output do not predict the direction (upregulation or downregulation) of expression changes following a virtual knockout.
FC) values in the diffRegulation output are derived from a chi-square test and represent the magnitude of perturbation, not the direction. They are always positive.scTenifoldKnk perturbs only one gene at a time, it cannot account for the net effect of all regulators on a downstream gene's expression.Note on edge colors: While a red edge (positive co-expression) is consistent with a neighbor being downregulated when a positive regulator is removed, this is not a reliable prediction for individual genes due to the multi-regulator nature of gene expression.
The main entry point for the pipeline.
Arguments:
countMatrix: Raw counts matrix (genes as rows, cells as columns).gKO: Single knockout: gene symbol (string). Transcriptome-wide: character vector of genes to perturb; NULL perturbs all.transcriptomeWide: Boolean. If TRUE, returns a distance matrix instead of a differential regulation table.qc: Boolean. Apply quality control (scQC).qc_minLibSize: Minimum library size for a cell to be retained.qc_removeOutlierCells: Boolean. Remove cells whose library size is an outlier.qc_minPCT: Minimum fraction of cells in which a gene must be expressed.qc_maxMTratio: Maximum mitochondrial read ratio per cell (matches ^MT-).nc_lambda: Directionality weighting for weaker edges.nc_nNet: Number of PC-regression networks to generate.nc_nCells: Number of cells subsampled per network.nc_nComp: Number of principal components used for networks.nc_scaleScores: Boolean. Normalize weights so max absolute value is 1.nc_symmetric: Boolean. Return a symmetric weights matrix.nc_q: Cut-off quantile of top relationships to keep.nc_priorNetwork: Optional data.frame with regulators/targets.td_K: Number of rank-one tensors for CP decomposition.td_maxIter: Max tensor-decomposition iterations.td_maxError: Relative Frobenius-norm error tolerance.td_nDecimal: Decimal places retained.ma_nDim: Manifold-alignment dimensions.dr_empiricalNull: Boolean. Use Efron's empirical null (via locfdr) instead of theoretical chi-square.nCores: Number of cores to use.In the plotKO() visualization, edge colors represent the sign of the co-expression relationship between the knocked-out (KO) gene and its neighbors in the wild-type (WT) single-cell gene regulatory network (scGRN). The colors are derived from the edge weight W in the WT adjacency matrix (X$tensorNetworks$WT).
edge.color = ifelse(E(netPlot)$W > 0, 'red', 'blue')Performs differential regulation testing from a manifold alignment.
Arguments:
manifoldOutput: The labeled manifoldAlignment matrix (rows are X_ genes followed by Y_ genes).empiricalNull: Boolean. If TRUE, estimate the null distribution using Efron's empirical null via locfdr instead of the theoretical chi-square null.Returns: A six-column differential regulation table containing: gene, distance, Z, FC, p.value, and p.adj.
Plots the KO-centered subnetwork from a scTenifoldKnk() result.
Arguments:
X: Output list from scTenifoldKnk().gKO: Gene symbol of the simulated knockout gene.q: Edge-weight quantile used to threshold weak edges.annotate: Boolean. Query enrichment databases (enrichR) and overlay category pies on nodes.nCategories: Maximum number of enrichment categories in the legend.fdrThreshold: Adjusted p-value cutoff for reporting enriched terms.Performs standalone single-cell quality control.
Arguments:
X: Raw counts matrix.minLibSize: Minimum library size.removeOutlierCells: Boolean.minPCT: Minimum fraction of cells expressing a gene.maxMTratio: Maximum mitochondrial read ratio.label: Optional string for progress messages.Returns: A dgCMatrix containing only the cells and genes that passed the filters.