nico_covariations package

Subpackages

• nico_covariations.utils package
  • Submodules
  • nico_covariations.utils.pyliger_utilities module
    • NMF_obj_eval()
    • column_group_sub()
    • iNMF()
    • nnlsm_blockpivot()
    • nonneg()
    • normal_eq_comb()
  • Module contents

Submodules

nico_covariations.Covariations module

nico_covariations.Covariations.alignment_score(H, spH, ind_H, ind_spH)

Calculate the alignment score between factors from two different modalities during integrated NMF.

This helper function is used in find_PC_of_invidualCluster_in_SC to evaluate the alignment score between factors from scRNAseq data and spatial data.

Parameters

Hnumpy.ndarray

The matrix representing the factors from the scRNAseq data. Each row corresponds to a sample, and each column corresponds to a factor.

spHnumpy.ndarray

The matrix representing the factors from the spatial data. Each row corresponds to a sample, and each column corresponds to a factor.

ind_Hnumpy.ndarray or list

Indices of the common genes in the scRNAseq data.

ind_spHnumpy.ndarray or list

Indices of the common genes in the spatial data.

Returns

float

The alignment score between the factors from the scRNAseq and spatial data.

Notes

The alignment score is calculated by computing the cosine similarity between the factors of the common genes in the scRNAseq and spatial data. A higher score indicates better alignment between the factors from the two modalities.

nico_covariations.Covariations.compute_PC_space(input, sct_ad_sc_full)

Helper function in gene_covariation_analysis to find the weighted neighborhood average of cell types from the spatial factors.

This function computes the weighted neighborhood average of principal components (PCs) for each cell type from spatial transcriptomics data. The weights are based on the inverse of the distances between neighboring cells.

Parameters

inputobject

An object containing the following attributes:

• spatialcell_unique_clusterid: list of unique spatial cell cluster IDs.

• neighbors: list of neighbors for each cell.

• neigh_distances: list of distances to neighbors for each cell.

• annotation_spatial_barcode_id: list of spatial barcode IDs for each cell.

• annotation_spatial_cluster_id: list of spatial cluster IDs for each cell.

• pc_of_sp_clusterid: matrix of principal components for each spatial cluster ID.

• no_of_pc: int, number of principal components.

• outputname: str, the name of the output file to save the results.

Returns

None

This function saves the weighted neighborhood of factors in a niche to a .npz file specified by input.outputname.

Notes

• This function calculates the weighted average of the principal components (PCs) for each cell’s neighborhood, using the inverse of the distances to its neighbors as weights.

• The result is a matrix where each row represents a cell, and each column represents the weighted average PC values for each cluster in the cell’s neighborhood.

• The weighted neighborhood feature matrix is saved to a file in .npz format.

nico_covariations.Covariations.create_directory(outputFolder)

Create an empty directory.

This function checks if a specified directory exists, and if not, it creates the directory.

Parameters

outputFolderstr

The path of the directory to be created.

Raises

OSError

If the directory cannot be created due to permission issues or other OS-related errors.

Notes

• If the directory already exists, no action is taken.

• This function ensures that the directory path is available for subsequent file operations.

Example

>>> create_directory('./new_out/')

nico_covariations.Covariations.create_subtitle(fig: Figure, grid: SubplotSpec, title: str)

Add a title to a specific set of subplots within a figure.

This helper function is used to create a title for a subset of plots within a Matplotlib figure. The title is added with a specific formatting and the subplot is hidden from view (no axes or frames).

Parameters:

figmatplotlib.figure.Figure

The figure object to which the subplot belongs.

gridmatplotlib.gridspec.SubplotSpec

The subplot specification that defines the location and size of the subplot within the figure.

titlestr

The title text to be displayed above the subplot.

nico_covariations.Covariations.extract_and_plot_top_genes_from_chosen_factor_in_celltype(input, choose_celltype, choose_factor_id, top_NOG=30, rps_rpl_mt_genes_included=True, correlation_with_spearman=True, positively_correlated=True, saveas='pdf', cmap='RdBu_r', transparent_mode=False, showit=True, dpi=300, figsize=(5, 6))

Extract and plot top genes associated with a chosen factor in a specified cell type.

This function uses the output from gene_covariation_analysis to identify and visualize the top genes associated with a chosen factor in a specified cell type. The genes can be filtered and visualized based on their correlation with the factor, with options to include or exclude specific gene types.

Parameters

inputobject

The main input is the output from gene_covariation_analysis.

choose_celltypestr

Define the cell type to include in the analysis.

choose_factor_idint

Define the factor ID of the cell type to be analyzed.

top_NOGint, optional

Number of top genes to visualize. (default is 30)

rps_rpl_mt_genes_includedbool, optional

Decide whether to include rps, rpl, and mt genes in the pathway analysis. If True, they are included. (default is True)

correlation_with_spearmanbool, optional

If True, visualize gene-factor association using the Spearman correlation coefficient; otherwise, use cosine similarity. (default is True)

positively_correlatedbool, optional

If the gene-factor association is selected as Spearman correlation, choose whether the associated genes should be positively correlated (True) or negatively correlated (False). (default is True)

saveasstr, optional

Save the figures in PDF or PNG format (dpi for PNG format is 300). (default is ‘pdf’)

cmapstr, optional

Define the colormap for visualizing factors. (default is ‘RdBu_r’)

transparent_modebool, optional

Define the background color of the figures. If True, figures have a transparent background. (default is False)

showitbool, optional

If True, the generated figures will be displayed. (default is True)

figsizetuple, optional

Dimension of the figure size. (default is (5, 6))

Outputs

pd.DataFrame

Returns a DataFrame containing the gene, factor, average expression, and proportion of the population expressing that gene.

Notes

• The function saves the figures in the directory “nico_out/covariations_R*_F*/dotplots/Factors*”.

• The DataFrame returned includes detailed information about the top genes associated with the chosen factor.

Example

>>> extract_and_plot_top_genes_from_chosen_factor_in_celltype(input_data, 'CellTypeA', 1, top_NOG=50, saveas='png', figsize=(10, 8))

nico_covariations.Covariations.findXYZC(c, s)

Helper function used in plot_top_selected_genes_as_dotplot.

This function extracts and transforms data from the given matrices c and s, creating four lists: x-coordinates, y-coordinates, values (z), and sizes (bigs).

Parameters

carray-like

A 2D array (matrix) where each element represents a value at a specific (i, j) coordinate.

sarray-like

A 2D array (matrix) of the same shape as c, where each element represents a size multiplier for the corresponding element in c.

Returns

xlist

List of x-coordinates for each element in c.

ylist

List of y-coordinates for each element in c.

zlist

List of values from c corresponding to each (x, y) coordinate.

bigslist

List of sizes, where each size is calculated as 100 times the corresponding element in s.

nico_covariations.Covariations.find_LR_interactions_in_interacting_cell_types(input, choose_interacting_celltype_pair=[], choose_factors_id=[], pvalueCutoff=0.05, dpi=300, correlation_with_spearman=True, LR_plot_NMF_Fa_thres=0.2, LR_plot_Exp_thres=0.2, saveas='pdf', transparent_mode=False, showit=True, figsize=(12, 10))

Find ligand-receptor (LR) interactions in interacting cell types and visualize them.

This function processes the output from gene_covariation_analysis to identify significant LR interactions between specified cell type pairs and visualizes the results.

Parameters

inputobject

The main input is the output from gene_covariation_analysis.

choose_interacting_celltype_pairlist, optional

Define the cell type pairs for which information on LR communication should be returned. The first element of the list is the central cell type (CC), and the second element is the niche cell type (NC). If the list is empty, LR interactions will be returned for all significant interacting cell types. Default is [].

choose_factors_idlist, optional

Define factor IDs for which LR interactions are visualized. The first element of the list is the factor ID of the central cell type, and the second element is the factor ID of the niche cell type. If the list is empty, LR plots will be saved for all significant niche cell type factor interactions. Default is [].

pvalueCutofffloat, optional

The p-value cutoff used to find the significant central cell type factor and niche cell type factor interactions. Default is 0.05.

correlation_with_spearmanbool, optional

If True, compute gene-factor correlation as Spearman correlation coefficient; otherwise, compute as cosine similarity. Default is True.

LR_plot_NMF_Fa_thresfloat, optional

Only ligands or receptors that exhibit a correlation to the respective factors higher than this cutoff are retained. Default is 0.2.

LR_plot_Exp_thresfloat, optional

Only ligands or receptors that are expressed in a fraction of cells of the respective cell types exceeding this cutoff are retained. Default is 0.2.

saveasstr, optional

Save the figures in PDF or PNG format (dpi for PNG format is 300). Default is ‘pdf’.

transparent_modebool, optional

Background color in the figures. Default is False.

showitbool, optional

If True, the figures are shown interactively. Default is True.

figsizetuple, optional

Dimension of the figure size. The figure size on the X-axis direction is the (number of genes) multiplied by factor 12/34. The figure size on the Y-axis direction is the (number of genes) multiplied by factor 10/44. All generated figure size are scaled according to the above factors. Initital figure size is (12, 10).

Outputs

• The LR interaction figures are saved in “./nico_out/covariations_R*_F*/Plot_ligand_receptor_in_niche*”.

Notes

• Our analysis accounts for bidirectional cellular crosstalk interactions of ligands and receptors in cell types A and B.

• The ligand can be expressed on cell type A and signal to the receptor detected on cell type B, or vice versa.

• Both ligand-receptor plots and Excel sheets profile bidirectional cellular crosstalk of ligand and receptor in cell types A and B.

nico_covariations.Covariations.find_PC_of_invidualCluster_in_SC(seed, spatial_integration_modality, scbarcode, iNMFmode, scadata, no_of_pc, spbarcode, spadata, sct_ad_sc_full, celltype_name, cutoff_to_count_exp_cell_population)

Helper function used in compute_PC_space to find principal components (PCs) for individual clusters in single-cell RNA sequencing (scRNA-seq) data and spatial transcriptomics data.

This function integrates scRNA-seq and spatial transcriptomics data using non-negative matrix factorization (NMF) or integrative NMF (iNMF), and computes the alignment score, correlation, and other metrics for the identified principal components.

Parameters

seedint

Random seed for reproducibility.

spatial_integration_modalitystr

Modality for spatial integration, either ‘single’ or ‘double’.

scbarcodelist

List of single-cell barcodes.

iNMFmodebool

Flag indicating whether to use iNMF (True) or not (False).

scadataAnnData

Single-cell RNA-seq data in AnnData format.

no_of_pcint

Number of principal components to compute.

spbarcodelist

List of spatial transcriptomics barcodes.

spadataAnnData

Spatial transcriptomics data in AnnData format.

sct_ad_sc_fullAnnData

Full single-cell RNA-seq data in AnnData format.

celltype_namestr

Name of the cell type being analyzed.

cutoff_to_count_exp_cell_populationfloat

Expression cutoff to count the proportion of cell population expressing a gene.

Returns

transfer_sp_comndarray

Transformed spatial component matrix.

transfer_sc_comlist

Transformed single-cell component matrix (currently not populated).

sc_spearmanndarray

Spearman correlation between genes and principal components in single-cell data.

sc_cosinendarray

Cosine similarity between genes and principal components in single-cell data.

sc_genenamesndarray

Array of gene names.

Hndarray

Principal component matrix for single-cell data.

spHndarray

Principal component matrix for spatial data.

sc_cluster_mean_expndarray

Mean expression of genes across single-cell clusters.

sc_cluster_exp_more_than_thresholdndarray

Proportion of single-cell clusters expressing genes above the cutoff.

alphaint

Optimal alpha value used in iNMF.

Notes

• This function normalizes gene expression data and computes principal components using either NMF or iNMF.

• It calculates the alignment score for spatial and single-cell data integration.

• Spearman correlation and cosine similarity between genes and PCs are computed.

• The results include the transformed spatial component matrix, gene correlations, and other metrics for downstream analysis.

nico_covariations.Covariations.find_correlation_bw_genes_and_PC_component_in_singlecell(KcomponentCluster, clusterExpression)

Calculate Spearman correlation between genes and principal components in single-cell data.

This helper function is used within the find_PC_of_invidualCluster_in_SC function to determine the Spearman correlation between common gene scRNAseq factors (principal components) and scRNAseq gene expression data.

Parameters

KcomponentClusternumpy.ndarray or pandas.DataFrame

The matrix representing the principal components (factors) from scRNAseq data. Each column corresponds to a principal component.

clusterExpressionnumpy.ndarray or pandas.DataFrame

The matrix representing the gene expression data from scRNAseq. Each row corresponds to a gene and each column corresponds to a cell.

nico_covariations.Covariations.find_correlation_bw_genes_and_PC_component_in_singlecell_cosine(KcomponentCluster, clusterExpression)

Calculate cosine similarity between common gene scRNAseq factors and scRNAseq count data.

This helper function is used within the find_PC_of_invidualCluster_in_SC function to determine the cosine similarity between common gene scRNAseq factors (principal components) and scRNAseq gene expression data.

Parameters

KcomponentClusternumpy.ndarray or pandas.DataFrame

The matrix representing the principal components (factors) from scRNAseq data. Each column corresponds to a principal component.

clusterExpressionnumpy.ndarray or pandas.DataFrame

The matrix representing the gene expression data from scRNAseq. Each row corresponds to a gene and each column corresponds to a cell.

Returns

numpy.ndarray

A matrix containing the cosine similarity scores between each gene and each principal component. Each row corresponds to a gene, and each column corresponds to a principal component.

nico_covariations.Covariations.find_fold_change(PCA, NH_PCA, gene, CCPC, NCPC, totalLRpairs, LRcutoff, CC_meanExpression, NC_meanExpression, CC_popExpression, NC_popExpression, number_of_top_genes_to_print)

Identify ligand-receptor genes for cell type interaction analysis.

This helper function is used in find_LR_interactions_in_interacting_cell_types to find ligand-receptor (LR) genes based on principal component analysis (PCA) data. It identifies the top genes and checks for LR interactions between specific cell types.

Parameters:

PCAnumpy.ndarray

PCA data for the cell type of interest.

NH_PCAnumpy.ndarray

PCA data for non-host cell types.

genelist of str

List of gene names corresponding to the PCA data.

CCPCint

Principal component index for the cell type of interest.

NCPCint

Principal component index for the non-host cell type.

totalLRpairslist of tuples

List of tuples representing all possible ligand-receptor pairs.

LRcutofffloat

Threshold for selecting significant ligand-receptor interactions.

CC_meanExpressionnumpy.ndarray

Mean expression values for the central cell type.

NC_meanExpressionnumpy.ndarray

Mean expression values for the niche cell type.

CC_popExpressionnumpy.ndarray

Population expression values for the central cell type.

NC_popExpressionnumpy.ndarray

Population expression values for the niche cell type.

number_of_top_genes_to_printint

Number of top genes to include in the output.

Returns:

cc_geneslist of str

List of significant genes for the cell type of interest.

nc_geneslist of str

List of significant genes for the non-host cell type.

cc_genes5list of list

Top genes for the cell type of interest with their PCA scores.

nc_genes5list of list

Top genes for the non-host cell type with their PCA scores.

Found1list of list

Ligand-receptor pairs with ligands in the cell type of interest and receptors in the non-host cell type.

Found2list of list

Ligand-receptor pairs with ligands in the non-host cell type and receptors in the cell type of interest.

nico_covariations.Covariations.find_index(sp_genename, sc_genename)

Find the common gene space submatrix between two modalities.

This helper function is used within the gene_covariation_analysis function to identify the indices of common genes between two lists of gene names corresponding to spatial and scRNAseq modalities.

Parameters

sp_genenamelist

A list of gene names from the spatial modality.

sc_genenamelist

A list of gene names from the scRNAseq modality.

Returns

list

A list of indices corresponding to the common genes found in both sp_genename and sc_genename.

Example

>>> sp_genes = ['gene1', 'gene2', 'gene3', 'gene4']
>>> sc_genes = ['gene3', 'gene4', 'gene5', 'gene6']
>>> index_sp,index_sc = find_index(sp_genes, sc_genes)
>>> print(index_sp)
[2, 3]

nico_covariations.Covariations.find_interest_of_genes(source, pop, mu, rps_rpl_mt_genes_included, CC_gene, top_NOG)

Find genes of interest based on factor values, population expression, and average expression.

Parameters:

sourcenp.array

Factor values associated with genes.

popnp.array

Population expression values.

munp.array

Mean expression values.

rps_rpl_mt_genes_includedbool

Include Rps, Rpl, and mt genes if True.

CC_genenp.array

List of gene names.

top_NOGint

Number of genes to select.

Returns:

gp1list

Genes of interest based on factor values.

vp1list

Corresponding factor values of the selected genes.

nico_covariations.Covariations.find_logistic_regression_interacting_score(cmn, coef, CTFeatures, nameOfCellType, logistic_coef_cutoff)

Helper function used in gene_covariation_analysis to find niche interaction scores from logistic regression classifier.

This function identifies the interacting cell types by analyzing the coefficients of a logistic regression classifier. It normalizes the coefficients, sorts them, and identifies the significant interactions based on a specified cutoff value.

Parameters

cmnarray

Confusion matrix or similar matrix representing the performance of the logistic regression classifier.

coefarray

Coefficients of the logistic regression model.

CTFeatureslist

List of cell type features used in the logistic regression model.

nameOfCellTypelist

List of names corresponding to cell types.

logistic_coef_cutofffloat

The cutoff value to consider a coefficient as significant for interaction.

Returns

logistic_predicted_interactionsdict

A dictionary where keys are cell types and values are lists of interacting cell types with their interaction scores.

Notes

• The function normalizes the logistic regression coefficients.

• It identifies the most significant interactions based on the absolute value of the coefficients.

• Interactions with coefficients above the cutoff value are considered significant and are included in the output.

nico_covariations.Covariations.gene_covariation_analysis(Radius=0, output_niche_prediction_dir=None, refpath='./inputRef/', quepath='./inputQuery/', ref_cluster_tag='cluster', ref_original_counts='Original_counts.h5ad', LRdbFilename='./utils/NiCoLRdb.txt', iNMFmode=True, no_of_factors=3, shap_analysis=False, shap_cluster_cutoff=0.5, cutoff_to_count_exp_cell_population=0, seed=541, spatial_integration_modality='double', anndata_object_name='nico_celltype_annotation.h5ad', lambda_c=[0.0009765625, 0.001953125, 0.00390625, 0.0078125, 0.015625, 0.03125, 0.0625, 0.125, 0.25, 0.5, 1.0, 2.0, 4.0, 8.0, 16.0, 32.0, 64.0, 128.0, 256.0, 512.0], coeff_cutoff_for_rid_reg=0, logistic_coef_cutoff=0)

Perform gene covariation analysis within the niche.

This is the primary function called by the user to perform gene covariation analysis within the niche. Before calling this function, the user must call the spatial_neighborhood_analysis function from the interaction module.

Parameters

Radiusint, optional

This radius parameter should be the same as used in spatial neighborhood analysis to find the niche interactions. Default is 0.

output_niche_prediction_dirstr, optional

The output directory location from the previous niche interaction runs generated by the function spatial_neighborhood_analysis. Default is ‘./nico_out/’.

refpathstr, optional

Path to the reference scRNAseq count matrix in scTransform-like normalization. The filename must be sct_singleCell.h5ad. Default is ‘./inputRef/’.

quepathstr, optional

Path to the query spatial count matrix in scTransform-like normalization. The filename must be sct_spatial.h5ad. Default is ‘./inputQuery/’.

ref_cluster_tagstr, optional

The slot in the reference anndata object file where cell type information is stored. Default is ‘cluster’.

ref_original_countsstr, optional

Path to the original count data of scRNAseq in anndata object. Must have the cluster information in .obs and the umap information in .obsm[‘X_umap’]. anndata.raw layer should have count matrix data. It will used to find the Spearman correlation and cosine similarity. Default is ‘Original_counts.h5ad’.

LRdbFilenamestr, optional

Filename of the ligand-receptor database. The first column should be Ligand, the second column Receptor, and the third column the resource list. Default is ‘./utils/NiCoLRdb.txt’.

iNMFmodebool, optional

If True, uses an integrated NMF approach to learn a gene-by-factor submatrix from both modalities. If False, uses an ordinary NMF approach to learn a gene by factor submatrix only from scRNAseq data and transfers these factors to the spatial modality for learning the gene weights. Default is True.

no_of_factorsint, optional

Number of factors used in NMF for finding the common gene latent dimension space. Default is 3.

lambda_clist, optional

Initial range of regularization parameters used in the ridge regression step to find the optimal parameter. Default is list(np.power(2.0, np.arange(-10, 10))).

shap_analysisbool, optional

Flag to perform SHAP analysis. Default is False.

shap_cluster_cutofffloat, optional

SHAP analysis cutoff parameter. Default is 0.5.

coeff_cutoff_for_rid_regfloat, optional

Cutoff used to create the list of significant celltype_factor-celltype_factor niche covariations with an absolute regression coefficient greater than this. Default is 0.

cutoff_to_count_exp_cell_populationint, optional

Parameter to find the percentage of the cell population that express a given gene in a given cell type. Value 0 is acceptable with count data. Default is 0.

seedint, optional

Random seed used in RepeatedStratifiedKFold. Default is 541.

spatial_integration_modalitystr, optional

Modality for spatial integration if both scRNAseq and Spatial data is available. Default is ‘double’. For only spatial data this value must be ‘single’

anndata_object_namestr, optional

Name of the spatial anndata object name. Default is ‘nico_celltype_annotation.h5ad’.

logistic_coef_cutofffloat, optional

Cutoff to retrieve the positive niche interactions (cell type - cell type). For values >0, cell type pairs are likely to interact. Default is 0.

Outputs

The output is saved in the directory specified by output_niche_prediction_dir, with default location being ‘./nico_out/covariations_R*_F*’.

Notes

• Please provide Original_counts.h5ad, sct_singleCell.h5ad files from scRNAseq data.

• Provide sct_spatial.h5ad files for the spatial transcriptomics data.

• Original_counts.h5ad object should also have the cluster information in .obs and the umap information in .obsm and .raw layer has count data.

nico_covariations.Covariations.makePCneighboorhoodFeatureMatrix(input)

Helper function in gene_covariation_analysis to find the weighted neighborhood average of cell types from the spatial factors.

This function computes a matrix where each row corresponds to a cell and each column corresponds to a weighted average of principal components (PCs) from neighboring cells.

Parameters:

inputobject

An object containing various attributes required for computation, such as:

• spatialcell_unique_clusterid: Unique cluster IDs for spatial cells.

• neighbors: List of neighboring cells for each cell.

• neigh_distances: Distances to neighbors.

• annotation_spatial_barcode_id: Barcode IDs for spatial annotations.

• annotation_spatial_cluster_id: Cluster IDs for spatial annotations.

• pc_of_sp_clusterid: Principal components for spatial cluster IDs.

• no_of_pc: Number of principal components.

• outputname: Name of the output file.

Outputs:

A .npz file containing the matrix of weighted neighborhood principal components.

nico_covariations.Covariations.make_excel_sheet_for_gene_correlation(input)

Create an Excel sheet compiling gene correlations with factors across different cell types.

This function generates an Excel sheet that provides a structured and accessible representation of gene factors associated with cell types. It includes various types of information, such as average gene expression, Spearman correlation values, and cosine similarity values for both scRNASeq and spatial data.

Parameters

inputobject

The main input is the output from gene_covariation_analysis.

Outputs

• Excel sheets categorized into different types of information:

  • ‘avg gene exp’: Average gene expression.

  • ‘spearman scRNAseq Fa(i)’: Spearman correlation values for different factors within scRNASeq data.

  • ‘cosine scRNAseq Fa(i)’: Cosine similarity values within scRNASeq data.

  • ‘spearman spatial Fa(i)’: Spearman correlation values for common genes in the spatial data.

  • ‘cosine spatial Fa(i)’: Cosine similarity values for common genes in the spatial data.

Notes

• In the sheet names, ‘i’ corresponds to the factor ID.

• Columns include factors representing all cell types.

• For each factor, genes are sorted based on their association with the factor ID corresponding to the respective sheet.

• A color-coding scheme is used to distinguish genes:

  • Ligands are depicted in blue.

  • Receptors are depicted in red.

  • Genes with both ligand and receptor functions are depicted in magenta.

nico_covariations.Covariations.model_linear_regression(input, logistic_predicted_interactions)

Helper function for gene_covariation_analysis to prepare data Y (central cell factors) and X (neighborhood average spatial cell factors) for each cell type to perform regression.

This function loads the precomputed neighborhood feature matrix and prepares the data for linear regression analysis. It then performs ridge regression for each cell type to find the relationship between the central cell factors (Y) and the neighborhood average spatial cell factors (X).

Parameters

inputobject

An object containing the following attributes:

• shap_cluster_cutoff : float, cutoff value for SHAP clustering.

• outputname : str, the name of the input file containing precomputed neighborhood features.

• no_of_pc : int, number of principal components.

• spatialcell_unique_clusterid : list, unique cluster IDs of spatial cells.

• annotation_spatial_cluster_id : list, cluster IDs for each spatial cell.

• spatialcell_unique_clustername : list, unique cluster names of spatial cells.

• seed : int, seed value for regression.

• lambda_c : float, regularization parameter for ridge regression.

• K_fold : int, number of folds for cross-validation.

• n_repeats : int, number of repeats for cross-validation.

logistic_predicted_interactionsdict

A dictionary where keys are cell type names and values are lists of tuples. Each tuple contains a cell type name and a score representing the predicted interaction strength with the key cell type.

Returns

save_coefdict

A dictionary where keys are unique cluster IDs and values are lists containing the following elements:

• coef : array, coefficients of the ridge regression model.

• intercept : array, intercepts of the ridge regression model.

• alpha : float, regularization parameter of the ridge regression model.

• xlabel : array, names of the features.

• score : array, scores of the features.

• target : array, target values (central cell factors).

• neighborhoodClass : array, neighborhood average spatial cell factors.

• pv : array, p-values of the regression coefficients.

• percent_variance_explained : array, percentage of variance explained by the model.

• residual_variance_explained : array, residual variance explained by the model.

Notes

• The function uses ridge regression to model the relationship between central cell factors and neighborhood factors.

• The precomputed neighborhood feature matrix is loaded from a file and NaN values are replaced with zeros.

• The function selects relevant features based on logistic_predicted_interactions and performs ridge regression.

• The results are stored in a dictionary and returned for further analysis.

nico_covariations.Covariations.multiplicative_method(W, H, A, max_iter)

Perform conventional Non-negative Matrix Factorization (NMF) using a multiplicative update rule.

This helper function is used in find_PC_of_invidualCluster_in_SC to decompose matrix A into two non-negative matrices W and H such that A ≈ W @ H.

Wndarray

Initial matrix representing the basis vectors. Shape(n_samples, n_components).

Hndarray

Initial matrix representing the coefficients. Shape(n_components, n_features).

Andarray

The input data matrix to be factorized. Shape(n_samples, n_features).

max_iterint

The maximum number of iterations for the multiplicative update algorithm.

Wndarray

Updated basis matrix after NMF. Shape: (n_samples, n_components).

Hndarray

Updated coefficient matrix after NMF. Shape: (n_components, n_features).

normslist

List of Frobenius norms of the difference between A and W @ H for each iteration.

The update rules for W and H are based on minimizing the Frobenius norm of the difference between A and W @ H. The update for H is performed as:

\[H_{ij} = H_{ij} \]

rac{(W^T A)_{ij}}{(W^T W H)_{ij} + epsilon}

where ε is a small constant to prevent division by zero.

The update for W has been commented out but follows a similar form. Uncomment the lines under “Update W” to perform updates for W as well.

\[W_{ij} = W_{ij} \]

rac{(A H^T)_{ij}}{(W H H^T)_{ij} + epsilon}

This method is sensitive to initializations of W and H, and the results may vary across runs.

nico_covariations.Covariations.pathway_analysis(input, NOG_pathway=50, choose_factors_id=[], correlation_with_spearman=True, saveas='pdf', savefigure=False, positively_correlated=True, rps_rpl_mt_genes_included=True, choose_celltypes=[], circlesize=12, pvalue_cutoff_enrichr=0.05, pathwayorganism='Mouse', database=['GO_Biological_Process_2021', 'BioPlanet_2019', 'Reactome_2016'], dotplot_x_order=False, dotplot_y_order=False, pvalue_cutoff=0.05, top_term=10, figsize=(4, 6), dotplot_xticklabels_rot=None, dotplot_yticklabels_rot=None, dotplot_marker='o', dotplot_show_ring=False, object_for_sorting='Adjusted P-value', object_for_color='Adjusted P-value', object_for_xaxis='Odds Ratio', object_for_yaxis='Term', barplot_edgecolor='black', barplot_linewidth=0.5, barplot_ascending_order=True, barplot_colorbar_length_shrink=0.5, barplot_log10_pvalue_roundoff=2, display_plot_as='barplot', fontsize=12, showit=True, transparent_mode=False, dpi=300, input_colormap='hot_r')

Perform pathway enrichment analysis for gene covariations within cell type niches.

This function analyzes the gene covariation identified through NMF or iNMF in gene_covariation_analysis and perform pathway enrichment analysis using the GSEApy library. Enriched pathways associated with specific cell types and NMF latent factors are visualized in bar or dot plots.

Parameters

inputobject

The main input object, which is the output from the gene_covariation_analysis.

NOG_pathwayint, optional

The number of top genes associated with each NMF factor to include in the pathway enrichment analysis. If no pathways are observed, increase the number of genes or try different databases. (default is 50)

choose_factors_idlist, optional

A list of specific factor IDs for which pathway enrichments analysis should be conducted. If empty, enrichment will be computed for all factors. (default is [])

correlation_with_spearmanbool, optional

If True, uses Spearman correlation coefficient for gene-factor association; otherwise, use cosine similarity. (default is True)

positively_correlatedbool, optional

If True, selects positively correlated genes for enrichment analysis; otherwise, selects negatively correlated genes. (default is True)

rps_rpl_mt_genes_includedbool, optional

If True, include rps, rpl, and mt- genes in the pathway enrichment analysis; if False, exclude these genes. (default is True)

pvalue_cutoff_enrichrfloat, optional

The significance threshold for including pathways in the gseapy.enrichr (based on adjusted p-value). It show enriched terms which Adjusted P-value < cutoff. Only affects the output figure, not the final output file. (default is 0.05) For detail see here https://gseapy.readthedocs.io/en/latest/run.html

pvalue_cutofffloat, optional

Terms with column value < cut-off are shown. Work only for (“Adjusted P-value”, “P-value”, “NOM p-val”, “FDR q-val”) https://gseapy.readthedocs.io/en/latest/run.html

pathwayorganismstr, optional

The organism for which to perform pathway analysis, supported by the GSEApy package (e.g., ‘Mouse’, ‘Human’). (default is ‘Mouse’)

databaselist, optional

A list of pathway databases to use for enrichment analysis in GSEApy package. The options includes ‘GO_Biological_Process_2021’, ‘BioPlanet_2019’, and ‘Reactome_2016’. See detail to find available databases https://gseapy.readthedocs.io/en/latest/gseapy_example.html (default is [‘GO_Biological_Process_2021’, ‘BioPlanet_2019’, ‘Reactome_2016’])

choose_celltypeslist, optional

A list of cell types for which pathway enrichment analysis should be performed. If empty, analysis will be performed for all cell types. (default is [])

saveasstr, optional

The file format for saving figures, either in PDF or PNG format. (default is ‘pdf’)

circlesizeint, optional

The size of the dots in the dot plots in pathway enrichment visualization. Increase this value to control marker size in the visualization. (default is 12)

savefigurebool, optional

If True, saves the generated figures to the specified path. (default is False)

display_plot_asstr, optional

The format for displaying the pathway analysis plot, either ‘barplot’ or ‘dotplot’. (default is ‘barplot’)

fontsizeint, optional

The font size for labels in the pathway visualization plots. (default is 12)

input_colormapstr, optional

The color map used for visualizing the pathways, available from matplotlib. Please look for all the available colormap https://matplotlib.org/stable/users/explain/colors/colormaps.html Popular choices are ‘autumn_r’, ‘RdBu_r’, ‘viridis’, ‘viridis_r’, (default is ‘hot_r’)

transparent_modebool, optional

Background color in the figures. (default is False)

showitbool, optional

If True, the figures are shown interactively. (default is True)

figsizetuple, optional

Dimension of the figure size. (default figure size is (4, 6)).

top_termint, optional

The number of terms in the barplot. (default is 10)

dpiint, optional

Resolution in dots per inch for saving the figure. Default is 300.

object_for_colorstr, optional

The dataFrame column for plotting the color (default is ‘Adjusted P-value’)

object_for_xaxisstr, optional

The dataFrame column for plotting the xaxis (default is ‘Odds Ratio’)

object_for_yaxisstr, optional

The dataFrame column for plotting the yaxis (default is ‘Term’)

object_for_sortingstr, optional

The dataFrame sorted as -log10 and top terms are plotted as barplot (default is ‘Adjusted P-value’)

barplot_edgecolorstr, optional

The color of barplot edge (default is ‘black’)

barplot_linewidthfloat, optional

The linewidth of barplot edge (default is 0.5)

barplot_ascending_orderbool, optional

Order the y-axis in barplot (default is True).

barplot_colorbar_length_shrinkfloat, optional

Length of colorbar in barplot (default is 0.5).

barplot_log10_pvalue_roundoffint, optional

Roundoff the pvalue (default is 2)

dotplot_x_order, dotplot_y_order, dotplot_xticklabels_rot, dotplot_yticklabels_rot, dotplot_marker, dotplot_show_ring

Used in gseapy.dotplot For details please check this website https://gseapy.readthedocs.io/en/latest/run.html (The default values are False, False, None, None, ‘o’, False)

Outputs

The pathway figures are saved in “./nico_out/covariations_R*_F*/Pathway_figures/”.

Notes General

• In the sheet names, ‘i’ corresponds to the factor ID.

• Columns include factors representing all cell types.

• For each factor, genes are sorted based on their association with the factor ID corresponding to the respective sheet.

• A color-coding scheme is used to distinguish genes:

  • Ligands are depicted in blue.

  • Receptors are depicted in red.

  • Genes with both ligand and receptor functions are depicted in magenta.

Notes Enrichr

• For original reference of below information please follow this url https://maayanlab.cloud/Enrichr/help#background&q=4

• Enrichr implements four scores to report enrichment results:

  • p-value

  • q-value

  • rank (Z-score) also called Odds Ratio

  • combined score

• Columns contain: Term Overlap P-value Odds Ratio Combinde Score Adjusted_P-value Genes

• The p-value is computed using a standard statistical method used by most enrichment analysis tools: Fisher’s exact test or the hypergeometric test.

• This is a binomial proportion test that assumes a binomial distribution and independence for probability of any gene belonging to any set.

• The q-value is an adjusted p-value using the Benjamini-Hochberg method for correction for multiple hypotheses testing. You can read more about this method,

• and why it is needed here [https://www.jstor.org/stable/2346101].

• The odds ratio is computed using this formula:

  • In Query | Not in Query | Row Total

  • In Gene Set | a (or x) | b | a + b (or m)

  • Not in Gene Set| c | d | c + d (or n)

  • Column Total | a + c (or k) | b + d | a + b + c + d (bg or Annotation Database Total)

  • oddsRatio = (1.0 * a * d) / Math.max(1.0 * b * c, 1)

  • where:

    • a (x) are the overlapping genes,

    • b (m-x) are the genes in the annotated set - overlapping genes

    • c (k-x) are the genes in the input set - overlapping genes

    • d (bg-m-k+x) are the 20,000 genes (or total genes in the background) - genes in the annotated set - genes in the input set + overlapping genes

• The combined score is a combination of the p-value and odds ratio calculated by multiplying the two scores as follows:

  • c = -log(p) * oddsRatio

  • Where c is the combined score, p is the p-value computed using Fisher’s exact test, and oddsRatio is the odds ratio.

  • The combined score provides a compromise between both methods and in several benchmarks show that it reports the best rankings when compared with the other scoring schemes.

• Enrichr provides all four options for sorting enriched terms.

• Python vs R differences (Please read GSEApy Documentation page 68 for more detail description https://readthedocs.org/projects/gseapy/downloads/pdf/latest/)

  • scipy.hypergeom.sf(k, M, n, N, loc=0):

    • M: the total number of objects,

    • n: the total number of Type I objects.

    • k: the random variate represents the number of Type I objects in N drawn without replacement from the total population.

  • R: > phyper(x-1, m, n, k, lower.tail=FALSE)

  • Python: > hypergeom.sf(x-1, m+n, m, k)

Example

For other available databases, check for species ‘Human,’ ‘Mouse,’ ‘Yeast,’ ‘Fly,’ ‘Fish,’ and ‘Worm’ in the following way:

>>> import gseapy as gp
>>> mouse = gp.get_library_name(organism='Mouse')
>>> human = gp.get_library_name(organism='Human')

nico_covariations.Covariations.plot_all_ct(CTname, PP, cellsinCT, ax, mycelltype, Fa, cmap, ms, msna)

Visualize factor values in UMAP for all cell types.

This helper function is used for visualizing factor values in UMAP, showing the distribution of cells across different cell types and highlighting specific cell types of interest.

Parameters:

CTnamelist of str

List of cell type names.

PPnp.ndarray

UMAP embedding coordinates for all cells.

cellsinCTdict

Dictionary where keys are cell type names and values are lists of cell indices corresponding to each cell type.

axmatplotlib.axes.Axes

Matplotlib Axes object where the UMAP plot will be drawn.

mycelltypelist of str

List of cell types to highlight.

Fanp.ndarray

Array of factor values corresponding to each cell.

cmapstr or matplotlib.colors.Colormap

Colormap used for plotting the factor values.

msint

Marker size for the highlighted cell types.

msnaint

Marker size for the non-highlighted (NA) cell types.

nico_covariations.Covariations.plot_cosine_and_spearman_correlation_to_factors(input, choose_celltypes=[], NOG_Fa=30, saveas='pdf', transparent_mode=False, showit=True, dpi=300, figsize=(15, 10))

Plots cosine and Spearman correlation to factors for given cell types.

Parameters:

inputobject

The main input object containing the output from gene_covariation_analysis.

choose_celltypeslist, optional

The cell types for which you want to inspect the covariation pattern. If the list is empty, the output will be generated for all cell types. Default is [].

NOG_Faint, optional

Number of genes to visualize for each factor. Default is 30.

saveasstr, optional

Format to save the figures. Options are ‘pdf’ or ‘png’. If ‘png’ is chosen, dpi is set to 300. Default is ‘pdf’.

transparent_modebool, optional

Whether to save the figure with a transparent background. Default is False.

showitbool, optional

Whether to display the plot interactively. Default is True.

figsizetuple, optional

Dimensions of the figure size. Default is (15, 10).

Outputs:

The output NMF plots are saved in ./<output_nico_dir>/covariations_R*_F*/NMF_output.

nico_covariations.Covariations.plot_feature_matrices(input, showit=True, saveas='pdf', transparent_mode=False, dpi=300, figsize=(10, 10))

Plots feature vectors of the spatial factors from the regression step.

nico_covariations.Covariations.plot_ligand_receptor_in_interacting_celltypes(CC_celltype_name, NC_celltype_name, logRegScore, pc1, pc2, ridgeRegScore, pvalue, Found1, Found2, saveLRplots, LR_plot_Exp_thres, saveas, transparent_mode, showit, figsize, flag, dpi)

Plot ligand-receptor interactions for interacting cell types.

This helper function is used in find_LR_interactions_in_interacting_cell_types to plot rectangle p-value figures representing ligand-receptor interactions between two cell types.

The Y-axis shows the central cell type factors, and the X-axis shows the colocalized neighborhood cell type factors. The circle size denotes the p-values, and the circle size scales with significance.

Parameters:

CC_celltype_namestr

Name of the central cell type.

NC_celltype_namestr

Name of the neighborhood cell type.

logRegScorefloat

Logistic regression score.

pc1int

Principal component for the central cell type.

pc2int

Principal component for the neighborhood cell type.

ridgeRegScorefloat

Ridge regression score.

pvaluefloat

P-value for the interaction.

Found1list

List of found ligand-receptor interactions where the ligand is in the central cell type.

Found2list

List of found ligand-receptor interactions where the ligand is in the neighborhood cell type.

saveLRplotsstr

Directory to save the ligand-receptor plots.

LR_plot_Exp_thresfloat

Expression threshold for plotting.

saveasstr

File format to save the plots (e.g., ‘png’, ‘pdf’).

transparent_modebool

Whether to save the plots with a transparent background.

showitbool

Whether to display the plots.

figsizetuple

Size of the figure.

flagstr

Flag indicating which interactions to plot (‘First’, ‘Second’, ‘Both’).

nico_covariations.Covariations.plot_significant_regression_covariations_as_circleplot(input, choose_celltypes=[], saveas='pdf', pvalue_cutoff=0.05, mention_pvalue=True, transparent_mode=False, showit=True, dpi=300, figsize=(6, 1.25))

Plot significant regression covariations as a circle plot.

This function visualizes the significant regression covariations identified in the gene covariation analysis.

Parameters

inputobject

The main input is the output from gene_covariation_analysis.

choose_celltypeslist, optional

The cell type(s) for which you want to inspect the covariation pattern. If the list is empty, the output will be generated for all cell types. Default is [].

saveasstr, optional

Format to save the figures in, either ‘pdf’ or ‘png’ (dpi for PNG format is 300). Default is ‘pdf’.

pvalue_cutofffloat, optional

The p-value cutoff used to print the -log10(pvalue) on top of the circle. Default is 0.05.

mention_pvaluebool, optional

Whether to highlight the p-value on the circle plot. If False, it will not be shown. Default is True.

transparent_modebool, optional

Background color in the figures. If True, the background will be transparent. Default is False.

showitbool, optional

Whether to display the plot. If False, the plot will be saved but not shown. Default is True.

figsizetuple, optional

Dimension of the figure size. Default is (6, 1.25).

Outputs

The regression figures are saved in ‘./nico_out/covariations_R*_F*/Regression_outputs/’.

Notes

• The main input is the output from gene_covariation_analysis.

• The output directory for saving the figures should exist prior to running this function.

nico_covariations.Covariations.plot_significant_regression_covariations_as_heatmap(input, choose_celltypes=[], saveas='pdf', transparent_mode=False, showit=True, dpi=300, figsize=(6, 10))

Plot significant regression covariations as a heatmap.

This function visualizes the significant regression covariations from the gene covariation analysis as a heatmap.

Parameters

inputobject

The main input is the output from the gene_covariation_analysis.

choose_celltypeslist, optional

The cell types for which you want to inspect the covariation regression pattern. If the list is empty, the output will be generated for all cell types. Default is an empty list [].

saveasstr, optional

Format to save the figures in, either ‘pdf’ or ‘png’ (dpi for PNG format is 300). Default is ‘pdf’.

transparent_modebool, optional

Background color in the figures. If True, the background will be transparent. Default is False.

showitbool, optional

Whether to display the plot. If False, the plot will be saved but not shown. Default is True.

figsizetuple, optional

Dimension of the figure size. Default is (6, 10).

Outputs

The regression heatmap figures are saved in the specified format and location as defined in the function implementation. Default save location is ./nico_out/covariations_R*_F*/Regression_outputs/

Notes

• Ensure the input contains the necessary data from the gene covariation analysis.

• Ensure the output directory exists and is writable before running this function.

nico_covariations.Covariations.plot_top_genes_for_a_given_celltype_from_all_factors(input, choose_celltypes=[], top_NOG=20, rps_rpl_mt_genes_included=True, correlation_with_spearman=True, saveas='pdf', transparent_mode=False, showit=True, dpi=300, figsize=(12, 10))

Visualize top genes associated with given cell types across all three factors.

This function generates plots of the top N genes associated with specified cell types from the input data. The associations can be visualized using either Spearman correlation coefficient or cosine similarity. Optionally, the visualization can include rps, rpl, and mt genes.

Parameters:

inputdict

The main input is the output from gene_covariation_analysis.

choose_celltypeslist, optional

The cell type for which the gene-factor associations should be displayed. If the list is empty, the output will be generated for all the cell types. (default is [])

top_NOGint, optional

Number of genes to visualize. (default is 20)

rps_rpl_mt_genes_includedbool, optional

For pathway analysis, decide whether to include rps, rpl, and mt genes. If True, they are included. (default is True)

correlation_with_spearmanbool, optional

If True, visualize gene-factor association obtained as Spearman correlation coefficient; otherwise, cosine similarity is displayed. (default is True)

saveasstr, optional

Save the figures in PDF or PNG format (dpi for PNG format is 300). (default is ‘pdf’)

transparent_modebool, optional

Background color of the figures. (default is False)

showitbool, optional

Whether to display the plot or not. (default is True)

figsizetuple, optional

Dimension of the figure size. (default is (12, 10))

Outputs:

The gene visualization figures are saved in ./nico_out/covariations_R*_F*/dotplots/*

Example:

>>> input_data = load_data_from_analysis()  # hypothetical function to load data
>>> plot_top_genes_for_a_given_celltype_from_all_factors(input_data, choose_celltypes=['CellType1'], top_NOG=10)

nico_covariations.Covariations.plot_top_genes_for_pair_of_celltypes_from_two_chosen_factors(input, choose_interacting_celltype_pair, visualize_factors_id, top_NOG=20, dpi=300, rps_rpl_mt_genes_included=True, correlation_with_spearman=True, saveas='pdf', transparent_mode=False, showit=True, figsize=(5, 8))

Visualize top genes associated with a pair of cell types from chosen factors.

This function generates plots of the top 20 genes in the factors associated with specified cell types from the input data, using either Spearman correlation coefficient or cosine similarity. The visualizations include comparisons between the chosen factors for each cell type.

Parameters:

inputobject

The main input is the output from gene_covariation_analysis, which includes factor and expression data.

choose_interacting_celltype_pairlist

Define the cell type pairs for visualization. The first entry is the central cell type, and the second is the niche cell type.

visualize_factors_idlist

Define the factor IDs for visualization. The first entry is the factor ID of the central cell type, and the second is the factor ID of the niche cell type.

top_NOGint, optional

Number of genes to visualize. (default is 20)

rps_rpl_mt_genes_includedbool, optional

For pathway analysis, decide whether to include rps, rpl, and mt genes. If True, they are included. (default is True)

correlation_with_spearmanbool, optional

If True, visualize gene-factor association obtained as Spearman correlation coefficient; otherwise, cosine similarity is displayed. (default is True)

saveasstr, optional

Save the figures in PDF or PNG format (dpi for PNG format is 300). (default is ‘pdf’)

transparent_modebool, optional

Background color of the figures. (default is False)

showitbool, optional

Whether to display the plot or not. (default is True)

figsizetuple, optional

Dimension of the figure size. (default is (5, 8))

Outputs:

The gene visualization figures are saved in ./nico_out/covariations_R*_F*/dotplots/*

Example:

>>> scov.plot_top_genes_for_pair_of_celltypes_from_two_chosen_factors(cov_out,
choose_interacting_celltype_pair=['Stem/TA','Paneth'],
visualize_factors_id=[1,1],
top_NOG=20,saveas=saveas,transparent_mode=transparent_mode)

nico_covariations.Covariations.read_LigRecDb(contdb)

Reads the ligand-receptor database file.

This function processes a database of ligand-receptor pairs, identifying unique ligands, receptors, and elements that act as both. The input should be a list of strings, where each string represents a line from the database file.

Parameters:

contdblist of str

A list of strings, where each string is a line from the ligand-receptor database file. Each line contains a ligand and a receptor separated by whitespace.

Example:

>>> contdb = [
        "LIG1 REC1",
        "LIG2 REC2",
        "REC1 LIG1",  # REC1 is both a receptor and a ligand
        "LIG3 REC3"
    ]
>>> totalLRpairs, ligand, receptor, either = read_LigRecDb(contdb)
>>> print(totalLRpairs)
[['LIG1', 'REC1'], ['LIG2', 'REC2'], ['REC1', 'LIG1'], ['LIG3', 'REC3']]
>>> print(ligand)
{'LIG2': 1, 'LIG3': 1}
>>> print(receptor)
{'REC2': 1, 'REC3': 1}
>>> print(either)
{'LIG1': 1, 'REC1': 1}

nico_covariations.Covariations.read_spatial_data(clusterFilename, celltypeFilename)

Read the cluster information for spatial data.

This helper function is used within the gene_covariation_analysis function to read the cluster and cell type information from the specified files.

Parameters

clusterFilenamestr

The file path of the cluster information file.

celltypeFilenamestr

The file path of the cell type information file.

nico_covariations.Covariations.remove_extra_character_from_name(name)

Remove special characters from cell type names to avoid errors while saving figures.

This function replaces certain special characters in the input name with underscores or other appropriate characters to ensure the name is safe for use as a filename.

Parameters

namestr

The original cell type name that may contain special characters.

Returns

str

The modified cell type name with special characters removed or replaced.

Example

>>> name = 'T-cell (CD4+)/CD8+'
>>> clean_name = remove_extra_character_from_name(name)
>>> print(clean_name)
'T-cell_CD4p_CD8p'

Notes

The following replacements are made:

• ‘/’ is replaced with ‘_’

• ‘ ‘ (space) is replaced with ‘_’

• ‘”’ (double quote) is removed

• “’” (single quote) is removed

• ‘)’ is removed

• ‘(’ is removed

• ‘+’ is replaced with ‘p’

• ‘-’ is replaced with ‘n’

• ‘.’ (dot) is removed

These substitutions help in creating filenames that do not contain characters that might be problematic for file systems or software.

nico_covariations.Covariations.run_ridge_regression(input, saveoutname, ylabelname, target, neighborhoodClass, shap_cluster_cutoff)

Helper function for model_linear_regression to perform ridge regression per cell type.

This function performs ridge regression for each target variable (central cell factors) using the neighborhood average spatial cell factors as predictors. It normalizes the data, fits the regression model, and computes various statistics including p-values and explained variance.

Parameters

inputobject

An object containing the following attributes: - shap_analysis : bool, whether to perform SHAP analysis. - regression_outdir : str, directory to save regression outputs. - lambda_c : list, list of regularization parameters for RidgeCV. - no_of_pc : int, number of principal components.

saveoutnamestr

The name to save the output of the regression results.

ylabelnamelist

List of feature names for the predictors.

targetarray

The target values (central cell factors).

neighborhoodClassarray

The neighborhood average spatial cell factors.

shap_cluster_cutofffloat

The cutoff value for clustering in SHAP analysis.

Returns

coefarray

Coefficients of the ridge regression model.

interceptarray

Intercepts of the ridge regression model.

lambda_clist

List of regularization parameters used in the ridge regression model.

percent_variance_explainedlist

Percentage of variance explained by the model.

residual_variance_explainedfloat

Residual variance explained by the model (currently set to 0).

pvarray

P-values of the regression coefficients.

Notes

• The function normalizes the predictors and target variables.

• It fits a ridge regression model for each target variable and computes various statistics.

• If SHAP analysis is enabled, it performs SHAP analysis and saves the plots.

nico_covariations.Covariations.save_LR_interactions_in_excelsheet_and_regression_summary_in_textfile_for_interacting_cell_types(input, pvalueCutoff=0.05, correlation_with_spearman=True, LR_plot_NMF_Fa_thres=0.2, LR_plot_Exp_thres=0.2, number_of_top_genes_to_print=20)

Save ligand-receptor (LR) interactions in an Excel sheet and regression summary in a text file for interacting cell types.

This function processes the output from gene_covariation_analysis to identify significant LR interactions and saves the results in an Excel sheet and a text file.

Parameters:

inputobject

The main input is the output from gene_covariation_analysis.

pvalueCutofffloat, optional

The cutoff used to select the significant central cell type factor and niche cell type factor covariations. Default is 0.05.

correlation_with_spearmanbool, optional

If True, genes factor correlations are computed as Spearman correlation coefficient; otherwise, cosine similarities are computed. Default is True.

LR_plot_NMF_Fa_thresfloat, optional

Only ligands or receptors are retained that exhibit a correlation to the respective factors higher than this cutoff. Default is 0.2.

LR_plot_Exp_thresfloat, optional

Only ligands or receptors are retained that are expressed in a fraction of cells of the respective cell types exceeding this cutoff. Default is 0.2.

number_of_top_genes_to_printint, optional

The number of top correlating genes to print in the regression summary text file. Default is 20.

Outputs:

• An Excel sheet with ligand-receptor interaction information for easy access. The columns are structured as follows in the sheets:

  • 1. ID of the cell type-cell type interaction

  • BC. Interacting cell types A and B

  • 4. Normalized interaction scores from the logistic regression classifier

  • EF. NMF factor IDs (metagenes) in cell types A and B

  • 7. Ridge regression coefficient indicating the factors’ covariation

  • 8. Ligand in cell type A

  • 1. Receptor in cell type B

  • JK. Pearson correlation of ligand and receptor genes in cell types A and B with the corresponding factors

  • LM. Average expression of ligands and receptors in cell types A and B

  • NO. Fraction of cells expressing these genes with counts greater than zero in cell types A and B

• A regression summary text file with the following structure:

• First row: CC-Fa(i), CC (cell type), niche_score (from classifier), NC-Fa*, NC (cell type), RegCoeff (covariation score), p-value on normal scale, p-value on -log10 scale

• Second row: Top 20 (number_of_top_genes_to_print) genes correlated to Fa(i) of central cell type, with genes and their factor ID indicated in the pair

• Third row: Top 20 (number_of_top_genes_to_print) genes correlated to Fa(j) of niche cell type, with genes and their factor ID indicated in the pair

Notes

• Our analysis accounts for bidirectional cellular crosstalk interactions of ligands and receptors in cell types A and B.

• The ligand can be expressed on cell type A and signal to the receptor detected on cell type B, or vice versa.

• Both ligand-receptor plots and Excel sheets profile bidirectional cellular crosstalk of ligand and receptor in cell types A and B.

• Each central cell type is represented in a separate Excel sheet, while the LR enrichment sheet aggregates all interactions across central cell types.

nico_covariations.Covariations.sort_index_in_right_order(correct, wrong)

Sorts the ‘wrong’ array to match the order of the ‘correct’ array based on the first column values.

This function reorders the rows of the ‘wrong’ array to match the order of the ‘correct’ array based on the values in the first column. It is a helper function used in visualizing cell type annotations.

Parameters:

correctndarray

An array with the correct order of elements. The sorting is based on the values in the first column.

wrongndarray

An array that needs to be reordered to match the ‘correct’ array. The sorting is based on the values in the first column.

Returns:

rightndarray

The ‘wrong’ array reordered to match the order of the ‘correct’ array based on the first column values.

nico_covariations.Covariations.sorting_of_factors_for_showing_the_value_in_excelsheet(CC_corr, no_of_pc, gene, genenames)

Sort factor values for displaying in an Excel sheet.

This helper function is used in make_excel_sheet_for_gene_correlation to sort the factor values from correlation data. It separates the sorted values into all genes and a subset of common genes.

Parameters:

CC_corrnumpy.ndarray

Array of correlation values, where rows represent genes and columns represent principal components.

no_of_pcint

Number of principal components.

genelist of str

List of gene names corresponding to the rows in CC_corr.

genenameslist of str

List of gene names to be included in the common subset.

nico_covariations.Covariations.top_genes_in_correlation_list_without(genename, corr_NMFfactors_genes, n_top_words)

Identify top genes associated with NMF factors, excluding duplicates.

This helper function sorts the factor values and selects the top genes associated with each factor. It is used in plot_cosine_and_spearman_correlation_to_factors.

Parameters

genenamenumpy.ndarray or pandas.Series

Array or Series containing gene names.

corr_NMFfactors_genesnumpy.ndarray or pandas.DataFrame

The matrix representing the correlation values between genes and NMF factors. Each row corresponds to a gene, and each column corresponds to an NMF factor.

n_top_wordsint

The number of top genes to retrieve for each NMF factor.

Returns

gnamenumpy.ndarray

Array containing the names of the top genes associated with the NMF factors.

matnumpy.ndarray

Matrix containing the correlation values of the top genes associated with the NMF factors. Each row corresponds to a selected top gene, and each column corresponds to an NMF factor.

nico_covariations.Covariations.triangulation_for_triheatmap(M, N)

Create triangulation for plotting a ligand-receptor map.

This helper function generates the triangulation needed for plotting a rectangle four faces in the plot_ligand_receptor_in_interacting_celltypes function. It constructs the vertices and triangles required for visualizing the ligand-receptor interactions on a heatmap.

Parameters:

Mint

Number of columns in the heatmap.

Nint

Number of rows in the heatmap.

Returns:

list of matplotlib.tri.Triangulation

nico_covariations.Covariations.visualize_factors_in_scRNAseq_umap(input, choose_interacting_celltype_pair, visualize_factors_id, umap_tag='X_umap', msna=0.1, ms=5, cmap='viridis', dpi=300, saveas='pdf', transparent_mode=False, showit=True, figsize=(8, 3.5))

Visualize factors in scRNAseq UMAP embedding.

This function visualizes the factors in single-cell RNA sequencing (scRNAseq) UMAP embeddings. It highlights the interactions between specified cell type pairs and their corresponding factor IDs.

Parameters:

inputstr

The primary input is the output from gene_covariation_analysis.

choose_interacting_celltype_pairlist

List defining the cell type single or in pairs to visualize. At least one cell type need to put by the user.

visualize_factors_idlist

List defining the factor IDs single or in pairs to visualize in the UMAP. The chosen factors analogous to defined cell types.

umap_tagstr, optional

The UMAP embedding tag in the .obsm field of the AnnData object (default is ‘X_umap’).

msnafloat, optional

The marker size for non selected (NA) cell types (default is 0.1).

msint, optional

The marker size for selected cell types (default is 5).

cmapstr, optional

Colormap for visualizing factors (default is plt.rcParams[“image.cmap”]).

saveasstr, optional

Format to save the figures (‘pdf’ or ‘png’) (default is ‘pdf’).

transparent_modebool, optional

Whether to save the figures with a transparent background (default is False).

showitbool, optional

Whether to display the figures (default is True).

figsizetuple, optional

Size of the figure (default is (8, 3.5)).

Outputs:

The factor visualization in scRNAseq embedding is saved in “./nico_out/covariations_R*_F*/scRNAseq_factors_in_umap”.

nico_covariations.Covariations.visualize_factors_in_spatial_umap(input, choose_interacting_celltype_pair, visualize_factors_id, umap_tag='X_umap', quepath='./inputQuery/', msna=0.1, ms=5, cmap='viridis', dpi=300, saveas='pdf', transparent_mode=False, showit=True, figsize=(8, 3.5))

Visualize factors in spatial UMAP for cell type interactions.

This function is used to visualize the factors of interacting cell types in a spatial UMAP embedding. It generates and saves plots showing the distribution and factor values of cells.

Parameters:

inputstr

The primary input is the output from gene_covariation_analysis.

choose_interacting_celltype_pairlist of str

Define the cell type single or in pairs for visualization in the spatial UMAP. Example: choose_interacting_celltype_pair=[‘CentralCellType’, ‘NicheCellType’]

visualize_factors_idlist of str

Define the factor IDs single or in pairs for visualization in the spatial UMAP. Example: visualize_factors_id=[1, 3]

umap_tagstr, optional

Slot for UMAP embedding in the AnnData object. Default is ‘X_umap’.

quepathstr, optional

Path to the query spatial count matrix in scTransform-like normalization in the common gene space. The filename should be sct_spatial.h5ad. Default is ‘./inputQuery/’.

msnafloat, optional

Marker size for not selected (NA) cell types. Default is 0.1.

msfloat, optional

Marker size for selected cell types. Default is 5.

cmapstr or matplotlib.colors.Colormap, optional

Colormap used for visualizing the factor values. Default is plt.rcParams[“image.cmap”].

saveasstr, optional

Format to save the figures, either ‘pdf’ or ‘png’. Default is ‘pdf’.

transparent_modebool, optional

Background color of the figures. If True, the figures have a transparent background. Default is False.

showitbool, optional

If True, the figures will be displayed. Default is True.

figsizetuple of float, optional

Dimension of the figure size. Default is (8, 3.5).

Output:

The output figure will be saved in nico_out/covariations_R*_F*/spatial_factors_in_umap*.

Module contents