NiCo: Niche covariation analysis of spatial transcriptomics data

Important

🚀 NEW USERS — START HERE!

For new NiCo analyses, please use nico-wrapper as the preferred way to apply NiCo.

Since August 1, 2026, nico-wrapper provides streamlined command-line and Python interfaces for the main NiCo workflow while continuing to use NiCo for the underlying scientific computations.

👉 Start with nico-wrapper on Gruenlab GitHub

The direct NiCo installation and tutorials on this website are primarily retained for existing users, legacy analyses, and reproducibility.

Infer cellular crosstalk from spatial transcriptomics and scRNA-seq data

Important

🆕 Recommended workflow for new analyses

If you are starting a new project with NiCo, please start with nico-wrapper rather than the legacy direct NiCo installation.

nico-wrapper provides a streamlined interface to the main NiCo workflow through both CLI and Python interfaces, while NiCo remains the underlying scientific computation framework.

👉 Start with nico-wrapper

Existing users who need to reproduce previous analyses can continue using the direct NiCo package and the tutorials provided in this documentation.

The Niche Covariation (NiCo) package is developed for the integration of single-cell resolution spatial transcriptomics and scRNA-seq data (or from sequencing-based spatial transcriptomics data alone) to (1) perform cell type annotations in the spatial modality by label transfer, (2) predict niche cell type interactions within local neighborhoods, and (3) infer cell state covariation and the underlying molecular crosstalk in the niche. NiCo infers factors capturing cell state variability in both modalities and identifies genes correlated to these latent factors for the prediction of ligand-receptor interactions and factor-associated pathways.

For new analyses, we recommend using nico-wrapper as the preferred interface to the NiCo workflow.

Highlights of NiCo

1. Annotations of cell types in spatial data by label transfer

2. Prediction of niche interactions using neighborhood analysis

3. Covariation analysis of latent factors across niche cell types

4. Prediction of ligand-receptor interactions mediating niche crosstalk

5. Inference of pathways aassociated with covarying cell states

Installation

Warning

For new analyses, please use nico-wrapper instead of the direct NiCo installation below.

Since August 1, 2026, nico-wrapper provides a streamlined command-line and Python interface for the main NiCo workflow while continuing to use NiCo as the underlying scientific computation framework.

Note

Please install using following commands:

conda create -n nicoUser python=3.11

conda activate nicoUser

pip install nico-sc-sp

pip install jupyterlab

For more details, follow the python package index guidelines from nico-sc-sp pypi

Tutorials

Note

New users: For new analyses, please start with nico-wrapper.

The tutorials below describe the direct NiCo workflow and are retained for existing users, previous analyses, and reproducibility.

Please prepare the input files with scRNA-seq count data and cell type annotation (cluster partition), spatial count data, and spatial cell coordinates to run the complete NiCo tutorials.

NiCo tutorials for imaging-based spatial transcriptomics (Xenium, MERSCOPE, seqFISH) or sequencing-based methods, e.g., Slide-seqV2, are available here

Contents:

• Introduction
  • Key Features:
  • Getting Started:
  • Github Tutorials:
  • Contributing:
  • Support:
• Installation
  • Prerequisites
  • Installing via Pip
  • Verifying the Installation
  • Updating NiCo
  • Troubleshooting
• Examples
  • Tutorials with visualization
  • Basic Usage
• Tutorial 0: Data Preparation
  • Usage introduction
  • If a spatial h5ad object is already available:
  • Reference scRNA-seq data
  • Find shared genes between scRNA-seq and spatial data
  • Perform scTransform-normalization (Pearson residuals) with two different alternative stratgies
    • Perform Leiden clustering on spatial transcriptomics data to guide cell type annotation
  • Guiding Leiden cluster resolutions
• Tutorial 1: Single-Cell Resolution Spatial Transcriptomics (seqFISH, Xenium, or MERSCOPE etc.)
  • A: Perform cell type annotation of the spatial data
    • Selection of parameters
    • The annotation slot in the scRNA-seq data and initial cluster slot in the spatial data
    • Save the annotation file to an AnnData object
  • Note: Annotations from different computational methods such cell2location or TACCO
    • Visualize the spatial annotations of all cell types
    • Visualize spatial annotations of selected pairs (or larger sets) of cell types
  • B: Infer significant niche cell type interactions
    • Example A: Plot the niche interaction network without any edge weight details for cutoff 0.1
    • Example B: Using edge weights included in the niche interaction plot can be done as shown below
    • Individual cell type niche plot
  • C: Perform niche cell state covariation analysis using latent factors
    • Covariation parameter settings
    • Ligand-Receptor database file
    • Visualize the cosine similarity and Spearman correlation between genes and latent factors
    • Visualizes genes associated with the latent factors along with average expression
    • Inspect genes associated with a latent factor
    • Save the latent factors into an excel sheet
  • D: Cell type covariation visualization
    • Visualize as heatmap instead of circle plot
  • E: Analysis of ligand-receptor interactions between covarying niche cell types
    • Save excel sheets and summary in text file
    • Usage for ligand receptor visualizations
  • F: Perform functional enrichment analysis for genes associated with latent factors
    • Example 1: Perform pathway enrichment analysis for factor-associated genes
    • Example 2: increase the size of dot
    • Example 3: instead of dotplot show as a barplot
  • Example 4 (Recommended version): We recommend using the following version of the plot
    • Example 5
    • Example 6
    • Example 7
    • Example 8
  • G: Visualization of top genes across cell types and factors as dotplot
  • H: Visualize factor values in the UMAP
• Tutorial 2: Slide-seqV2, Slide-tags, or Stereo-seq
  • Usage introduction
    • A: Visualize cell type annotation of spatial data
  • Visualize spatial annotations of selected pairs (or larger sets) of cell types
    • B: Infer significant niche cell type interactions
    • Individual cell type niche plot
    • C: Perform niche cell state covariation analysis using latent factors
  • Covariation parameter settings
  • Ligand-Receptor database file
  • Visualize the cosine similarity and Spearman correlation between genes and latent factors
  • Visualizes genes associated with the latent factors along with average expression
  • Inspect genes associated with a latent factor
  • Save the latent factors into an excel sheet
    • D: Cell type covariation visualization
  • Visualize as heatmap instead of circle plot
    • E: Analysis of ligand-receptor interactions between covarying niche cell types
  • Save excel sheets and summary in text file
  • Usage for ligand-receptor visualizations
    • F: Perform functional enrichment analysis for genes associated with latent factors
  • Perform pathway enrichment analysis for factor-associated genes
    • G: Visualization of top genes across cell types and factors as dotplot
    • H: Visualize factor values in the UMAP
• API Reference
  • Module 1: nico_annotations
    • create_directory()
    • delete_files()
    • findSpatialCells()
    • find_all_the_spatial_cells_mapped_to_single_cells()
    • find_anchor_cells_between_ref_and_query()
    • find_annotation_index()
    • find_commnon_MNN()
    • find_index()
    • find_match_index_in_dist()
    • find_mutual_nn()
    • find_unmapped_cells_and_deg()
    • nico_based_annotation()
    • plot_all_ct()
    • plot_specific_ct()
    • read_dist_and_nodes_as_graph()
    • remove_extra_character_from_name()
    • resolved_confused_and_unmapped_mapping_of_cells_with_majority_vote()
    • resolved_confused_and_unmapped_mapping_of_cells_with_weighted_average_of_inverse_distance_in_neighbors()
    • return_singlecells()
    • save_annotations_in_spatial_object()
    • sct_return_sc_sp_in_shared_common_PC_space()
    • visualize_spatial_anchored_cell_mapped_to_scRNAseq()
    • visualize_umap_and_cell_coordinates_with_all_celltypes()
    • visualize_umap_and_cell_coordinates_with_selected_celltypes()
    • write_annotation()
  • Module 2: nico_interactions
    • create_directory()
    • create_spatial_CT_feature_matrix()
    • euclidean_dist()
    • findNeighbors_in_given_radius()
    • find_interacting_cell_types()
    • find_neighbors()
    • model_log_regression()
    • plot_coefficient_matrix()
    • plot_confusion_matrix()
    • plot_evaluation_scores()
    • plot_multiclass_roc()
    • plot_niche_interactions_with_edge_weight()
    • plot_niche_interactions_without_edge_weight()
    • plot_predicted_probabilities()
    • plot_roc_results()
    • read_processed_data()
    • reading_data()
    • remove_extra_character_from_name()
    • spatial_neighborhood_analysis()
  • Module 3: nico_covariations
    • alignment_score()
    • compute_PC_space()
    • create_directory()
    • create_subtitle()
    • extract_and_plot_top_genes_from_chosen_factor_in_celltype()
    • findXYZC()
    • find_LR_interactions_in_interacting_cell_types()
    • find_PC_of_invidualCluster_in_SC()
    • find_correlation_bw_genes_and_PC_component_in_singlecell()
    • find_correlation_bw_genes_and_PC_component_in_singlecell_cosine()
    • find_fold_change()
    • find_index()
    • find_interest_of_genes()
    • find_logistic_regression_interacting_score()
    • gene_covariation_analysis()
    • makePCneighboorhoodFeatureMatrix()
    • make_excel_sheet_for_gene_correlation()
    • model_linear_regression()
    • multiplicative_method()
    • pathway_analysis()
    • plot_all_ct()
    • plot_cosine_and_spearman_correlation_to_factors()
    • plot_feature_matrices()
    • plot_ligand_receptor_in_interacting_celltypes()
    • plot_significant_regression_covariations_as_circleplot()
    • plot_significant_regression_covariations_as_heatmap()
    • plot_top_genes_for_a_given_celltype_from_all_factors()
    • plot_top_genes_for_pair_of_celltypes_from_two_chosen_factors()
    • read_LigRecDb()
    • read_spatial_data()
    • remove_extra_character_from_name()
    • run_ridge_regression()
    • save_LR_interactions_in_excelsheet_and_regression_summary_in_textfile_for_interacting_cell_types()
    • sort_index_in_right_order()
    • sorting_of_factors_for_showing_the_value_in_excelsheet()
    • top_genes_in_correlation_list_without()
    • triangulation_for_triheatmap()
    • visualize_factors_in_scRNAseq_umap()
    • visualize_factors_in_spatial_umap()
• Frequently Asked Questions (FAQ)

Indices and tables

• Index

• Module Index

• Search Page