Merge pull request #39 from CostaLab/doc

Doc

Improved network functions and coloc module completely documented

Author: MayraRuizT

README.md

@@ -1,6 +1,8 @@
-# Nichesphere
+<img align="right" src="nichesphere/nichesphere/source/_static/logo.png" alt="Nichesphere Logo" width="200">
 
-Nichesphere is an sc-verse compatible Python library which allows the user to find differential co-localization domains / niches based on cell type pair co-localization probabilities in different conditions. Cell type pair co-localization probabilities can be obtained in different ways, for example, through deconvolution of spatial transcriptomics / PIC-seq data (getting the probabilities of finding each cell type in each spot / multiplet) ; or counting cell boundaries overlaps for each cell type pair in single cell spatial data (MERFISH , CODEX …).
+# NicheSphere
+
+NicheSphere is an sc-verse compatible Python library which allows the user to find differential co-localization domains / niches based on cell type pair co-localization probabilities in different conditions. Cell type pair co-localization probabilities can be obtained in different ways, for example, through deconvolution of spatial transcriptomics / PIC-seq data (getting the probabilities of finding each cell type in each spot / multiplet) ; or counting cell boundaries overlaps for each cell type pair in single cell spatial data (MERFISH , CODEX …).
 
 It also offers the possibility to look at biological process based differential communication among differential co-localization domains based on Ligand-Receptor pairs expression data, such as results from CrossTalkeR [ref.].
 

nichesphere/nichesphere/coloc.py

@@ -3,27 +3,43 @@
 import numpy as np
 import scipy
 import seaborn as sns
-#import random
 import matplotlib.pyplot as plt
 import matplotlib.colors as mcolors
-#import ot
 import networkx as nx
-#import itertools
 import sklearn
-#import scanpy as sc
-#import sys
-#sys.path.append(".")
-#from tl import *
-#from . import tl
 from matplotlib.colors import ListedColormap
 
 def unique(array):
+    """get unique elements in array without re-sorting
+
+    Parameters
+    ----------
+    array : np.array
+
+    Returns
+    -------
+    uniq[index.argsort()] : np.array of unique elements of the original array in original order
+    """
     uniq, index = np.unique(array, return_index=True)
     return uniq[index.argsort()]
 
 #%%
 
 def cellCatContained(pair, cellCat):
+    """Check if a cell group (niche/type/category) is contained in a cell type pair
+
+    Parameters
+    ----------
+    pair : list
+        cell type list (usually cell type pairs in the form [cellTypeA,cellTypeB])
+
+    cellCat : list
+        list of cell types in a cell group (niche/type/category)
+
+    Returns
+    -------
+    True or False
+    """
 
     contained=[cellType in pair for cellType in cellCat]
     return True in contained
@@ -138,7 +154,7 @@ def getDiffComm(diffCommTbl, pairCatDF, ncells, cat):
 
 #%%
 
-def catNW(x_chem,colocNW, cell_group, group_cmap='tab20', ncols=20, color_group=None, plot_title='', 
+def catNW(x_chem,colocNW, cell_group, group=None, group_cmap='tab20', ncols=20, color_group=None, plot_title='', 
           clist=None, nodeSize=None, legend_ax=[0.7, 0.05, 0.15, 0.2], layout='neato', thr=0, fsize=(8,8), alpha=1, lab_spacing=7, edge_scale=1, pos=None):    
 
     # Choose colormap
@@ -163,7 +179,16 @@ def catNW(x_chem,colocNW, cell_group, group_cmap='tab20', ncols=20, color_group=
 
     colors = np.vstack((np.flip(c1[128:256], axis=0), c2[128:256]))
     mymap = mcolors.LinearSegmentedColormap.from_list('my_colormap', colors)
-
+    
+    cmap=mcolors.LinearSegmentedColormap.from_list("WhiteGray",['white','lightgrey'])
+    # Get the colormap colors
+    graycmp = cmap(np.arange(cmap.N))
+    # Set alpha (transparency)
+    graycmp[:,-1] = np.linspace(0, alpha-0.2, cmap.N)
+    c3=graycmp.copy()
+    # Create new colormap
+    graycmp = ListedColormap(graycmp)
+    
     #cell group cmap
     cmap = plt.cm.get_cmap(group_cmap, ncols)
     if clist == None:
@@ -249,6 +274,16 @@ def catNW(x_chem,colocNW, cell_group, group_cmap='tab20', ncols=20, color_group=
 
     inter=pd.Series(np.abs(pd.Series(list(weights))))
     inter.index=edgeCols.index
+
+    ####### NEW #######
+    if group!=None:
+        edgeCols[[cellCatContained(pair=[x.split('->')[0], x.split('->')[0]], 
+                   cellCat=group)==False for x in edgeCols.index]]='lightgray'
+        orange_edges = [(u,v) for u,v in G.edges if edgeCols[u+'->'+v] == 'orange']
+        blue_edges = [(u,v) for u,v in G.edges if edgeCols[u+'->'+v] == 'lightblue']
+        gray_edges = [(u,v) for u,v in G.edges if edgeCols[u+'->'+v] == 'lightgray']
+    ###################
+    
     ###
 
     if nodeSize == 'betweeness':
@@ -278,7 +313,13 @@ def catNW(x_chem,colocNW, cell_group, group_cmap='tab20', ncols=20, color_group=
 
 
         nx.draw_networkx_nodes(G,pos,node_color=color_group,ax=ax1)
-
+    
+    ##########################################
+    if group!=None:
+        nx.draw_networkx_edges(G,pos=pos,edge_color=inter[edgeCols=='lightgray'],
+            connectionstyle="arc3,rad=0.15", arrowstyle='<->',
+            width=inter[edgeCols=='lightgray']*edge_scale,ax=ax1, edgelist=gray_edges, edge_cmap=graycmp, edge_vmin=-1*np.max(inter), edge_vmax=np.max(inter))
+    ##########################################
     nx.draw_networkx_edges(G,pos=pos_edges,edge_color=inter[edgeCols=='lightblue'],
             connectionstyle="arc3,rad=0.15",
             width=inter[edgeCols=='lightblue']*edge_scale,ax=ax1, edgelist=blue_edges, edge_cmap=cmap3,edge_vmin=-1*np.max(inter), 
@@ -287,7 +328,6 @@ def catNW(x_chem,colocNW, cell_group, group_cmap='tab20', ncols=20, color_group=
             connectionstyle="arc3,rad=0.15",
             width=inter[edgeCols=='orange']*edge_scale,ax=ax1, edgelist=orange_edges, edge_cmap=cmap4,edge_vmin=-1*np.max(inter), 
             edge_vmax=np.max(inter), arrowsize=20)
-    
     nx.draw_networkx_labels(G,pos_attrs,verticalalignment='bottom',
         font_size=12,clip_on=False,ax=ax1, font_weight='bold')
     f.suptitle(plot_title)

nichesphere/nichesphere/comm.py

@@ -0,0 +1,6 @@
+About NicheSphere
+=================
+
+**NicheSphere** is an sc-verse compatible Python library which allows the user to find differential co-localization domains / niches based on cell type pair co-localization probabilities in different conditions. Cell type pair co-localization probabilities can be obtained in different ways, for example, through deconvolution of spatial transcriptomics / PIC-seq data (getting the probabilities of finding each cell type in each spot / multiplet) ; or counting cell boundaries overlaps for each cell type pair in single cell spatial data (MERFISH , CODEX ...).
+
+It also offers the possibility to look at biological process based differential communication among differential co-localization domains based on Ligand-Receptor pairs expression data, such as results from CrossTalkeR https://github.com/CostaLab/CrossTalkeR .

nichesphere/nichesphere/source/_static/logo.png

@@ -1,7 +1,8 @@
-fake module
-=======================
+API
+===
 
-.. automodule:: fake
-   :members:
-   :undoc-members:
-   :show-inheritance:
+:doc:`coloc`
+
+:doc:`comm`
+
+:doc:`tl`

nichesphere/nichesphere/source/_static/logo_transparent.png

@@ -3,59 +3,44 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Nichesphere's documentation!
+Welcome to NicheSphere's documentation!
 =======================================
 
+**NicheSphere** is an sc-verse compatible Python library which allows the user to find differential co-localization domains / niches and associated biological processes based on cell type pair co-localization probabilities in different conditions. 
 
-Introduction
-============
 
-**Nichesphere** is an sc-verse compatible Python library which allows the user to find differential co-localization domains / niches based on cell type pair co-localization probabilities in different conditions. Cell type pair co-localization probabilities can be obtained in different ways, for example, through deconvolution of spatial transcriptomics / PIC-seq data (getting the probabilities of finding each cell type in each spot / multiplet) ; or counting cell boundaries overlaps for each cell type pair in single cell spatial data (MERFISH , CODEX ...).
+.. toctree::
+   :maxdepth: 2
+   :caption: About NicheSphere
 
-It also offers the possibility to look at biological process based differential communication among differential co-localization domains based on Ligand-Receptor pairs expression data, such as results from CrossTalkeR [ref.].
+   about
 
 
-Installation
-============
+.. toctree::
+   :maxdepth: 2
+   :caption: Installation
 
-In your terminal window run::
+   installation
 
-    conda create --name test python=3.10
-    conda activate test
-    conda install pip
-    pip install jupyterlab
-    conda install --channel conda-forge pygraphviz
-    conda install conda-forge::git
-    pip install git+https://github.com/CostaLab/Nichesphere#subdirectory=nichesphere
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Tutorials
 
-Tutorials
-=========
-
-In our first example we will use data from the Myocardial Infarction atlas from Kuppe, C. et. Al., 2022 to find differential co-localization domains related to ischemia. The data you'll need to run the tutorials can be found here: https://doi.org/10.5281/zenodo.15790389  
-
-.. nbgallery::
-    :caption: Notebooks:
-    :glob:
-
-    notebooks/Nichesphere_tutorial_MIvisium_coloc.ipynb
-    notebooks/Nichesphere_tutorial_MIvisium_comm.ipynb
-    notebooks/Nichesphere_tutorial_MIvisium_preprocessing.ipynb
-
+   tutorials
 
 Docker image and summarized analysis tutorial
 =============================================
 
 We provide access to a Docker image, available at: https://gitlab.com/sysbiobig/ismb-eccb-2025-tutorial-vt3/container_registry. The Docker image comes preconfigured with all necessary libraries, tools, and software required to follow the hands-on exercises. Additionally, the repository at https://gitlab.com/sysbiobig/ismb-eccb-2025-tutorial-vt3 contains a summarized Nichesphere co-localization + communication analysis tutorial.
 
 
-API
-===
+.. toctree::
+   :maxdepth: 2
+   :caption: API
 
-:doc:`coloc`
+   api
 
-:doc:`comm`
 
-:doc:`tl`
 
 

nichesphere/nichesphere/source/about.rst

@@ -0,0 +1,24 @@
+Installation
+============
+
+Prerequisites
+-------------
+Before installing, ensure you have the following:
+
+* Python > = 3.10 < = 3.12
+* pip (Python package manager)
+* pygraphviz . You can install it running this command in your terminal:
+
+
+.. code-block:: bash
+
+    conda install --channel conda-forge pygraphviz
+
+
+From GitHub
+-----------
+To install NicheSphere, run this command in your terminal:
+
+.. code-block:: bash
+
+    pip install git+https://github.com/CostaLab/Nichesphere#subdirectory=nichesphere