txoptimus 0.1.0__tar.gz

txoptimus-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include LICENSE
+include README.md
+include requirements.txt
+include environment.yml
+recursive-include txoptimus/core/data_splits *.csv *.obo *.py
+recursive-include txoptimus/core/graphmask *.py
+recursive-include txoptimus/resources *.txt *.json

txoptimus-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.1
+Name: txoptimus
+Version: 0.1.0
+Summary: Zero-shot drug repurposing via TxGNN on PrimeKG and OptimusKG
+Home-page: https://github.com/arsalanriaz/txoptimus
+Author: arsalanriaz
+Keywords: drug-repurposing zero-shot graph-neural-network knowledge-graph biomedical txgnn primekg optimuskg
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: torch==2.4.0
+Requires-Dist: dgl==2.4.0
+Requires-Dist: torch-geometric==2.6.1
+Requires-Dist: numpy==1.24.4
+Requires-Dist: pandas==2.0.3
+Requires-Dist: scikit-learn==1.3.2
+Requires-Dist: scipy==1.10.1
+Requires-Dist: matplotlib==3.7.5
+Requires-Dist: tqdm==4.70.0
+Requires-Dist: requests==2.32.4
+Requires-Dist: transformers
+Requires-Dist: networkx==3.1
+Requires-Dist: pydantic==2.10.6
+Requires-Dist: PyYAML==6.0.3
+Requires-Dist: openpyxl==3.1.5
+Requires-Dist: xlsxwriter==3.2.9
+Requires-Dist: goatools==1.6.5
+Requires-Dist: statsmodels==0.14.1
+Requires-Dist: rich==14.3.4
+Requires-Dist: pillow==10.4.0
+
+# TxOptimus
+
+**Zero-shot drug repurposing via TxGNN on PrimeKG and OptimusKG.**
+
+TxOptimus is a unified Python package that wraps [TxGNN](https://github.com/mims-harvard/TxGNN) (Huang et al., *Nature Medicine*, 2024) with two knowledge graph backends:
+
+- **TxGNN Prime** — the original baseline trained on Harvard [PrimeKG](https://github.com/mims-harvard/PrimeKG)
+- **TxGNN Optimus** — an enriched model trained on the Zitnik Lab's [OptimusKG](https://zitniklab.hms.harvard.edu/projects/OptimusKG/), a multimodal knowledge graph validated by LLM extraction (PaperQA3)
+
+OptimusKG achieves a **~34% improvement in Macro AUROC** over PrimeKG in zero-shot drug repurposing for oncology under the `cell_proliferation` split.
+
+## Installation
+
+```bash
+# Create a dedicated environment (recommended)
+conda create -n txoptimus python=3.8
+conda activate txoptimus
+
+# Install
+pip install txoptimus
+```
+
+> **⚠ System Requirements:**
+> - RAM: ≥32 GB (OptimusKG loads a 21.8M-edge graph)
+> - Storage: ≥8 GB free disk space
+> - Python: 3.8+ (tested on 3.8.20)
+> - GPU: Optional (CPU inference supported)
+
+## Quick Start
+
+### 1. Download data files
+
+```bash
+txoptimus --setup              # downloads both PrimeKG and OptimusKG data
+txoptimus --setup prime        # only PrimeKG
+txoptimus --setup optimus      # only OptimusKG
+```
+
+### 2. Run zero-shot drug repurposing
+
+```bash
+# Using OptimusKG (recommended)
+txoptimus --engine optimus --diseases "oral cavity cancer" "glioblastoma"
+
+# Using PrimeKG baseline
+txoptimus --engine prime --diseases "oral cavity cancer"
+
+# Benchmark mode — runs both and generates a comparison report
+txoptimus --engine benchmark --diseases "oral cavity cancer"
+```
+
+### 3. Fuzzy disease matching
+
+TxOptimus uses **PubMedBERT embeddings** to fuzzy-match your disease terms against the knowledge graph vocabulary. If your input doesn't match exactly, the tool will show the top-10 closest matches and let you pick:
+
+```
+Disease term: "breast cancer"
+
+Matched terms in OPTIMUS:
+  [1] invasive breast carcinoma (similarity: 0.94)
+  [2] breast carcinoma (similarity: 0.91)
+  [3] triple-negative breast cancer (similarity: 0.89)
+
+Select terms (e.g., '1 3' or 'all'): 1 3
+```
+
+### 4. Enable explainability
+
+```bash
+# Add --graphmask to enable GraphMask pathway attribution
+txoptimus --engine optimus --diseases "oral cavity cancer" --graphmask
+```
+
+> **Note:** GraphMask requires ≥30 GB RAM and takes 2-4 hours on CPU.
+
+## Full CLI Reference
+
+| Argument | Type | Default | Description |
+|:---|:---|:---|:---|
+| `--engine` | str | `optimus` | `prime`, `optimus`, or `benchmark` |
+| `--diseases` | str[] | *(required)* | Disease terms (fuzzy matched) |
+| `--graphmask` | flag | `False` | Enable GraphMask explainability |
+| `--output_dir` | str | `./txoptimus_output` | Output directory |
+| `--prefix` | str | `txoptimus` | File prefix |
+| `--threads` | int | `18` | CPU threads |
+| `--top_k` | int | `100` | Drug candidates per disease |
+| `--setup` | str? | — | Download data (`prime`/`optimus`/both) |
+| `--data_dir` | str | `~/.txoptimus` | Data directory override |
+
+## Output Files
+
+| File | Description |
+|:---|:---|
+| `{prefix}_{engine}_results.json` | Full metrics (AUROC, AUPRC, per-relation, graph profile) |
+| `{prefix}_{engine}_candidates.csv` | Top-K drug candidates ranked by score |
+| `{prefix}_comparison_report.md` | Side-by-side comparison (benchmark mode only) |
+
+## Citation
+
+If you use TxOptimus in your research, please cite the original TxGNN paper:
+
+```bibtex
+@article{huang2024txgnn,
+  title={Zero-shot prediction of therapeutic use with geometric deep learning and clinician centered design},
+  author={Huang, Kexin and Chandak, Payal and Wang, Qianwen and Haber, Shreyas and Zitnik, Marinka},
+  journal={Nature Medicine},
+  year={2024}
+}
+```
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+## Author
+
+**arsalanriaz**

txoptimus-0.1.0/README.md

@@ -0,0 +1,117 @@
+# TxOptimus
+
+**Zero-shot drug repurposing via TxGNN on PrimeKG and OptimusKG.**
+
+TxOptimus is a unified Python package that wraps [TxGNN](https://github.com/mims-harvard/TxGNN) (Huang et al., *Nature Medicine*, 2024) with two knowledge graph backends:
+
+- **TxGNN Prime** — the original baseline trained on Harvard [PrimeKG](https://github.com/mims-harvard/PrimeKG)
+- **TxGNN Optimus** — an enriched model trained on the Zitnik Lab's [OptimusKG](https://zitniklab.hms.harvard.edu/projects/OptimusKG/), a multimodal knowledge graph validated by LLM extraction (PaperQA3)
+
+OptimusKG achieves a **~34% improvement in Macro AUROC** over PrimeKG in zero-shot drug repurposing for oncology under the `cell_proliferation` split.
+
+## Installation
+
+```bash
+# Create a dedicated environment (recommended)
+conda create -n txoptimus python=3.8
+conda activate txoptimus
+
+# Install
+pip install txoptimus
+```
+
+> **⚠ System Requirements:**
+> - RAM: ≥32 GB (OptimusKG loads a 21.8M-edge graph)
+> - Storage: ≥8 GB free disk space
+> - Python: 3.8+ (tested on 3.8.20)
+> - GPU: Optional (CPU inference supported)
+
+## Quick Start
+
+### 1. Download data files
+
+```bash
+txoptimus --setup              # downloads both PrimeKG and OptimusKG data
+txoptimus --setup prime        # only PrimeKG
+txoptimus --setup optimus      # only OptimusKG
+```
+
+### 2. Run zero-shot drug repurposing
+
+```bash
+# Using OptimusKG (recommended)
+txoptimus --engine optimus --diseases "oral cavity cancer" "glioblastoma"
+
+# Using PrimeKG baseline
+txoptimus --engine prime --diseases "oral cavity cancer"
+
+# Benchmark mode — runs both and generates a comparison report
+txoptimus --engine benchmark --diseases "oral cavity cancer"
+```
+
+### 3. Fuzzy disease matching
+
+TxOptimus uses **PubMedBERT embeddings** to fuzzy-match your disease terms against the knowledge graph vocabulary. If your input doesn't match exactly, the tool will show the top-10 closest matches and let you pick:
+
+```
+Disease term: "breast cancer"
+
+Matched terms in OPTIMUS:
+  [1] invasive breast carcinoma (similarity: 0.94)
+  [2] breast carcinoma (similarity: 0.91)
+  [3] triple-negative breast cancer (similarity: 0.89)
+
+Select terms (e.g., '1 3' or 'all'): 1 3
+```
+
+### 4. Enable explainability
+
+```bash
+# Add --graphmask to enable GraphMask pathway attribution
+txoptimus --engine optimus --diseases "oral cavity cancer" --graphmask
+```
+
+> **Note:** GraphMask requires ≥30 GB RAM and takes 2-4 hours on CPU.
+
+## Full CLI Reference
+
+| Argument | Type | Default | Description |
+|:---|:---|:---|:---|
+| `--engine` | str | `optimus` | `prime`, `optimus`, or `benchmark` |
+| `--diseases` | str[] | *(required)* | Disease terms (fuzzy matched) |
+| `--graphmask` | flag | `False` | Enable GraphMask explainability |
+| `--output_dir` | str | `./txoptimus_output` | Output directory |
+| `--prefix` | str | `txoptimus` | File prefix |
+| `--threads` | int | `18` | CPU threads |
+| `--top_k` | int | `100` | Drug candidates per disease |
+| `--setup` | str? | — | Download data (`prime`/`optimus`/both) |
+| `--data_dir` | str | `~/.txoptimus` | Data directory override |
+
+## Output Files
+
+| File | Description |
+|:---|:---|
+| `{prefix}_{engine}_results.json` | Full metrics (AUROC, AUPRC, per-relation, graph profile) |
+| `{prefix}_{engine}_candidates.csv` | Top-K drug candidates ranked by score |
+| `{prefix}_comparison_report.md` | Side-by-side comparison (benchmark mode only) |
+
+## Citation
+
+If you use TxOptimus in your research, please cite the original TxGNN paper:
+
+```bibtex
+@article{huang2024txgnn,
+  title={Zero-shot prediction of therapeutic use with geometric deep learning and clinician centered design},
+  author={Huang, Kexin and Chandak, Payal and Wang, Qianwen and Haber, Shreyas and Zitnik, Marinka},
+  journal={Nature Medicine},
+  year={2024}
+}
+```
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+## Author
+
+**arsalanriaz**

txoptimus-0.1.0/environment.yml

@@ -0,0 +1,111 @@
+name: /media/pmlab/c2dd36be-37c8-481e-ac15-95767a75f66e/Tools_DB/txgnn/txgnn_env
+channels:
+  - defaults
+dependencies:
+  - _libgcc_mutex=0.1
+  - _openmp_mutex=5.1
+  - ca-certificates=2026.8.13
+  - ld_impl_linux-64=2.44
+  - libffi=3.4.8
+  - libgcc=15.2.0
+  - libgcc-ng=15.2.0
+  - libstdcxx=15.2.0
+  - libstdcxx-ng=15.2.0
+  - libxcb=1.17.0
+  - libzlib=1.3.2
+  - ncurses=6.6
+  - openssl=3.5.7
+  - pip=24.2
+  - pthread-stubs=0.3
+  - python=3.8.20
+  - readline=8.3
+  - setuptools=75.1.0
+  - sqlite=3.53.2
+  - tk=8.6.15
+  - wheel=0.44.0
+  - xorg-libx11=1.8.13
+  - xorg-libxau=1.0.12
+  - xorg-libxdmcp=1.1.5
+  - xorg-xorgproto=2025.1
+  - xz=5.8.2
+  - zlib=1.3.2
+  - pip:
+      - aiohappyeyeballs==2.4.4
+      - aiohttp==3.10.11
+      - aiosignal==1.3.1
+      - annotated-types==0.7.0
+      - async-timeout==5.0.1
+      - attrs==25.3.0
+      - certifi==2026.7.22
+      - charset-normalizer==3.5.1
+      - contourpy==1.1.1
+      - cycler==0.12.1
+      - dgl==2.4.0+cu121
+      - et-xmlfile==2.0.0
+      - filelock==3.16.1
+      - fonttools==4.57.0
+      - frozenlist==1.5.0
+      - fsspec==2025.3.0
+      - ftpretty==0.4.0
+      - goatools==1.6.5
+      - idna==3.15
+      - importlib-resources==6.4.5
+      - jinja2==3.1.6
+      - joblib==1.4.2
+      - kiwisolver==1.4.7
+      - markdown-it-py==3.0.0
+      - markupsafe==2.1.5
+      - matplotlib==3.7.5
+      - mdurl==0.1.2
+      - mpmath==1.3.0
+      - multidict==6.1.0
+      - networkx==3.1
+      - numpy==1.24.4
+      - nvidia-cublas-cu12==12.1.3.1
+      - nvidia-cuda-cupti-cu12==12.1.105
+      - nvidia-cuda-nvrtc-cu12==12.1.105
+      - nvidia-cuda-runtime-cu12==12.1.105
+      - nvidia-cudnn-cu12==9.1.0.70
+      - nvidia-cufft-cu12==11.0.2.54
+      - nvidia-curand-cu12==10.3.2.106
+      - nvidia-cusolver-cu12==11.4.5.107
+      - nvidia-cusparse-cu12==12.1.0.106
+      - nvidia-nccl-cu12==2.20.5
+      - nvidia-nvjitlink-cu12==12.9.86
+      - nvidia-nvtx-cu12==12.1.105
+      - openpyxl==3.1.5
+      - packaging==26.2
+      - pandas==2.0.3
+      - patsy==1.0.2
+      - pillow==10.4.0
+      - propcache==0.2.0
+      - psutil==7.2.2
+      - pydantic==2.10.6
+      - pydantic-core==2.27.2
+      - pydot==4.0.1
+      - pygments==2.19.2
+      - pyparsing==3.1.4
+      - python-dateutil==2.9.0.post0
+      - pytz==2026.3.post1
+      - pyyaml==6.0.3
+      - requests==2.32.4
+      - rich==14.3.4
+      - scikit-learn==1.3.2
+      - scipy==1.10.1
+      - six==1.17.0
+      - statsmodels==0.14.1
+      - sympy==1.13.3
+      - threadpoolctl==3.5.0
+      - torch==2.4.0
+      - torch-geometric==2.6.1
+      - tqdm==4.70.0
+      - triton==3.0.0
+      - txgnn==0.0.3
+      - typing-extensions==4.13.2
+      - tzdata==2026.3
+      - urllib3==2.2.3
+      - xlsxwriter==3.2.9
+      - yarl==1.15.2
+      - zipp==3.20.2
+prefix: 
+  /media/pmlab/c2dd36be-37c8-481e-ac15-95767a75f66e/Tools_DB/txgnn/txgnn_env

txoptimus-0.1.0/requirements.txt

@@ -0,0 +1,20 @@
+torch==2.4.0
+dgl==2.4.0
+torch-geometric==2.6.1
+numpy==1.24.4
+pandas==2.0.3
+scikit-learn==1.3.2
+scipy==1.10.1
+matplotlib==3.7.5
+tqdm==4.70.0
+requests==2.32.4
+transformers
+networkx==3.1
+pydantic==2.10.6
+PyYAML==6.0.3
+openpyxl==3.1.5
+xlsxwriter==3.2.9
+goatools==1.6.5
+statsmodels==0.14.1
+rich==14.3.4
+pillow==10.4.0

txoptimus-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

txoptimus-0.1.0/setup.py

@@ -0,0 +1,107 @@
+from setuptools import setup, find_packages
+from setuptools.command.install import install
+import sys
+
+
+class PostInstallCommand(install):
+    """Post-installation: display requirements banner and environment warning."""
+
+    def run(self):
+        install.run(self)
+        # Environment warning
+        if hasattr(sys, 'real_prefix') or (hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix):
+            env_type = "virtual environment"
+        else:
+            env_type = "system Python"
+
+        print("\n" + "=" * 60)
+        print(" TxOptimus v0.1.0 installed successfully!")
+        print("=" * 60)
+
+        if env_type == "system Python":
+            print("\n ⚠ WARNING: You are installing into your SYSTEM Python.")
+            print("   It is strongly recommended to install TxOptimus in a")
+            print("   separate virtual or conda environment to avoid")
+            print("   overwriting existing dependencies.")
+            print("\n   Create a dedicated environment:")
+            print("     conda create -n txoptimus python=3.8")
+            print("     conda activate txoptimus")
+            print("     pip install txoptimus")
+
+        print(f"\n   Detected environment: {env_type}")
+        print(f"   Python: {sys.version}")
+
+        print("""
+ REQUIREMENTS:
+   • RAM:     ≥32 GB (OptimusKG loads a 21.8M-edge graph)
+   • Storage: ≥8 GB free disk space for data files
+   • Python:  3.8+ (tested on 3.8.20)
+   • GPU:     Optional (CPU inference supported)
+
+ QUICK START:
+   1. Download data:  txoptimus --setup
+   2. Run inference:  txoptimus --engine optimus --diseases "oral cavity cancer"
+   3. Benchmark:      txoptimus --engine benchmark --diseases "oral cavity cancer"
+
+ For more details:  txoptimus --help
+""")
+        print("=" * 60 + "\n")
+
+
+with open("README.md", "r", encoding="utf-8") as f:
+    long_description = f.read()
+
+setup(
+    name='txoptimus',
+    version='0.1.0',
+    description='Zero-shot drug repurposing via TxGNN on PrimeKG and OptimusKG',
+    long_description=long_description,
+    long_description_content_type='text/markdown',
+    author='arsalanriaz',
+    url='https://github.com/arsalanriaz/txoptimus',
+    python_requires='>=3.8',
+    packages=find_packages(),
+    include_package_data=True,
+    install_requires=[
+        'torch==2.4.0',
+        'dgl==2.4.0',
+        'torch-geometric==2.6.1',
+        'numpy==1.24.4',
+        'pandas==2.0.3',
+        'scikit-learn==1.3.2',
+        'scipy==1.10.1',
+        'matplotlib==3.7.5',
+        'tqdm==4.70.0',
+        'requests==2.32.4',
+        'transformers',
+        'networkx==3.1',
+        'pydantic==2.10.6',
+        'PyYAML==6.0.3',
+        'openpyxl==3.1.5',
+        'xlsxwriter==3.2.9',
+        'goatools==1.6.5',
+        'statsmodels==0.14.1',
+        'rich==14.3.4',
+        'pillow==10.4.0',
+    ],
+    entry_points={
+        'console_scripts': [
+            'txoptimus=txoptimus.txoptimus:main',
+        ],
+    },
+    cmdclass={
+        'install': PostInstallCommand,
+    },
+    classifiers=[
+        'Development Status :: 3 - Alpha',
+        'Intended Audience :: Science/Research',
+        'Topic :: Scientific/Engineering :: Bio-Informatics',
+        'Topic :: Scientific/Engineering :: Artificial Intelligence',
+        'Programming Language :: Python :: 3.8',
+        'Programming Language :: Python :: 3.9',
+        'Programming Language :: Python :: 3.10',
+        'License :: OSI Approved :: MIT License',
+        'Operating System :: OS Independent',
+    ],
+    keywords='drug-repurposing zero-shot graph-neural-network knowledge-graph biomedical txgnn primekg optimuskg',
+)

txoptimus-0.1.0/txoptimus/__init__.py

@@ -0,0 +1,8 @@
+"""
+TxOptimus — Zero-shot drug repurposing via TxGNN on PrimeKG and OptimusKG.
+"""
+
+__version__ = "0.1.0"
+__author__ = "arsalanriaz"
+
+from .core import TxData, TxGNN, TxEval