# `cg-gnn`
`cg-gnn` (short for "Cell Graph - Graph Neural Networks") is a library to train a graph neural network model on graphs built out of cell spatial data to predict patient outcomes or any other y-variable you choose. This library is designed to be used with the [Spatial Profiling Toolbox (SPT)](https://github.com/nadeemlab/SPT), although independent functionality is also possible provided you can provide cell graphs in the same format as SPT [(as implemented in the `graphs` submodule)](https://github.com/nadeemlab/SPT/tree/main/spatialprofilingtoolbox/graphs).
In addition to standalone use, `cg-gnn` also serves as an example implementation of an SPT-compatible graph neural network pipeline, for open source developers to reference when building their own deep learning tools that use cell graphs created by SPT. The key features that have to be implemented are
1. model training and inference
2. cell-level importance score calculation
If the input and output schema is followed, your tool will be compatible with the SPT ecosystem, allowing users to easily integrate your tool into their SPT workflows and upload your model's results to an SPT database.
This library is a heavily modified version of [histocartography](https://github.com/BiomedSciAI/histocartography) and two of its applications, [hact-net](https://github.com/histocartography/hact-net) and [patho-quant-explainer](https://github.com/histocartography/patho-quant-explainer).
## Installation
### Using pip
In addition to installing via pip,
```
pip install cg-gnn
```
you must also install using the instructions on their websites,
* [pytorch](https://pytorch.org/get-started/locally/)
* [DGL](https://www.dgl.ai/pages/start.html)
* [CUDA](https://anaconda.org/nvidia/cudatoolkit) (optional but highly recommended if your machine supports it)
### From source
1. Clone this repository
2. Create a conda environment that can run this software using
```
conda env create -f environment.yml
```
### Docker
For convenience, Dockerized versions of this package are provided at [nadeemlab/spt-cg-gnn](https://hub.docker.com/repository/docker/nadeemlab/spt-cg-gnn/general). We recommend using the CUDA-enabled version, provided it will run on your machine.
## Quickstart
Use [`spt graphs extract` and `spt graphs generate-graphs`](https://github.com/nadeemlab/SPT/tree/main/spatialprofilingtoolbox/graphs) to create cell graphs from a SPT database instance that this python package can use.
This module includes two scripts that you can call from the command line, or you can use the modules directly in Python.
1. `cg-gnn-train` trains a graph neural network model on a set of cell graphs, saves the model to file, and updates the cell graphs it was trained on with cell-level importance-to-classification scores if an explainer model type is provided.
2. `cg-gnn-separability` calculates class separability metrics given a trained model and other metadata.
## Credits
As mentioned above, this repository is a heavily modified version of [the histocartography project](https://github.com/BiomedSciAI/histocartography) and two of its applications: [hact-net](https://github.com/histocartography/hact-net) and [patho-quant-explainer](https://github.com/histocartography/patho-quant-explainer). Specifically,
* Cell graph formatting, saving, and loading using DGL is patterned on how they were implemented in hact-net
* The neural network training and inference module is modified from the hact-net implementation for cell graphs
* Importance score and separability calculations are sourced from patho-quant-explainer
* The dependence on histocartography is indirect, through the functionality used by the above features
Due to dependency issues that arose when using the version of histocartography published on PyPI, we've chosen to copy and make slight updates to only the modules of histocartography used by the features supported in this library.
Raw data
{
"_id": null,
"home_page": "https://github.com/nadeemlab/cg-gnn",
"name": "cg-gnn",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "gnn,pathology,omics,single-cell,graph,network,deep-learning,machine-learning,cancer,predictive-modeling,predictive-medicine,precision-medicine,precision-oncology,precision-pathology,precision-health,precision-healthcare",
"author": "Carlin Liao",
"author_email": "liaoc2@mskcc.org",
"download_url": "https://files.pythonhosted.org/packages/28/a4/df71465e1534c320ed134a9a727cce5dee3ee8061aa560476b31c65bee59/cg_gnn-0.3.2.tar.gz",
"platform": null,
"description": "# `cg-gnn`\n\n`cg-gnn` (short for \"Cell Graph - Graph Neural Networks\") is a library to train a graph neural network model on graphs built out of cell spatial data to predict patient outcomes or any other y-variable you choose. This library is designed to be used with the [Spatial Profiling Toolbox (SPT)](https://github.com/nadeemlab/SPT), although independent functionality is also possible provided you can provide cell graphs in the same format as SPT [(as implemented in the `graphs` submodule)](https://github.com/nadeemlab/SPT/tree/main/spatialprofilingtoolbox/graphs).\n\nIn addition to standalone use, `cg-gnn` also serves as an example implementation of an SPT-compatible graph neural network pipeline, for open source developers to reference when building their own deep learning tools that use cell graphs created by SPT. The key features that have to be implemented are\n1. model training and inference\n2. cell-level importance score calculation\nIf the input and output schema is followed, your tool will be compatible with the SPT ecosystem, allowing users to easily integrate your tool into their SPT workflows and upload your model's results to an SPT database.\n\nThis library is a heavily modified version of [histocartography](https://github.com/BiomedSciAI/histocartography) and two of its applications, [hact-net](https://github.com/histocartography/hact-net) and [patho-quant-explainer](https://github.com/histocartography/patho-quant-explainer).\n\n## Installation\n\n### Using pip\n\nIn addition to installing via pip,\n```\npip install cg-gnn\n```\nyou must also install using the instructions on their websites,\n* [pytorch](https://pytorch.org/get-started/locally/)\n* [DGL](https://www.dgl.ai/pages/start.html)\n* [CUDA](https://anaconda.org/nvidia/cudatoolkit) (optional but highly recommended if your machine supports it)\n\n### From source\n\n1. Clone this repository\n2. Create a conda environment that can run this software using\n```\nconda env create -f environment.yml\n```\n\n### Docker\n\nFor convenience, Dockerized versions of this package are provided at [nadeemlab/spt-cg-gnn](https://hub.docker.com/repository/docker/nadeemlab/spt-cg-gnn/general). We recommend using the CUDA-enabled version, provided it will run on your machine.\n\n## Quickstart\n\nUse [`spt graphs extract` and `spt graphs generate-graphs`](https://github.com/nadeemlab/SPT/tree/main/spatialprofilingtoolbox/graphs) to create cell graphs from a SPT database instance that this python package can use.\n\nThis module includes two scripts that you can call from the command line, or you can use the modules directly in Python.\n1. `cg-gnn-train` trains a graph neural network model on a set of cell graphs, saves the model to file, and updates the cell graphs it was trained on with cell-level importance-to-classification scores if an explainer model type is provided.\n2. `cg-gnn-separability` calculates class separability metrics given a trained model and other metadata.\n\n## Credits\n\nAs mentioned above, this repository is a heavily modified version of [the histocartography project](https://github.com/BiomedSciAI/histocartography) and two of its applications: [hact-net](https://github.com/histocartography/hact-net) and [patho-quant-explainer](https://github.com/histocartography/patho-quant-explainer). Specifically,\n\n* Cell graph formatting, saving, and loading using DGL is patterned on how they were implemented in hact-net\n* The neural network training and inference module is modified from the hact-net implementation for cell graphs\n* Importance score and separability calculations are sourced from patho-quant-explainer\n* The dependence on histocartography is indirect, through the functionality used by the above features\n\nDue to dependency issues that arose when using the version of histocartography published on PyPI, we've chosen to copy and make slight updates to only the modules of histocartography used by the features supported in this library.\n",
"bugtrack_url": null,
"license": "AGPL-3.0-or-later",
"summary": "Train a graph neural network on cell graphs.",
"version": "0.3.2",
"project_urls": {
"Homepage": "https://github.com/nadeemlab/cg-gnn",
"Repository": "https://github.com/nadeemlab/cg-gnn"
},
"split_keywords": [
"gnn",
"pathology",
"omics",
"single-cell",
"graph",
"network",
"deep-learning",
"machine-learning",
"cancer",
"predictive-modeling",
"predictive-medicine",
"precision-medicine",
"precision-oncology",
"precision-pathology",
"precision-health",
"precision-healthcare"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1a447b92e2903f23c01d2013a3adcd5b472fb641bc208e83eef7d798ddc98989",
"md5": "5a0a10d33763345774468311123c5a42",
"sha256": "acd9db6c36f0bf86159ba70bfc67f42d524ac9ad9f76a71450d7610c4bac9b62"
},
"downloads": -1,
"filename": "cg_gnn-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5a0a10d33763345774468311123c5a42",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 59756,
"upload_time": "2024-01-18T22:38:39",
"upload_time_iso_8601": "2024-01-18T22:38:39.062299Z",
"url": "https://files.pythonhosted.org/packages/1a/44/7b92e2903f23c01d2013a3adcd5b472fb641bc208e83eef7d798ddc98989/cg_gnn-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "28a4df71465e1534c320ed134a9a727cce5dee3ee8061aa560476b31c65bee59",
"md5": "97c515d392ef29d9bebdb7bf66ee1cae",
"sha256": "7901e44caddd7fc0275124f9f3a3c8f9a02bc4e3b629e655227149261848e27f"
},
"downloads": -1,
"filename": "cg_gnn-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "97c515d392ef29d9bebdb7bf66ee1cae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 49658,
"upload_time": "2024-01-18T22:38:40",
"upload_time_iso_8601": "2024-01-18T22:38:40.759692Z",
"url": "https://files.pythonhosted.org/packages/28/a4/df71465e1534c320ed134a9a727cce5dee3ee8061aa560476b31c65bee59/cg_gnn-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-18 22:38:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nadeemlab",
"github_project": "cg-gnn",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cg-gnn"
}
JSON
