Dev

.github/workflows/python-package.yml

@@ -3,33 +3,31 @@ name: Python package
 
 on:
   push:
-    branches: [ "main", "doc" ] # Added "doc" so you can see if it works before merging!
+    branches: [ "main", "dev", "doc" ]
   pull_request:
-    branches: [ "main" ]
+    branches: [ "main", "dev" ]
 
 jobs:
   build:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10","3.11","3.12"]
+        python-version: ["3.11", "3.12", "3.14"]
 
     steps:
     - uses: actions/checkout@v4
-    
+
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5 # Updated to v5 (current best practice)
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
-        
+
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         python -m pip install flake8 pytest
-        # IMPORTANT: This installs YOUR local code from the current branch
-        pip install -e . 
-        # Check if requirements exist in the new root or docs folder
+        pip install -e .
         if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
 
     - name: Lint with flake8
@@ -39,5 +37,4 @@ jobs:
 
     - name: Test with pytest
       run: |
-        # This tells pytest to look in your new root tests/ folder
-        pytest tests/
+        pytest tests/

.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+data/
+figures/
+results/
+.ipynb_checkpoints/
+*.pyc
+Results_PILOT/
+docs/build/
+docs/_build/
+docs/generated/
+nichesphere/

.readthedocs.yaml

@@ -32,4 +32,8 @@ sphinx:
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
   install:
+    # 1. Install all dependencies (statsmodels, joblib, gravis)
      - requirements: docs/requirements.txt
+     # 2. Install the library itself so Sphinx can find your code
+     - method: pip
+       path: .

docs/Makefile

@@ -5,7 +5,7 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
+SOURCEDIR     = .
 BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".

docs/_static/custom.css

@@ -0,0 +1,104 @@
+/* --- Custom sidebar logo size --- */
+
+img[src*="logo.png"] {
+    max-height: 150px !important; /* Limits maximum image height */
+    height: 150px !important; /* Forces a fixed height of 140px */
+    width: auto !important; /* Maintains aspect ratio automatically */
+}
+
+
+
+
+/* --- Logo home page --- */
+
+/* Margin and spacing around the floating logo */
+img.logo-header {
+    background: none !important;
+    margin-left: 30px !important;
+    margin-bottom: 20px !important;
+    margin-top: -10px !important; /* Slightly aligns the top of the logo with the heading */
+}
+
+/* Improves text flow next to the logo */
+p {
+    text-align: justify;
+    line-height: 1.6 !important;
+}
+
+/* Clears floating alignment after the first block to prevent layout issues */
+.clear-float {
+    clear: both;
+}
+
+
+
+
+/* --- Styles for the nbgallery (Thumbnails in tutorial section) --- */
+
+/* Gallery container: uses flexbox to align cards */
+div.nbgallery {
+    display: flex !important;
+    flex-wrap: wrap !important;
+    gap: 15px !important;
+    margin-top: 20px !important;
+    margin-bottom: 25px !important;
+    align-items: stretch !important; /* IMPORTANT: Ensures all cards in the row have the same height */
+}
+
+/* Individual Card Formatting */
+.nbsphinx-gallery .sphx-glr-thumbcontainer,
+div.nbgallery > div {
+    border: 1px solid #e2e8f0 !important; /* Soft solid gray border */
+    border-style: solid !important;
+    border-radius: 50px !important;       /* Rounded corners */
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.04) !important; /* Soft shadow */
+    background-color: #ffffff !important;
+    padding: 15px !important;
+    width: 210px !important;              /* Uniform width */
+    display: flex !important;
+    flex-direction: column !important;     /* Column layout: Image top, Text bottom */
+    justify-content: flex-start !important; /* Content starts at the top */
+    transition: transform 0.2s ease, box-shadow 0.2s ease !important;
+    height: auto !important;               /* IMPORTANT: Do not force fixed height */
+    box-sizing: border-box !important;
+}
+
+/* Hover effect in tutorial notebooks*/
+.nbsphinx-gallery .sphx-glr-thumbcontainer:hover,
+div.nbgallery > div:hover {
+    transform: translateY(-3px) !important;
+    box-shadow: 0 8px 16px rgba(0, 0, 0, 0.08) !important;
+    border-color: #cbd5e1 !important;
+}
+
+/* Image inside the card */
+.nbsphinx-gallery .sphx-glr-thumbcontainer img,
+div.nbgallery img {
+    max-height: 120px !important;
+    object-fit: contain !important;
+    margin: 0 auto !important;
+    display: block !important;
+    border-bottom: 1px solid #f1f5f9 !important; /* Divider line below image */
+    padding-bottom: 10px !important;
+    margin-bottom: 0 !important;               /* REMOVES margin that pushed text down */
+}
+
+/* Notebook Text/Title style */
+.nbsphinx-gallery a,
+div.nbgallery a,
+.nbsphinx-gallery .sphx-glr-thumbcontainer a {
+    color: var(--color-foreground-primary, currentColor) !important; /* Professional dark text color */
+    font-weight: 600 !important;
+    font-size: 0.9em !important;
+    line-height: 1.4 !important;
+    text-decoration: none !important;     /* Removes blue underline */
+    text-align: center !important;
+    margin-top: 10px !important;         /* Space between divider line and text */
+    display: block !important;
+    width: 100% !important;
+}
+
+.nbsphinx-gallery a:hover,
+div.nbgallery a:hover {
+    color: var(--color-brand-primary, #2563eb) !important;
+}

docs/api.rst

@@ -1,9 +1,8 @@
 API Reference
 =============
 
-.. toctree::
-   :maxdepth: 2
-
-   coloc
-   comm
-   tl
+.. include:: coloc.rst
+.. include:: comm.rst
+.. include:: tl.rst
+.. include:: niche_stats.rst
+.. include:: sankey.rst

docs/coloc.rst

@@ -1,9 +1,24 @@
+.. custom label for :ref: on the home page 
+.. _api_coloc:
+
 coloc module
-=======================
+--------------
 
 Focused on differential co-localization
 
-.. automodule:: nichesphere.coloc
-   :members:
-   :undoc-members:
-   :show-inheritance:
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   ~nichesphere.coloc.OvsE_coloc_test
+   ~nichesphere.coloc.OvsE_coloc_test_adjPval
+   ~nichesphere.coloc.cellCatContained
+   ~nichesphere.coloc.colocNW
+   ~nichesphere.coloc.compute_sc_spatial_knn_coloc_matrix
+   ~nichesphere.coloc.compute_sc_spatial_radius_coloc_matrix
+   ~nichesphere.coloc.diffColoc_test
+   ~nichesphere.coloc.getColocProbs
+   ~nichesphere.coloc.reshapeColoc
+   ~nichesphere.coloc.spatialCTPlot
+   ~nichesphere.coloc.spatialNichePlot
+   ~nichesphere.coloc.spatialSingleCTPlot

docs/comm.rst

@@ -1,9 +1,21 @@
+.. custom label for :ref: on the home page 
+.. _api_comm:
+
 comm module
-=======================
+--------------
 
 Focused on differential communication
 
-.. automodule:: nichesphere.comm
-   :members:
-   :undoc-members:
-   :show-inheritance:
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   ~nichesphere.comm.calculate_LR_CT_pair_scores_dir
+   ~nichesphere.comm.catNW
+   ~nichesphere.comm.cellCatContained
+   ~nichesphere.comm.diffCcommStats
+   ~nichesphere.comm.equalizeScoresTable
+   ~nichesphere.comm.getDiffComm
+   ~nichesphere.comm.lr_ctPairScores_perCat_dir
+   ~nichesphere.comm.plotDiffCcommStatsHM
+   ~nichesphere.comm.unique

docs/conf.py

@@ -23,31 +23,74 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx_rtd_theme', 'nbsphinx', 'sphinx.ext.autosummary', 'sphinx.ext.intersphinx']
-
+extensions = [
+    'sphinx.ext.autodoc', 
+    'sphinx.ext.napoleon', 
+    'sphinx_book_theme',
+    'nbsphinx', 
+    'sphinx.ext.autosummary',
+    'sphinxcontrib.bibtex', 
+    'sphinx.ext.intersphinx',
+    'sphinx_design']
+
+autosummary_generate = True # Auto-generates individual API doc pages from summary tables
 templates_path = ['_templates']
 exclude_patterns = []
 
-language = 'English'
+language = 'en'
+
+# -- BibTeX citation settings
+bibtex_bibfiles = ['references.bib']
+bibtex_default_style = 'alpha'
+
+# -- It hides the input/output prompt numbers (In [1]: / Out [1]:).
+nbsphinx_prolog = """
+.. raw:: html
+
+    <style>
+        div.nbinput.container div.prompt,
+        div.nboutput.container div.prompt,
+        span.prompt {
+            display: none !important;
+            min-width: 0 !important;
+            padding: 0 !important;
+        }
+    </style>
+"""
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-#import sphinx_rtd_theme
+#import sphinx_book_theme
+
+html_theme = 'sphinx_book_theme'
+
+pygments_style = 'sphinx'       
 
-html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']
 
 # Path to the logo relative to the configuration directory
 html_logo = "_static/logo.png"
 
-# Ensure the static path is included so Sphinx finds the file
-html_static_path = ['_static']
+# Link custom CSS (logo sizing and styling, located in '_static')
+html_css_files = [
+    "custom.css",
+]
 
-# (Optional) If you want ONLY the logo to show without the project name text
+# Specific parameters passed directly to the 'sphinx_book_theme'.
 html_theme_options = {
-    'logo_only': True,
-    'display_version': False,
-}
-
-
+    # URL of the GitHub repository
+    "repository_url": "https://github.com/CostaLab/Nichesphere",
+    # GitHub button in the top navigation bar
+    "use_repository_button": True,
+    # Show a download button (e.g., PDF or Markdown/RST)
+    "use_download_button": True,
+    # Full-screen reading mode
+    "use_fullscreen_button": True,
+    # Collapse inactive subsections in the left sidebar to keep it tidy
+    "collapse_navbar": True,
+    # Set the maximum depth of heading levels (H1 to H4) shown in the right-hand page TOC
+    "show_toc_level": 4,
+    # Control how many navigation levels deep are automatically expanded in the left sidebar
+    "show_navbar_depth": 2,
+}

docs/generated/nichesphere.coloc.OvsE_coloc_test.rst

@@ -0,0 +1,6 @@
+nichesphere.coloc.OvsE\_coloc\_test
+===================================
+
+.. currentmodule:: nichesphere.coloc
+
+.. autofunction:: OvsE_coloc_test

docs/generated/nichesphere.coloc.OvsE_coloc_test_adjPval.rst

@@ -0,0 +1,6 @@
+nichesphere.coloc.OvsE\_coloc\_test\_adjPval
+============================================
+
+.. currentmodule:: nichesphere.coloc
+
+.. autofunction:: OvsE_coloc_test_adjPval

docs/generated/nichesphere.coloc.cellCatContained.rst

@@ -0,0 +1,6 @@
+nichesphere.coloc.cellCatContained
+==================================
+
+.. currentmodule:: nichesphere.coloc
+
+.. autofunction:: cellCatContained

docs/generated/nichesphere.coloc.colocNW.rst

@@ -0,0 +1,6 @@
+nichesphere.coloc.colocNW
+=========================
+
+.. currentmodule:: nichesphere.coloc
+
+.. autofunction:: colocNW

docs/generated/nichesphere.coloc.colocNW_old.rst

@@ -0,0 +1,6 @@
+nichesphere.coloc.colocNW\_old
+==============================
+
+.. currentmodule:: nichesphere.coloc
+
+.. autofunction:: colocNW_old