{"id":50138729,"url":"https://github.com/drmsabdullahi/genpath-pph","last_synced_at":"2026-05-24T00:02:08.534Z","repository":{"id":285904430,"uuid":"958012408","full_name":"DrMSAbdullahi/GenPath-PPH","owner":"DrMSAbdullahi","description":"GenPath-PPH: Python package for integrating gene expression and KEGG  pathway networks via Persistent Path Homology to detect disease-relevant  pathway dysregulation. Available on PyPI: pip install genpath-pph","archived":false,"fork":false,"pushed_at":"2026-05-23T18:07:56.000Z","size":13371,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-23T18:16:42.707Z","etag":null,"topics":["bioinformatics","pathway-analysis","pathway-enrichment-analysis","persistent-homology","persistent-path-homology","topological-data-analysis"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DrMSAbdullahi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-31T13:55:45.000Z","updated_at":"2026-05-23T18:07:59.000Z","dependencies_parsed_at":"2025-04-03T09:41:09.000Z","dependency_job_id":null,"html_url":"https://github.com/DrMSAbdullahi/GenPath-PPH","commit_stats":null,"previous_names":["drmsabdullahi/genpath-pph"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/DrMSAbdullahi/GenPath-PPH","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrMSAbdullahi%2FGenPath-PPH","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrMSAbdullahi%2FGenPath-PPH/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrMSAbdullahi%2FGenPath-PPH/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrMSAbdullahi%2FGenPath-PPH/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DrMSAbdullahi","download_url":"https://codeload.github.com/DrMSAbdullahi/GenPath-PPH/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrMSAbdullahi%2FGenPath-PPH/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33416315,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"ssl_error","status_checked_at":"2026-05-23T22:14:43.778Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bioinformatics","pathway-analysis","pathway-enrichment-analysis","persistent-homology","persistent-path-homology","topological-data-analysis"],"created_at":"2026-05-24T00:02:07.791Z","updated_at":"2026-05-24T00:02:08.529Z","avatar_url":"https://github.com/DrMSAbdullahi.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GenPath-PPH: Gene ExpressioN and PATHway network integration using Persistent Path Homology\n\nThis repository contains the code and supplementary material for the research article:\nAbdullahi et al., \"GenPath-PPH: Integrating Gene Expression and Pathway Networks via Persistent Path Homology Enhances Detection of Disease-Relevant Pathways\", *Computational and Structural Biotechnology Journal*, 27, 5348-5362, 2025. https://doi.org/10.1016/j.csbj.2025.11.018\n\n---\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Datasets](#datasets)\n- [GenPath-PPH Analysis](#genpath-pph-analysis)\n- [Project Dependencies](#project-dependencies)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Project Structure](#project-structure)\n- [License](#license)\n- [References](#references)\n\n---\n\n## Introduction\n\n**GenPath-PPH** introduces a novel approach for detecting disease-relevant pathways by integrating gene expression data with biological pathway networks using **persistent path homology (PPH)**. This enables detection of pathways significantly altered in disease conditions, exemplified with **hepatocellular carcinoma (HCC)** from peripheral blood mononuclear cell (PBMC) samples.\n\n---\n\n## Datasets\n\nWe used the following datasets in our project. \n\n- **RNA-Seq Gene Expression**: This comprises 26,575 genes from 34 samples (17 healthy, 17 disease). Original data from Han et al.[1], NCBI project PRJNA739257 [here](https://dataview.ncbi.nlm.nih.gov/object/PRJNA739257). \n\n- **KEGG Pathways**: We obtained 251 metabolic and signaling pathways from the KEGG database using the packages; 'AnnotationDbi' (v1.66.0) and 'org.Hs.eg.db' (v3.19.1) in R (v4.4.1).\n\n- **Pathways Networks**: Interaction networks (e.g., activations, inhibitions) parsed from KEGG Markup Language (KGML) files downloaded from the KEGG website (https://www.genome.jp/kegg/pathway.html).\n\n---\n\n## GenPath-PPH Analysis\n\nThe core methodology of **GenPath-PPH** consists of the following steps for identifying pathways that are most likely implicated in disease conditions.\n\n### 1. **Data Preparation**\n- **Data Peprocessing**: Transcript Per Million (TPM) normalization is applied to the raw gene expression data, followed by log₂ transformation to account for transcript length, sequencing depth, and to stabilize variance.\n\n- **Pathway-Specific Gene Expression**: Gene expression subsets corresponding to each biological pathway are extracted by mapping genes to their respective pathways. This yields pathway-specific datasets representing gene activity patterns within each pathway.\n\n- **Condition Grouping**: Samples are grouped into experimental conditions (e.g., **HCC** vs. **Control**) to examine how gene expression differences influence pathway topology.\n\n### 2. **Persistent Path Homology (PPH) Computation**\nFor each pathway and condition, PPH is computed to capture (track) topological changes (variations) in the gene expression network:\n   - **Filtration Scale**: Ranges from 0 to 1, where 0 represents the strongest correlation between genes and 1 represents the weakest.\n   - **Step Size**: A step of 0.01 yields 101 Betti numbers per pathway and condition across the filtration scale [0,1].\n\nThe output comprises two sets of Betti numbers (for **HCC** and **Control**), describing how the network’s topological features evolve with varying correlation strength. This enables a comparative analysis of pathway network alterations between the two conditions.\n\n### 3. **Statistical Significance**\n\n- #### a. **Global Differences**:\n  Persistence landscapes (PLs) were obtained for each pathway output from the PPH computation. The average landscape was then computed for each group (**HCC** and **Control**). The difference between these average landscapes was quantified using the supremum norm ($\\|\\cdot\\|$∞) and the $L_{1,2}$-norm, and the statistical significance of these differences was evaluated through permutation testing.\n\n- #### b. **Pathway-Level Differences**:\n   Kolmogorov–Smirnov (KS) tests and Cohen’s $d$ were applied to quantify the statistical significance of the differences observed between the two conditions (**HCC** and **Control**) for each pathway through permutation testing.\n\n   The obtained $p$-values were corrected for multiple testing using the Benjamini–Hochberg (BH) method. The adjusted $p$-values or False Discovery Rate (FDR) threshold was set to $\u003c 0.05$ throughout.\n\n### 4. **PPH Implementation Details**\n\n- **Dissimilarity Matrix**: This was constructed using $1 - |\\rho|$, where $\\rho$ is the Pearson correlation coefficient between genes.\n\n- **Path Complex Construction**: For each pathway and condition, path complexes are built using gene point clouds obtained from the dissimilarity matrix and the underlying pathway network structure.\n\n### 5. **Visualization**  \n\nCustom and library-based visualization scripts were implemented to illustrate both network-level and topological features.\n\n- **Custom Visualizations**:  \n  - **Correlation Heatmaps** showing inter-gene relationships within each pathway.  \n  - **Betti Number Evolution Plots** across filtration values.  \n  - **PCA Plots** for sample clustering.  \n  - **UpSet Plots** for pathway overlap and intersection analysis.  \n\n- **Library-Based Visualizations (Gudhi)**:  \n  - **Persistence Diagrams** using `plot_persistence_diagram`.  \n  - **Persistence Barcodes** using `plot_persistence_barcode`.  \n\nThese visualizations provide both qualitative and quantitative insights into the topological evolution and expression variability of pathways under different biological conditions.\n\n---\n\n## Project Dependencies\n\nThe following dependencies are required for running the analysis:\n\n### 1. **Python Libraries**  \nThe following Python libraries are required:\n\n- **`persim==0.2.1`**: Used for persistence landscape (PL) related computations.\n- **`scipy==1.14.1`**: Used for Kolmogorov-Smirnov (KS) test statistics and effect size computations.\n- **`statsmodels==0.13.5`**: Used for applying the Benjamini–Hochberg correction method for multiple testing.\n- **`biopython==1.76`**: Used for bioinformatics functionalities.\n- **`seaborn==0.11.2`**: Used for advanced statistical visualizations.\n- **`matplotlib==3.4.3`**: Used for general plotting.\n- **`mpl_toolkits==3.1.1`**: Used for 3D plotting.\n\n### 2. **R Libraries**  \nThe following R packages are required:\n\n- **`annotationDbi==1.66.0`**: Used for database management and gene annotation.\n- **`org.Hs.eg.db==3.19.1`**: Homo sapiens genome annotation package.\n- **`edgeR==3.42.4`**: Used for data normalization and transformation.\n\n### 3. **GenPath-PPH Core Framework**  \nThis framework builds on a modified version of [PathHom](https://github.com/WeilabMSU/PathHom), where correlation-based dissimilarity and filtration-level edge interaction tracking functions were added to enhance the PPH computation.\n\n### 4. **External Tools Used for Comparison**\nThe following packages were used only for benchmarking or comparison:\n- **`DESeq2 (R package)`**: Used for differential gene expression (DEG) analysis.\n- **`gseapy==v1.1.3`**: Used for Gene Set Enrichment Analysis (GSEA).\n\n---\n\n## Core Module and Enhancements\n\nThe main computation is implemented in `core.py` through the GenPathHomology class (an extended version of PathHomology). This module performs Persistent Path Homology (PPH) analysis on pathway networks by integrating:\n- **Point clouds** derived from gene expression data.\n- **Directed graphs (digraphs)** obtained from KEGG pathway networks.\n\nIntegration is achieved by masking the point cloud with the corresponding digraph, combining both gene-level and network-level information into a unified representation.\n\n### Enhancements in GenPath-PPH\n\nCompared to the original PathHom implementation, this version introduces several improvements:\n\n- **Flexible distance metrics**: Users can choose among multiple distance options for computing pairwise relationships between genes:\n   - `euclidean` (used in PathHom)\n   - `1 - correlation`\n   - `1 - |correlation|` (default for GenPath-PPH)\n\n- **Filtration-level edge tracking**: In addition to Betti number distributions (series), the function also returns the set of edges active (present) at each filtration level, allowing detailed inspection of the evolving topological structure.\n\n- **Integration-ready output**: \nFor each pathway and condition, the framework produces:\n   - Betti number series describing topological changes across filtrations.\n   - Filtration-level edge sets tracking the evolution of gene interactions.\n\nThese outputs can be directly integrated into downstream statistical, biological, or visualization analyses (e.g., group comparisons using persistence landscapes, pathway-level significance testing, tracking gene-gene connectivity dynamics across filtrations to identify stable or condition-specific interactions, quantifying edge persistence or node centrality changes to reveal rewired subnetworks, visualizing edge evolution heatmaps, persistence barcodes, or module reorganization across filtrations).\n\n---\n\n## Installation\n\n### Option 1 — Install from PyPI (recommended)\n```bash\npip install genpath-pph\n```\n\n### Option 2 — Install from source\n```bash\n# Clone the repository\ngit clone https://github.com/DrMSAbdullahi/GenPath-PPH.git\ncd GenPath-PPH\n```\n\n```bash\n# Install the necessary packages\npip install -r requirements.txt\n```\n\n---\n\n## Usage\n\n### Quick start (new high-level API)\n\n#### One-liner: single pathway\n```python\n    from genpath_pph import run_pathway\n    import numpy as np\n\n    # X_disease, X_control : np.ndarray (n_genes, n_samples)\n    # adj_matrix            : np.ndarray (n_genes, n_genes)\n\n    result = run_pathway(X_disease, X_control, adj_matrix)\n    print(result)\n    # PathwayResult(SIGNIFICANT)\n    #   β₀ → KS=0.4231  perm-p=0.002  Cohen-d=0.88  mean-diff=2.31\n    #   β₁ → KS=0.3812  perm-p=0.014  Cohen-d=0.72  mean-diff=0.98\n```\n\n#### One-liner: batch over many pathways\n```python\n    from genpath_pph import run_batch\n    from genpath_pph import extract_adjacency_matrices, extract_pathway_expressions\n\n    adj_matrices   = extract_adjacency_matrices(select_path_ids, ...)\n    pathway_exprs  = extract_pathway_expressions(select_path_ids, ...)\n\n    results_df = run_batch(\n        pathway_ids    = select_path_ids,\n        adj_matrices   = adj_matrices,\n        pathway_exprs  = pathway_exprs,\n        class_size     = 17,\n        n_permutations = 5000,\n    )\n    significant = results_df[results_df[\"significant\"]]\n    print(f\"{len(significant)} significant pathways found\")\n```\n\n#### Object-oriented interface\n```python\n    from genpath_pph import GenPathAnalysis\n\n    model = GenPathAnalysis(n_permutations=1000)\n    model.fit(X_disease, X_control, adj_matrix)\n\n    b0_d, b1_d = model.betti_series(\"disease\")\n    b0_c, b1_c = model.betti_series(\"control\")\n    delta0, delta1 = model.delta_betti()\n    phases = model.phase_summary()   # low / mid / high filtration breakdown\n    result = model.test()\n```\n\n### Import the package in Python (low-level API)\n\n```python\nfrom genpath_pph import GenPathHomology, PathwayDataProcessor\nimport numpy as np\n\n# Suppose you have a toy adjacency matrix for a pathway\nadj_matrix = np.array([\n    [0, 1, 0],\n    [0, 0, 1],\n    [1, 0, 0]\n])\n\n# Example edges extracted from adjacency matrix\nrows, cols = np.nonzero(adj_matrix)\nedges = np.column_stack((rows, cols))\n\n# Simulated gene expression for 3 genes, 4 samples\nexpression_data = np.random.rand(3, 4)\n\n# Initialize PPH object\npph = GenPathHomology()\n\n# Generate allowed paths (dimension 2)\nallowed_paths = pph.utils_generate_allowed_paths(edges, max_path=2)\n\n# Compute boundaries\nboundary_matrices, ranks, path_idx_flags = pph.utils_unlimited_boundary_operator(allowed_paths, max_path=2)\n\n# Compute Betti numbers for connected digraph\nbetti_numbers = pph.path_homology_for_connected_digraph(allowed_paths, max_path=2)\n\n# Print the results\nprint(\"Allowed paths:\", allowed_paths)\nprint(\"Boundary matrices:\", boundary_matrices)\nprint(\"Betti numbers:\", betti_numbers)\n```\n\n---\n\n### Built-in toy dataset\n\n```python\nfrom genpath_pph import GenPathHomology, load_toy_data\n\n# Load built-in toy expression data and pathway edges\ndf, edges, filtration = load_toy_data()\n\n# Split into control and disease groups\nX_control = df[[\"C1\", \"C2\", \"C3\"]].values\nX_disease  = df[[\"D1\", \"D2\", \"D3\"]].values\n\npph = GenPathHomology()\n\n# Compute Betti-0 for each group\nbetti_0_control, _ = pph.persistent_path_homology_from_digraph(\n    X_control, edges, target_dimension=0, filtration=filtration\n)\nbetti_0_disease, _ = pph.persistent_path_homology_from_digraph(\n    X_disease, edges, target_dimension=0, filtration=filtration\n)\n\nprint(\"Control β₀:\", [int(x) for x in betti_0_control])\nprint(\"Disease β₀:\", [int(x) for x in betti_0_disease])\n```\n\n### Run some examples\n\n**1. Toy example test** - This is a small simulated gene expression dataset and toy graph used in our manuscript to demonstrate PPH computation:\n```bash\npython core.py --test\n```\nRunning the above will:\n- Generate a small simulated gene expression dataset.\n- Compute persistent path homology on a toy graph.\n- Print Betti numbers for each dimension across the filtration.\n\n**2. Example for real pathways** - Demonstrates PPH computation for real biological pathways (p53 signaling pathway and ferroptosis):\n\n```bash\npython examples/p53_signaling.py\npython examples/ferroptosis.py\n```\n\n**3. Jupyter Notebook examples** - Detailed analyses on HCC gene expression data, including:\n- Comparing PH vs PPH on a toy example.\n- Global difference analysis across HCC samples.\n- Pathway-level analysis to identify significant pathways.\n```bash\njupyter notebook notebooks/toy_example_ph_vs_pph.ipynb\njupyter notebook notebooks/genpath_pph_global.ipynb\njupyter notebook notebooks/genpath_pph_pathway_level.ipynb\n```\n\nThese examples demonstrate how to compute PPH (Betti number computation), visualize topological features, and interpret identified pathways.\n\n---\n\n## Project Structure\n\n```text\nGenPath-PPH/\n│\n├── README.md\n├── LICENSE.txt\n├── requirements.txt            # Python dependencies\n├── pyproject.toml              # PyPI packaging config       \n├── .github/\n│   └── workflows/\n│       └── publish.yml         # Auto-publish to PyPI        \n├── genpath_pph/                # Core package\n│   ├── __init__.py\n│   ├── core.py                 # Core PPH computations\n│   ├── utils.py                # Utility functions (allowed paths, boundaries, etc.)\n│   ├── run_analysis.py         # Optional analysis scripts for custom workflows\n│   └── api.py                  # High-level one-liner API    \n├── examples/                   # Example scripts for toy and real pathways\n│   ├── toy_example.py\n│   ├── p53_signaling.py\n│   └── ferroptosis.py\n├── notebooks/                  # Jupyter notebooks for detailed analyses\n│   ├── toy_example_ph_vs_pph.ipynb     # Compare PH vs PPH on toy data\n│   ├── genpath_pph_global.ipynb        # Global difference analysis on HCC data\n│   └── genpath_pph_pathway_level.ipynb # Pathway-level analysis on HCC data\n└── data/                  # Datasets used/created\n```\n\n---\n\n## License\n\n### Code License\n\nThe code in this repository is licensed under the **MIT License**. You are free to use, modify, and distribute the code, provided that the following conditions are met:\n\n- The original copyright notice and the MIT License text must be included in all copies or substantial portions of the code.\n- The code is provided \"as is,\" without warranty of any kind.\n\nFor the full MIT License text, please see the [LICENSE](./LICENSE.txt) file.\n\n### Data License\n\nThe data in this repository is licensed under the **Creative Commons Attribution 4.0 International License (CC BY 4.0)**. You are free to:\n\n- **Share**: Copy and redistribute the material in any medium or format.\n- **Adapt**: Remix, transform, and build upon the material for any purpose, including commercial purposes.\n\nUnder the following conditions:\n\n- **Attribution**: You must provide appropriate credit, give a link to the license, and indicate if changes were made. You may do this in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.\n- **No additional restrictions**: You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.\n\nThe data is provided \"as is,\" without any warranty of fitness for a particular purpose. Users are solely responsible for their use of the data and any consequences thereof.\n\nFor the full Creative Commons Attribution 4.0 International License text, please visit the [CC BY 4.0 License](https://creativecommons.org/licenses/by/4.0/).\n\n---\n\n#### References\n\n[1] Han, Z., Feng, W., Hu, R., Ge, Q., Ma, W., Zhang, W., Xu, S., Zhan, B., Zhang, L., Sun, X. et al. (2021). 'RNA-seq profiling reveals PBMC RNA as a potential biomarker for hepatocellular carcinoma.' Sci. Reports, 11, 17797.\n\n[2] Chen, D., Liu, J., Wu, J., Wei, G.-W., Pan, F., Yau, S.-T. (2023). 'Path topology in molecular and materials sciences'. The Journal of Physical Chemistry Letters 14 (4), 954–964.\n\n[3] Chowdhury, S., Mémoli, F. (2018). 'Persistent path homology of directed networks'. In: Proceedings of the Twenty-Ninth Annual ACM-SIAM Symposium on Discrete Algorithms, pp. 1152–1169.\n\n---\n\n#### Citation\n\nIf you use this codebook in your research or publication, please cite:\n\n[Abdullahi, M.S.; Piro, R.M.; Suratanee, A.; Plaimas, K. \"GenPath-PPH: Integrating Gene Expression and Pathway Networks via Persistent Path Homology Enhances Detection of Disease-Relevant Pathways\". Computational and Structural Biotechnology Journal (Submitted), 27, 5348-5362, 2025. https://doi.org/10.1016/j.csbj.2025.11.018]\n\nFor questions or additional permissions, contact [abdullahi.sirajo@udusok.edu.ng].\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrmsabdullahi%2Fgenpath-pph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrmsabdullahi%2Fgenpath-pph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrmsabdullahi%2Fgenpath-pph/lists"}