UCD-BDLab · ramosv · Nov 30, 2025 · Nov 30, 2025 · Nov 30, 2025 · Nov 30, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/README.md b/README.md
diff --git a/TCGA-Notebooks/TCGA-KIPAN.ipynb b/TCGA-Notebooks/TCGA-KIPAN.ipynb
@@ -15,7 +15,7 @@
     "- **Goal**: Perform histological subtype classification.\n",
     "- **Prediction Target**: Predict the specific kidney cancer subtype (`KIRC`, `KIRP`, or `KICH`) from its multi-omics profile.\n",
     "\n",
-    "**Data Source:** Broad Institute FireHose (`http://firebrowse.org/?cohort=KIPAN`)"
+    "**Data Source:** Broad Institute FireHose(`http://firebrowse.org/?cohort=KIPAN`)"
    ]
   },
   {

diff --git a/assets/BioNeuralNet.png b/assets/BioNeuralNet.png
diff --git a/assets/BioNeuralNet1-0.png b/assets/BioNeuralNet1-0.png
diff --git a/assets/bioneuralnet_api.png b/assets/bioneuralnet_api.png
diff --git a/assets/clusters.png b/assets/clusters.png
diff --git a/assets/emb_kipan.png b/assets/emb_kipan.png
diff --git a/assets/embeddings.png b/assets/embeddings.png
diff --git a/assets/kipan_net.png b/assets/kipan_net.png
diff --git a/assets/metrics_plot_1.png b/assets/metrics_plot_1.png
diff --git a/assets/metrics_plot_2.png b/assets/metrics_plot_2.png
diff --git a/assets/performance.png b/assets/performance.png
diff --git a/assets/plot_network.png b/assets/plot_network.png
diff --git a/assets/plot_network2.png b/assets/plot_network2.png
diff --git a/assets/rosmap_net1.png b/assets/rosmap_net1.png
diff --git a/assets/rosmap_net2.png b/assets/rosmap_net2.png
diff --git a/bioneuralnet/__init__.py b/bioneuralnet/__init__.py
@@ -23,7 +23,7 @@
 * `utils`: Utilities for logging, reproducibility, graph generation, and data processing.
 """
 
-__version__ = "1.2.0"
+__version__ = "1.2.1"
 
 # submodules to enable direct imports such as `from bioneuralnet import utils`
 from . import utils

diff --git a/bioneuralnet/clustering/hybrid_louvain.py b/bioneuralnet/clustering/hybrid_louvain.py
@@ -20,7 +20,7 @@ class HybridLouvain:
         k4 (float): Weight for Correlated Louvain.
         max_iter (int): Maximum number of iterations.
         weight (str): Edge weight parameter name.
-        tune (bool): Flag to enable tuning of parameters       
+        tune (bool): Flag to enable tuning of parameters
     """
     def __init__(
         self,

diff --git a/bioneuralnet/downstream_task/dpmon.py b/bioneuralnet/downstream_task/dpmon.py
@@ -26,7 +26,6 @@
 from ray import train
 from ray import tune
 from ray.tune import Checkpoint
-#from bioneuralnet.utils.ray_compatability import train, tune, Checkpoint
 from ray.tune import CLIReporter
 from ray.tune.error import TuneError
 from ray.tune.stopper import TrialPlateauStopper
@@ -803,7 +802,7 @@ def run_hyperparameter_tuning(X_train, y_train, adjacency_matrix, clinical_data,
         grace_period=30,
         reduction_factor=2
     )
-    
+
     best_configs = []
 
     omics_data = omics_dataset[0]

diff --git a/bioneuralnet/metrics/plot.py b/bioneuralnet/metrics/plot.py
@@ -345,7 +345,7 @@ def plot_network(adjacency_matrix, weight_threshold=0.0, show_labels=False, show
 def find_omics_modality(mapping_df, dfs, source_names=None):
     """
     Maps features in the mapping DataFrame to their omics source based on provided dataframes.
-    
+
     Args:
 
         mapping_df (pd.DataFrame): DataFrame with an "Omic" column listing feature names.
@@ -354,7 +354,7 @@ def find_omics_modality(mapping_df, dfs, source_names=None):
 
     Returns:
         pd.DataFrame: Updated mapping DataFrame with an additional "Source" column.
-        
+
     """
     if not source_names:
         source_names = []

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -12,7 +12,7 @@
 try:
     release = metadata.version("bioneuralnet")
 except metadata.PackageNotFoundError:
-    release = "1.2.0"
+    release = "1.2.1"
 
 project = "BioNeuralNet"
 version = release

diff --git a/docs/source/datasets.rst b/docs/source/datasets.rst
@@ -121,7 +121,7 @@ Valid ``dataset_name`` values (case-insensitive):
 - ``"kipan"``
 - ``"paad"``
 
-The :pyattr:`DatasetLoader.shape <bioneuralnet.datasets.DatasetLoader.shape>` property returns a mapping from table name to ``(n_rows, n_cols)`` for each loaded table.
+The `.shape` property returns a mapping from table name to ``(n_rows, n_cols)`` for each loaded table.
 
 Built-in Datasets
 -----------------

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -69,33 +69,47 @@ BioNeuralNet allows you to inspect the topology of your constructed networks. Th
 .. figure:: _static/kipan_net.png
    :align: center
    :alt: Multi-Omics Network Visualization
-   :width: 90%
+   :width: 100%
 
-   *Network visualization of a highly connected gene module identified in the KIPAN dataset.*
+   *Network visualization of a highly connected gene module identified in the KIPAN dataset.* `Full Size Image <https://bioneuralnet.readthedocs.io/en/latest/_images/kipan_net.png>`_
 
 **Top Identified Biomarkers (Hub Omics)**
 
 The table below lists the top hub features identified in the network above, ranked by their degree centrality.
 
 .. list-table:: Omics with high degree
-   :widths: 50 25
+   :widths: 40 10 10 10
    :header-rows: 1
    :align: center
 
    * - Feature Name (Omic)
+     - Index
      - Degree
+     - Source
    * - INPP5J_27124
+     - 5
      - 12
+     - RNA
    * - SLC26A7_115111
+     - 26
      - 9
+     - RNA
    * - HEPACAM2_253012
+     - 12
      - 7
+     - RNA
    * - CLNK_116449
+     - 16
      - 7
+     - RNA
    * - RHCG_51458
+     - 27
      - 6
+     - RNA
    * - CLCNKB_1188
+     - 3
      - 6
+     - RNA
 
 
 Why Graph Neural Networks for Multi-Omics?
@@ -117,9 +131,9 @@ By projecting high-dimensional omics networks into latent spaces, BioNeuralNet d
 .. figure:: _static/emb_kipan.png
    :align: center
    :alt: t-SNE visualization of Network Embeddings
-   :width: 90%
+   :width: 100%
 
-   *2D projection of Network Embeddings showing distinct separation between omics modalities.*
+   *2D projection of Network Embeddings showing distinct separation between omics modalities.* `Full Size Image <https://bioneuralnet.readthedocs.io/en/latest/_images/emb_kipan.png>`_
 
 For detailed explanations of BioNeuralNet's supported GNN architectures, see :doc:`gnns`.
 

diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -1,7 +1,7 @@
 Installation
 ============
 
-BioNeuralNet is fully compatible with Python 3.10, 3.11 and 3.12 and supports Windows, macOS, and Linux platforms. Follow these steps to install BioNeuralNet along with necessary dependencies.
+BioNeuralNet is tested with Python 3.10, 3.11, and 3.12 and supports Windows, macOS, and Linux platforms. Follow these steps to install BioNeuralNet along with the necessary dependencies.
 
 Recommended System Requirements
 -------------------------------
@@ -22,10 +22,11 @@ Recommended System Requirements
    * - Storage
      - Minimum 64GB for system and software; SSD recommended; 500GB+ for large datasets
    * - GPU (Optional but recommended)
-     - NVIDIA GPU with `>=` 6GB VRAM or Intel Arc GPU for faster training; ensure drivers and CUDA/cuDNN versions match PyTorch
+     - NVIDIA GPU with >= 6GB VRAM or Intel Arc GPU for faster training; ensure drivers and CUDA/cuDNN versions match PyTorch
    * - Notes
-     - GPU acceleration significantly improves training speed; hardware requirements increase with model and dataset size
-
+     - GPU acceleration significantly improves training speed; hardware requirements increase with model and dataset size. 
+         If you have an NVIDIA graphics card or an M-series Mac chip, please see the respective installation instructions below.
+
 1. **Install BioNeuralNet via pip**
 
    The core modules, including graph embeddings, disease prediction (DPMON), and clustering, can be installed directly:
@@ -34,30 +35,39 @@ Recommended System Requirements
 
       pip install bioneuralnet
 
-   This will also install the required Ray components for hyperparameter tuning (Ray Tune and Ray Train) if your environment honors package extras.
+   This will also install the required Ray components for hyperparameter tuning (Ray Tune and Ray Train).
 
 2. **Install PyTorch and PyTorch Geometric (Required for GNNs and DPMON)**
 
    BioNeuralNet utilizes PyTorch and PyTorch Geometric for graph neural network computations (e.g., GNN embeddings and the DPMON model). These are **not** pinned automatically because GPU/CPU builds and CUDA versions vary by system, so you should install them separately.
 
-   Basic installation (CPU-only or default build):
+   Basic installation (CPU-only or simple environments):
 
    .. code-block:: bash
 
       pip install torch
       pip install torch_geometric
 
-   We recommend the following tested versions for DPMON and GNN-based workflows:
+   If this fails or you need a GPU-enabled build, please follow the official installation guides to select the correct wheels for your OS, Python version, and CUDA:
 
-   .. code-block:: bash
+   - `PyTorch Installation Guide <https://pytorch.org/get-started/locally/>`_
+   - `PyTorch Geometric Installation Guide <https://pytorch-geometric.readthedocs.io/en/latest/notes/installation.html>`_
 
-      pip install "torch==2.7.0+cu118"
-      pip install "torch_geometric==2.6.1"
+   .. note::
 
-   For GPU-enabled installations or advanced configurations, please refer to the official documentation and choose the appropriate build based on your system and GPU availability:
+      On Apple Silicon (M1/M2/M3) Macs, PyTorch can use the Metal (MPS) backend instead of CUDA. 
+      For details and recommended installation commands, see the official guide:
 
-   - `PyTorch Installation Guide <https://pytorch.org/get-started/locally/>`_
-   - `PyTorch Geometric Installation Guide <https://pytorch-geometric.readthedocs.io/en/latest/notes/installation.html>`_
+   - `PyTorch on Metal (Apple Developer) <https://developer.apple.com/metal/pytorch/>`_
+
+   **Example tested GPU configuration (Windows/Linux + CUDA 11.8)**
+
+   The following versions have been tested with DPMON and GNN-based workflows:
+
+   .. code-block:: bash
+
+      pip install "torch==2.7.0+cu118" --index-url https://download.pytorch.org/whl/cu118
+      pip install "torch_geometric==2.6.1"
 
    .. figure:: _static/pytorch.png
       :align: center
@@ -67,11 +77,43 @@ Recommended System Requirements
       :align: center
       :alt: PyTorch Geometric Installation Guide Example
 
+   .. note::
+
+      If you are working on Windows, we recommend installing Git Bash so that all shell commands in this documentation work as written.
+      You can install Git for Windows (which includes Git Bash) from:
+
+   - `Git for Windows Installer <https://git-scm.com/install/windows>`_
+
+   **Troubleshooting: CUDA / PyG compatibility**
+
+   If you are using an NVIDIA graphics card, you must ensure that the CUDA version used by PyTorch and the wheels for PyTorch Geometric (and its extensions) match. When they do not, you may encounter segmentation faults during import.
+
+   The following block uninstalls all relevant torch and PyTorch Geometric libraries and reinstalls a known-working combination (Linux + CUDA 11.8). You can copy and paste this block into your terminal. If it fails, try running each line one by one:
+
+   .. code-block:: bash
+
+      pip uninstall pyg-lib torch torchvision torchaudio torch-scatter torch-sparse torch-cluster torch-spline-conv torch-geometric -y
+
+      pip install --no-cache-dir "torch==2.7.0+cu118" --index-url https://download.pytorch.org/whl/cu118
+      pip install --no-cache-dir pyg-lib -f https://data.pyg.org/whl/torch-2.7.0+cu118.html
+
+      pip install --no-cache-dir torch-scatter -f https://data.pyg.org/whl/torch-2.7.0+cu118.html
+      pip install --no-cache-dir torch-sparse -f https://data.pyg.org/whl/torch-2.7.0+cu118.html
+      pip install --no-cache-dir torch-cluster -f https://data.pyg.org/whl/torch-2.7.0+cu118.html
+      pip install --no-cache-dir torch-spline-conv -f https://data.pyg.org/whl/torch-2.7.0+cu118.html
+      pip install --no-cache-dir torch-geometric -f https://data.pyg.org/whl/torch-2.7.0+cu118.html
+
+   After running the above, you can verify your installation with:
+
+   .. code-block:: bash
+
+      python -c "import torch_geometric; from torch_scatter import scatter_add; print('OK')"
+
 3. **Ray for Hyperparameter Tuning (DPMON and Other HPO Workflows)**
 
-   BioNeuralNet uses `Ray Tune` and `Ray Train` for hyperparameter optimization and checkpointing in components such as DPMON.
+   BioNeuralNet uses :mod:`Ray Tune` and :mod:`Ray Train` for hyperparameter optimization and checkpointing in components such as DPMON.
 
-   If you installed BioNeuralNet via pip in a standard environment, Ray with the necessary extras should be installed automatically. For reproducibility or if your environment strips extras, you can explicitly install the tested Ray version:
+   If you installed BioNeuralNet via pip in a standard environment, Ray with the necessary extras should be installed automatically. For reproducibility, or if your environment strips extras, you can explicitly install the tested Ray version:
 
    .. code-block:: bash
 
@@ -96,7 +138,7 @@ Recommended System Requirements
       pydantic >= 2.5
       ray[tune,train] = 2.46.0
 
-   *Note: The installer is flexible. It will attempt to install these tested versions (or compatible newer releases) to ensure stability, but will not strictly force them if your environment requires slight deviations.*
+   Our packaging specifies minimum versions for these dependencies; pip may install newer compatible releases depending on your environment.
 
 5. **Optional: Install R and External Tools (e.g., SmCCNet)**
 
@@ -109,15 +151,14 @@ Recommended System Requirements
 
         if (!requireNamespace("BiocManager", quietly = TRUE))
             install.packages("BiocManager")
-        
+
         install.packages(c("dplyr", "jsonlite"))
         BiocManager::install(c("impute", "preprocessCore", "GO.db", "AnnotationDbi"))
         install.packages("SmCCNet")
         install.packages("WGCNA")
 
    See :doc:`external_tools/index` for further details on external tools.
 
-
 Next Steps
 ----------
 

diff --git a/docs/source/metrics.rst b/docs/source/metrics.rst
@@ -5,10 +5,6 @@ The ``metrics`` module provides a suite of tools for statistical analysis, quali
 
 To see the full code used to generate the plots below (specifically for the Kidney Cancer analysis), refer to our **TCGA KIPAN Biomarker Discovery** tutorial in :doc:`notebooks/index`.
 
-.. contents:: Table of Contents
-   :local:
-   :depth: 2
-
 Performance Evaluation
 ----------------------
 
@@ -47,14 +43,9 @@ The example below shows embeddings from the **TCGA KIPAN** dataset, revealing di
 
    from bioneuralnet.metrics import plot_embeddings
 
-   # Retrieve embeddings from the trained GNN model
-   embeddings_array = embeddings.values  
-
-   # Prepare labels (e.g., Omics Type or Phenotype) for coloring
-   node_labels = gnn._prepare_node_labels()
-
-   # Generate t-SNE projection
-   plot_embeddings(embeddings_array, node_labels, title="Embeddings in 2D space")
+   # feature(omics) embeddings colored by omics type.
+   print(f"Plotting Feature Embeddings for graph:")
+   plot_embeddings(GAT_embeddings_array, node_labels, legend_labels=["DNA_Methylation", "RNA", "miRNA"])
 
 Network Visualization & Clustering
 ----------------------------------

diff --git a/docs/source/notebooks/TCGA-Biomarkers.ipynb b/docs/source/notebooks/TCGA-Biomarkers.ipynb
@@ -19,7 +19,7 @@
     "\n",
     "- We will also leverage BioNeuralNet visualization tools to explore the discovered communities further.\n",
     "\n",
-    "**Data Source:** [Broad Institute FireHose](`http://firebrowse.org/?cohort=KIPAN`)\n",
+    "**Data Source:** [Broad Institute FireHose](http://firebrowse.org/?cohort=KIPAN)\n",
     "\n",
     "*For the end-to-end analysis see TCGA-KIPAN Analysis*"
    ]