Examples
========

This section provides examples of how to use the NiCo tool for spatial cell type annotation, niche interaction inference, and covariation analysis.


Tutorials with visualization
----------------------------
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 Xenium, MERSCOPE, SEQFISH and Slide-seqV2 spatial technologies via Jupyter lab are `available here
<https://github.com/ankitbioinfo/nico_tutorial>`_


Basic Usage
-----------

Below is a complete example demonstrating the usage of the main steps (modules) in NiCo.

### Importing Modules and Setting Up

.. code-block:: python

   # if you installed the nico package
   from nico import NicoAnalysis
   from nico import Annotations as sann
   from nico import Interactions as sint
   from nico import Covariations as scov

   # if you did not install the nico package and downloaded the nico files into the current directory
   #import Annotations as sann
   #import Interactions as sint
   #import Covariations as scov


   import scanpy as sc
   import numpy as np
   import matplotlib.pyplot as plt

   # Configure matplotlib for publication-quality plots
   plt.rcParams['font.family'] = 'sans-serif'
   plt.rcParams['font.sans-serif'] = ['Helvetica', 'Tahoma', 'DejaVu Sans', 'Lucida Grande', 'Verdana']
   plt.rcParams['pdf.fonttype'] = 42  # Embed fonts in PDF files

   import warnings
   warnings.filterwarnings("ignore")

   # Parameters for saving plots
   saveas = 'png'
   transparent_mode = False

   ref_datapath = './inputRef/'
   query_datapath = './inputQuery/'
   output_nico_dir = './nico_analysis/'
   output_annotation_dir = None
   annotation_save_fname = 'nico_celltype_annotation.h5ad'
   inputRadius = 0
   ref_cluster_tag = 'cluster'  # scRNAseq cell type slot
   annotation_slot = 'nico_ct'  # spatial cell type slot



**A: Perform Cell Type Annotation of Spatial Data**


# Find anchor cells between reference and query datasets

.. code-block:: python

   anchors_and_neighbors_info = sann.find_anchor_cells_between_ref_and_query(
   refpath=ref_datapath,
   quepath=query_datapath,
   output_nico_dir=output_nico_dir,
   output_annotation_dir=output_annotation_dir
   )

   # Perform NiCo-based annotation
   output_info = sann.nico_based_annotation(
   anchors_and_neighbors_info,
   guiding_spatial_cluster_resolution_tag='leiden0.4',
   across_spatial_clusters_dispersion_cutoff=0.15,
   resolved_tie_issue_with_weighted_nearest_neighbor='No'
   )

   # Clean up temporary files
   sann.delete_files(output_info)

   # Save annotations to the spatial object
   sann.save_annotations_in_spatial_object(output_info, anndata_object_name=annotation_save_fname)




**B: Cell Type Annotation Visualization**

.. code-block:: python

   print('\n\nModule A visualization')
   # Visualize UMAP and cell coordinates with all cell types
   sann.visualize_umap_and_cell_coordinates_with_all_celltypes(
   output_nico_dir=output_nico_dir,
   output_annotation_dir=output_annotation_dir,
   anndata_object_name=annotation_save_fname,
   spatial_cluster_tag=annotation_slot,
   spatial_coordinate_tag='spatial',
   umap_tag='X_umap',
   saveas=saveas,
   transparent_mode=transparent_mode
   )

   # Visualize UMAP and cell coordinates with selected cell types
   sann.visualize_umap_and_cell_coordinates_with_selected_celltypes(
   output_nico_dir=output_nico_dir,
   output_annotation_dir=output_annotation_dir,
   anndata_object_name=annotation_save_fname,
   spatial_cluster_tag=annotation_slot,
   spatial_coordinate_tag='spatial',
   umap_tag='X_umap',
   choose_celltypes=[],
   saveas=saveas,
   transparent_mode=transparent_mode
   )



**C: Infer Significant Niche Cell Type Interactions**

.. code-block:: python

   print('\n\nModule B')
   do_not_use_following_CT_in_niche = ['Basophils', 'Cycling/GC B cell', 'pDC']

   niche_pred_output = sint.spatial_neighborhood_analysis(
   Radius=inputRadius,
   output_nico_dir=output_nico_dir,
   anndata_object_name=annotation_save_fname,
   spatial_cluster_tag=annotation_slot,
   removed_CTs_before_finding_CT_CT_interactions=do_not_use_following_CT_in_niche
   )

   celltype_niche_interaction_cutoff = 0.1

   sint.plot_niche_interactions_with_edge_weight(
   niche_pred_output,
   niche_cutoff=celltype_niche_interaction_cutoff,
   saveas=saveas,
   transparent_mode=transparent_mode
   )

   sint.plot_niche_interactions_without_edge_weight(
   niche_pred_output,
   niche_cutoff=celltype_niche_interaction_cutoff,
   saveas=saveas,
   transparent_mode=transparent_mode
   )

   sint.find_interacting_cell_types(
   niche_pred_output,
   choose_celltypes=[],
   celltype_niche_interaction_cutoff=celltype_niche_interaction_cutoff,
   coeff_cutoff=30,
   saveas=saveas,
   transparent_mode=transparent_mode,
   figsize=(4.0, 2.0)
   )

   sint.plot_confusion_matrix(
   niche_pred_output,
   saveas=saveas,
   transparent_mode=transparent_mode
   )

   sint.plot_coefficient_matrix(
   niche_pred_output,
   saveas=saveas,
   transparent_mode=transparent_mode
   )

   sint.plot_evaluation_scores(
   niche_pred_output,
   saveas=saveas,
   transparent_mode=transparent_mode,
   figsize=(4, 3)
   )



**D: Perform Niche Cell State Covariation Analysis Using Latent Factors**

.. code-block:: python

   print('\n\nModule C')
   cov_out = scov.gene_covariation_analysis(
   iNMFmode=True,
   Radius=inputRadius,
   no_of_factors=3,
   spatial_integration_modality='double',
   refpath=ref_datapath,
   quepath=query_datapath,
   output_niche_prediction_dir=output_nico_dir,
   ref_cluster_tag=ref_cluster_tag
   )

   # Visualize the correlation of genes from NMF
   scov.plot_cosine_and_spearman_correlation_to_factors(
   cov_out,
   choose_celltypes=[],
   NOG_Fa=30,
   saveas=saveas,
   transparent_mode=transparent_mode,
   figsize=(15, 10)
   )

   scov.make_excel_sheet_for_gene_correlation(cov_out)





**E: Cell Type Covariation Visualization**

.. code-block:: python

   print('\n\nModule D')
   scov.plot_significant_regression_covariations_as_circleplot(
   cov_out,
   choose_celltypes=[],
   pvalue_cutoff=0.05,
   mention_pvalue=True,
   saveas=saveas,
   transparent_mode=transparent_mode,
   figsize=(6, 1.25)
   )





**F: Analysis of Ligand-Receptor Interactions Associated with Covarying Latent Factors of Niche Cell Types**

.. code-block:: python

   print('\n\nModule E')
   scov.save_LR_interactions_in_excelsheet_and_regression_summary_in_textfile_for_interacting_cell_types(
   cov_out,
   pvalueCutoff=0.05,
   correlation_with_spearman=True,
   LR_plot_NMF_Fa_thres=0.1,
   LR_plot_Exp_thres=0.1,
   number_of_top_genes_to_print=5
   )

   scov.find_LR_interactions_in_interacting_cell_types(
   cov_out,
   choose_interacting_celltype_pair=[],
   choose_factors_id=[],
   pvalueCutoff=0.05,
   LR_plot_NMF_Fa_thres=0.2,
   LR_plot_Exp_thres=0.2,
   saveas=saveas,
   transparent_mode=transparent_mode,
   figsize=(12, 10)
   )




**G: Perform Functional Enrichment Analysis for Genes Associated with Latent Factors**

.. code-block:: python

   print('\n\nModule F')
   scov.pathway_analysis(
   cov_out,
   choose_celltypes=[],
   NOG_pathway=50,
   choose_factors_id=[],
   savefigure=True,
   positively_correlated=True,
   saveas='pdf',
   rps_rpl_mt_genes_included=False
   )





**H: Visualization of Top Genes Associated with Latent Factors Across Cell Types and Factors as Dotplot**

.. code-block:: python

   print('\n\nModule G')
   scov.plot_top_genes_for_a_given_celltype_from_all_factors(
   cov_out,
   choose_celltypes=[],
   top_NOG=20,
   saveas=saveas,
   transparent_mode=transparent_mode
   )

   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
   )




**I: Visualization of Factor Values in the UMAP**

.. code-block:: python

   print('\n\nModule H')
   scov.visualize_factors_in_spatial_umap(
   cov_out,
   visualize_factors_id=[1, 1],
   choose_interacting_celltype_pair=['Stem/TA', 'Paneth'],
   saveas=saveas,
   transparent_mode=transparent_mode,
   figsize=(8, 3.5)
   )

   scov.visualize_factors_in_scRNAseq_umap(
   cov_out,
   choose_interacting_celltype_pair=['Stem/TA', 'Paneth'],
   visualize_factors_id=[1, 1],
   saveas=saveas,
   transparent_mode=transparent_mode,
   figsize=(8, 3.5)
   )