| # Combinatorial prediction of therapeutic perturbations using causally-inspired neural networks |
| [](https://zitniklab.hms.harvard.edu/projects/PDGrapher/) [](https://github.com/mims-harvard/PDGrapher) [](https://www.biorxiv.org/content/10.1101/2024.01.03.573985v5) [](https://www.nature.com/articles/s41551-025-01481-x) [](https://github.com/mims-harvard/PDGrapher/tree/main/data)  |
|
|
|
|
|
|
| [Guadalupe Gonzalez*](https://www.guadalupegonzalez.io/), [Xiang Lin*](https://xianglin226.github.io/), [Isuru Herath](https://scholar.google.com/citations?user=F-RC5k0AAAAJ&hl=en), [Kirill Veselkov](https://scholar.google.com/citations?user=0n-5UGYAAAAJ&hl=en), |
| [Michael Bronstein](https://scholar.google.com/citations?user=UU3N6-UAAAAJ&hl=en), and [Marinka Zitnik](https://dbmi.hms.harvard.edu/people/marinka-zitnik) |
|
|
|  |
| ## Project structure |
|
|
| The project consists of next folders: |
| - [data](data/) contains all of the data on which our models were built. On how to obtain this data, refer to [Data](#data) section, |
| - [docs](docs/) contains documentation, built with 'sphinx', |
| - [src/pdgrapher](src/pdgrapher/) contains the source code for PDGrapher, |
| - [tests](tests/) contains unit and integration tests. |
|
|
| ## Virtual environment |
|
|
| ``` |
| conda env create -f conda-env.yml |
| conda activate pdgrapher |
| pip install pip==23.2.1 |
| pip install -r requirements.txt |
| |
| pip install torch==1.10.1+cu111 torchvision==0.11.2+cu111 torchaudio==0.10.1 -f https://download.pytorch.org/whl/cu111/torch_stable.html |
| pip install torch-scatter==2.0.9 -f https://data.pyg.org/whl/torch-1.10.1+cu111.html |
| pip install torch-sparse==0.6.12 -f https://data.pyg.org/whl/torch-1.10.1+cu111.html |
| pip install torch-cluster==1.5.9 -f https://data.pyg.org/whl/torch-1.10.1+cu111.html |
| pip install torch-spline-conv==1.2.1 -f https://data.pyg.org/whl/torch-1.10.1+cu111.html |
| pip install torch-geometric==2.0.4 -f https://data.pyg.org/whl/torch-1.10.1+cu111.html |
| pip install torchmetrics==0.9.3 |
| pip install lightning==1.9.5 |
| |
| ``` |
|
|
|
|
| ## Data |
|
|
| For processed data, download the compressed folders and place them in `data/processed/` with the following commands: |
|
|
| ### Download genetic and splits data from Zenodo |
| ```bash |
| cd data/processed |
| # Download splits and genetic data |
| wget -O splits.tar.gz "https://zenodo.org/api/records/15375990/files/splits.tar.gz/content" |
| wget -O torch_data_genetic.tar.gz "https://zenodo.org/api/records/15375990/files/torch_data_genetic.tar.gz/content" |
| |
| # Extract splits data |
| tar -xzvf splits.tar.gz |
| |
| # Create torch_data directory and extract genetic data into it |
| mkdir -p torch_data |
| cd torch_data |
| tar -xzvf ../torch_data_genetic.tar.gz |
| cd .. |
| ``` |
|
|
| ### Download chemical data from Zenodo |
| ```bash |
| # Download chemical data (run from data/processed directory) |
| wget -O torch_data_chemical.tar.gz "https://zenodo.org/api/records/15390483/files/torch_data_chemical.tar.gz/content" |
| |
| # Extract chemical torch data into torch_data directory |
| cd torch_data |
| tar -xzvf ../torch_data_chemical.tar.gz |
| cd .. |
| ``` |
|
|
| ### Data Sources |
| - **Genetic data and splits**: [https://zenodo.org/records/15375990](https://zenodo.org/records/15375990) |
| - **Chemical data**: [https://zenodo.org/records/15390483](https://zenodo.org/records/15390483) |
|
|
|
|
| ## Building |
|
|
| This project can be build as a Python library by running `pip install -e .` in the root of this repository. |
|
|
|
|
| ## Documentation |
|
|
| Documentation can be built with the following commands: |
|
|
| ### Prerequisites |
| First, install the required documentation dependencies: |
| ```bash |
| pip install myst-parser |
| ``` |
|
|
| ### Build Documentation |
| 1. `sphinx-apidoc -fe -o docs/source/ src/pdgrapher/` updates the source files from which the documentation is built |
| 2. `cd docs && make html` builds the documentation |
|
|
| Then, the documentation can be accessed locally by going to `docs/build/html/index.html` |
| All of the settings along with links to instructions can be found and modified in [docs/source/conf.py](docs/source/conf.py). |
|
|
| ## Notebooks |
| | Tutorials | Links | |
| |----------------|---------------------------------| |
| | Train PDGrapher on chemical dataset | [notebook](./notebooks/train_chemical.ipynb) | |
| | Train PDGrapher on genetic dataset | [notebook](./notebooks/train_genetic.ipynb) | |
| | Test PDGrapher on chemical/genetic dataset | [notebook](./notebooks/test_PDG.ipynb) | |
|
|
| ## Additional Resources |
| * [Paper](https://www.nature.com/articles/s41551-025-01481-x) |
| * [HMS News & Research](https://hms.harvard.edu/news/new-ai-tool-pinpoints-genes-drug-combos-restore-health-diseased-cells) |
|
|
| @article{gonzalez2025combinatorial, |
| title={Combinatorial Prediction of Therapeutic Perturbations Using Causally-Inspired Neural Networks}, |
| author={Gonzalez, Guadalupe and Lin, Xiang and Herath, Isuru and Veselkov, Kirill and Bronstein, Michael and Zitnik, Marinka}, |
| journal={Nature Biomedical Engineering}, |
| url={https://www.nature.com/articles/s41551-025-01481-x}, |
| year={2025} |
| } |
|
|
| ## License |
| The code in this package is licensed under the MIT License. |
|
|
| ## Questions |
| Please leave a Github issue or contact [Guadalupe Gonzalez](mailto:ggonzalezp16@gmail.com), [Xiang Lin](mailto:xianglin226@gmail.com), or [Marinka Zitnik](mailto:marinka@zitnik.si) |
|
|
|
|
