molgraph

Name	molgraph JSON
Version	0.6.5 JSON
	download
home_page	https://github.com/akensert/molgraph
Summary	Graph Neural Networks for Molecular Machine Learning
upload_time	2024-02-09 14:18:08
maintainer
docs_url	None
author	Alexander Kensert
requires_python	>=3.10
license	MIT
keywords	graph-neural-networks deep-learning machine-learning molecular-machine-learning molecular-graphs graphs cheminformatics chemometrics bioinformatics chemistry biology biochemistry
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # MolGraph

**Graph Neural Networks** with **TensorFlow** and **Keras**. Focused on **Molecular Machine Learning**.

<img src="https://github.com/akensert/molgraph/blob/main/media/molgraph.jpg" alt="molgraph" width="800">

## Highlights

Build a Graph Neural Network with Keras' [Sequential](https://www.tensorflow.org/api_docs/python/tf/keras/Sequential) API:

```python
from molgraph import GraphTensor
from molgraph import layers
from tensorflow import keras

model = keras.Sequential([
    layers.GINConv(units=32),
    layers.GINConv(units=32),
    layers.Readout(),
    keras.layers.Dense(units=1),
])
output = model(
    GraphTensor(node_feature=[[4.], [2.]], edge_src=[0], edge_dst=[1])
)
```

## Paper
See [arXiv](https://arxiv.org/abs/2208.09944)

## Documentation
See [readthedocs](https://molgraph.readthedocs.io/en/latest/)

## Implementations

- **Graph tensor** ([GraphTensor](http://github.com/akensert/molgraph/tree/main/molgraph/tensors/graph_tensor.py))
    - A composite tensor holding graph data.
    - Has a ragged state (multiple graphs) and a non-ragged state (single disjoint graph).
    - Can conveniently go between both states (merge(), separate()).
    - Can propagate node states (features) based on edges (propagate()).
    - Can add, update and remove graph data (update(), remove()).
    - Compatible with TensorFlow's APIs (including Keras). For instance, graph data (encoded as a GraphTensor) can now seamlessly be used with keras.Sequential, keras.Functional, tf.data.Dataset, and tf.saved_model APIs.
- **Layers**
    - **Convolutional**
        - GCNConv ([GCNConv](http://github.com/akensert/molgraph/tree/main/molgraph/layers/convolutional/gcn_conv.py))
        - GINConv ([GINConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/convolutional/gin_conv.py))
        - GCNIIConv ([GCNIIConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/convolutional/gcnii_conv.py))
        - GraphSageConv ([GraphSageConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/convolutional/graph_sage_conv.py))
    - **Attentional**
        - GATConv ([GATConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/attentional/gat_conv.py))
        - GATv2Conv ([GATv2Conv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/attentional/gatv2_conv.py))
        - GTConv ([GTConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/attentional/gt_conv.py))
        - GMMConv ([GMMConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/attentional/gmm_conv.py))
        - GatedGCNConv ([GatedGCNConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/attentional/gated_gcn_conv.py))
        - AttentiveFPConv ([AttentiveFPConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/attentional/attentive_fp_conv.py))
    - **Message-passing**
        - MPNNConv ([MPNNConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/message_passing/mpnn_conv.py))
        - EdgeConv ([EdgeConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/message_passing/edge_conv.py))
    - **Distance-geometric**
        - DTNNConv ([DTNNConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/geometric/dtnn_conv.py))
        - GCFConv ([GCFConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/geometric/gcf_conv.py))
    - **Pre- and post-processing**
        - In addition to the aforementioned GNN layers, there are also several other layers which improves model-building. See [readout/](https://github.com/akensert/molgraph/tree/main/molgraph/layers/readout), [preprocessing/](https://github.com/akensert/molgraph/tree/main/molgraph/layers/preprocessing), [postprocessing/](https://github.com/akensert/molgraph/tree/main/molgraph/layers/postprocessing), [positional_encoding/](https://github.com/akensert/molgraph/tree/main/molgraph/layers/positional_encoding).
- **Models**
    - Although model building is easy with MolGraph, there are some built-in GNN [models](https://github.com/akensert/molgraph/tree/main/molgraph/models):
        - **GIN**
        - **MPNN**
        - **DMPNN**
    - And models for improved interpretability of GNNs:
        - **SaliencyMapping**
        - **IntegratedSaliencyMapping**
        - **SmoothGradSaliencyMapping**
        - **GradientActivationMapping** (Recommended)

## Requirements/dependencies
- **Python** (version ~= 3.10)
    - **TensorFlow** (version ~= 2.15.0)
    - **RDKit** (version ~= 2022.3.5)
    - **Pandas** (version ~= 1.0.3)
    - **IPython** (version ~= 8.12.0)

> MolGraph should work with the more recent TensorFlow and RDKit versions. If not, try installing earlier versions of TensorFlow and RDKit.

## Installation

For **GPU** users:
<pre>
pip install molgraph[gpu]
</pre>

For **CPU** users:
<pre>
pip install molgraph
</pre>

Now run your first program with **MolGraph**:

```python
from tensorflow import keras
from molgraph import chemistry
from molgraph import layers
from molgraph import models

# Obtain dataset, specifically ESOL
qm7 = chemistry.datasets.get('esol')

# Define molecular graph encoder
atom_encoder = chemistry.Featurizer([
    chemistry.features.Symbol(),
    chemistry.features.Hybridization(),
    # ...
])

bond_encoder = chemistry.Featurizer([
    chemistry.features.BondType(),
    # ...
])

encoder = chemistry.MolecularGraphEncoder(atom_encoder, bond_encoder)

# Obtain graphs and associated labels
x_train = encoder(qm7['train']['x'])
y_train = qm7['train']['y']

x_test = encoder(qm7['test']['x'])
y_test = qm7['test']['y']

# Build model via Keras API
gnn_model = keras.Sequential([
    layers.GATConv(units=32, name='gat_conv_1'),
    layers.GATConv(units=32, name='gat_conv_2'),
    layers.Readout(),
    keras.layers.Dense(units=1024, activation='relu'),
    keras.layers.Dense(units=y_train.shape[-1])
])

# Compile, fit and evaluate
gnn_model.compile(optimizer='adam', loss='mae')
gnn_model.fit(x_train, y_train, epochs=50)
scores = gnn_model.evaluate(x_test, y_test)

# Compute gradient activation maps
gam_model = models.GradientActivationMapping(
    model=gnn_model, layer_names=['gat_conv_1', 'gat_conv_2'])

maps = gam_model(x_train.separate())
```

## Changelog
For a detailed list of changes, see the [CHANGELOG.md](https://github.com/akensert/molgraph/blob/main/CHANGELOG.md).

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/akensert/molgraph",
    "name": "molgraph",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": "",
    "keywords": "graph-neural-networks,deep-learning,machine-learning,molecular-machine-learning,molecular-graphs,graphs,cheminformatics,chemometrics,bioinformatics,chemistry,biology,biochemistry",
    "author": "Alexander Kensert",
    "author_email": "alexander.kensert@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/63/98/d0955d28e9e05f29b3a5c0c8270ef08929c61dfb65f939873c79c7bda3d1/molgraph-0.6.5.tar.gz",
    "platform": null,
    "description": "# MolGraph\n\n**Graph Neural Networks** with **TensorFlow** and **Keras**. Focused on **Molecular Machine Learning**.\n\n<img src=\"https://github.com/akensert/molgraph/blob/main/media/molgraph.jpg\" alt=\"molgraph\" width=\"800\">\n\n## Highlights\n\nBuild a Graph Neural Network with Keras' [Sequential](https://www.tensorflow.org/api_docs/python/tf/keras/Sequential) API:\n\n```python\nfrom molgraph import GraphTensor\nfrom molgraph import layers\nfrom tensorflow import keras\n\nmodel = keras.Sequential([\n    layers.GINConv(units=32),\n    layers.GINConv(units=32),\n    layers.Readout(),\n    keras.layers.Dense(units=1),\n])\noutput = model(\n    GraphTensor(node_feature=[[4.], [2.]], edge_src=[0], edge_dst=[1])\n)\n```\n\n## Paper\nSee [arXiv](https://arxiv.org/abs/2208.09944)\n\n## Documentation\nSee [readthedocs](https://molgraph.readthedocs.io/en/latest/)\n\n## Implementations\n\n- **Graph tensor** ([GraphTensor](http://github.com/akensert/molgraph/tree/main/molgraph/tensors/graph_tensor.py))\n    - A composite tensor holding graph data.\n    - Has a ragged state (multiple graphs) and a non-ragged state (single disjoint graph).\n    - Can conveniently go between both states (merge(), separate()).\n    - Can propagate node states (features) based on edges (propagate()).\n    - Can add, update and remove graph data (update(), remove()).\n    - Compatible with TensorFlow's APIs (including Keras). For instance, graph data (encoded as a GraphTensor) can now seamlessly be used with keras.Sequential, keras.Functional, tf.data.Dataset, and tf.saved_model APIs.\n- **Layers**\n    - **Convolutional**\n        - GCNConv ([GCNConv](http://github.com/akensert/molgraph/tree/main/molgraph/layers/convolutional/gcn_conv.py))\n        - GINConv ([GINConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/convolutional/gin_conv.py))\n        - GCNIIConv ([GCNIIConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/convolutional/gcnii_conv.py))\n        - GraphSageConv ([GraphSageConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/convolutional/graph_sage_conv.py))\n    - **Attentional**\n        - GATConv ([GATConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/attentional/gat_conv.py))\n        - GATv2Conv ([GATv2Conv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/attentional/gatv2_conv.py))\n        - GTConv ([GTConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/attentional/gt_conv.py))\n        - GMMConv ([GMMConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/attentional/gmm_conv.py))\n        - GatedGCNConv ([GatedGCNConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/attentional/gated_gcn_conv.py))\n        - AttentiveFPConv ([AttentiveFPConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/attentional/attentive_fp_conv.py))\n    - **Message-passing**\n        - MPNNConv ([MPNNConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/message_passing/mpnn_conv.py))\n        - EdgeConv ([EdgeConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/message_passing/edge_conv.py))\n    - **Distance-geometric**\n        - DTNNConv ([DTNNConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/geometric/dtnn_conv.py))\n        - GCFConv ([GCFConv](https://github.com/akensert/molgraph/tree/main/molgraph/layers/geometric/gcf_conv.py))\n    - **Pre- and post-processing**\n        - In addition to the aforementioned GNN layers, there are also several other layers which improves model-building. See [readout/](https://github.com/akensert/molgraph/tree/main/molgraph/layers/readout), [preprocessing/](https://github.com/akensert/molgraph/tree/main/molgraph/layers/preprocessing), [postprocessing/](https://github.com/akensert/molgraph/tree/main/molgraph/layers/postprocessing), [positional_encoding/](https://github.com/akensert/molgraph/tree/main/molgraph/layers/positional_encoding).\n- **Models**\n    - Although model building is easy with MolGraph, there are some built-in GNN [models](https://github.com/akensert/molgraph/tree/main/molgraph/models):\n        - **GIN**\n        - **MPNN**\n        - **DMPNN**\n    - And models for improved interpretability of GNNs:\n        - **SaliencyMapping**\n        - **IntegratedSaliencyMapping**\n        - **SmoothGradSaliencyMapping**\n        - **GradientActivationMapping** (Recommended)\n\n## Requirements/dependencies\n- **Python** (version ~= 3.10)\n    - **TensorFlow** (version ~= 2.15.0)\n    - **RDKit** (version ~= 2022.3.5)\n    - **Pandas** (version ~= 1.0.3)\n    - **IPython** (version ~= 8.12.0)\n\n> MolGraph should work with the more recent TensorFlow and RDKit versions. If not, try installing earlier versions of TensorFlow and RDKit.\n\n## Installation\n\nFor **GPU** users:\n<pre>\npip install molgraph[gpu]\n</pre>\n\nFor **CPU** users:\n<pre>\npip install molgraph\n</pre>\n\nNow run your first program with **MolGraph**:\n\n```python\nfrom tensorflow import keras\nfrom molgraph import chemistry\nfrom molgraph import layers\nfrom molgraph import models\n\n# Obtain dataset, specifically ESOL\nqm7 = chemistry.datasets.get('esol')\n\n# Define molecular graph encoder\natom_encoder = chemistry.Featurizer([\n    chemistry.features.Symbol(),\n    chemistry.features.Hybridization(),\n    # ...\n])\n\nbond_encoder = chemistry.Featurizer([\n    chemistry.features.BondType(),\n    # ...\n])\n\nencoder = chemistry.MolecularGraphEncoder(atom_encoder, bond_encoder)\n\n# Obtain graphs and associated labels\nx_train = encoder(qm7['train']['x'])\ny_train = qm7['train']['y']\n\nx_test = encoder(qm7['test']['x'])\ny_test = qm7['test']['y']\n\n# Build model via Keras API\ngnn_model = keras.Sequential([\n    layers.GATConv(units=32, name='gat_conv_1'),\n    layers.GATConv(units=32, name='gat_conv_2'),\n    layers.Readout(),\n    keras.layers.Dense(units=1024, activation='relu'),\n    keras.layers.Dense(units=y_train.shape[-1])\n])\n\n# Compile, fit and evaluate\ngnn_model.compile(optimizer='adam', loss='mae')\ngnn_model.fit(x_train, y_train, epochs=50)\nscores = gnn_model.evaluate(x_test, y_test)\n\n# Compute gradient activation maps\ngam_model = models.GradientActivationMapping(\n    model=gnn_model, layer_names=['gat_conv_1', 'gat_conv_2'])\n\nmaps = gam_model(x_train.separate())\n```\n\n## Changelog\nFor a detailed list of changes, see the [CHANGELOG.md](https://github.com/akensert/molgraph/blob/main/CHANGELOG.md).\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Graph Neural Networks for Molecular Machine Learning",
    "version": "0.6.5",
    "project_urls": {
        "Homepage": "https://github.com/akensert/molgraph"
    },
    "split_keywords": [
        "graph-neural-networks",
        "deep-learning",
        "machine-learning",
        "molecular-machine-learning",
        "molecular-graphs",
        "graphs",
        "cheminformatics",
        "chemometrics",
        "bioinformatics",
        "chemistry",
        "biology",
        "biochemistry"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "da23e521768e871977dc58e52a7d1e70648110962580e0fe3cc06043bd2af1b1",
                "md5": "51b17c46d64d79affb3d8ee7bb2f702c",
                "sha256": "f35dcc2ea30c43be63246bc2f6f4891b30cebb125066e72de7cf5a5ef8ef732f"
            },
            "downloads": -1,
            "filename": "molgraph-0.6.5-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "51b17c46d64d79affb3d8ee7bb2f702c",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 197555,
            "upload_time": "2024-02-09T14:18:04",
            "upload_time_iso_8601": "2024-02-09T14:18:04.808094Z",
            "url": "https://files.pythonhosted.org/packages/da/23/e521768e871977dc58e52a7d1e70648110962580e0fe3cc06043bd2af1b1/molgraph-0.6.5-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "6398d0955d28e9e05f29b3a5c0c8270ef08929c61dfb65f939873c79c7bda3d1",
                "md5": "4eb025301cd2b120de31fa1825154e21",
                "sha256": "9096a60e87528c98c15ac05ee8ae5a8763bd1cc12604360f6323746245283eab"
            },
            "downloads": -1,
            "filename": "molgraph-0.6.5.tar.gz",
            "has_sig": false,
            "md5_digest": "4eb025301cd2b120de31fa1825154e21",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 110458,
            "upload_time": "2024-02-09T14:18:08",
            "upload_time_iso_8601": "2024-02-09T14:18:08.805041Z",
            "url": "https://files.pythonhosted.org/packages/63/98/d0955d28e9e05f29b3a5c0c8270ef08929c61dfb65f939873c79c7bda3d1/molgraph-0.6.5.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-02-09 14:18:08",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "akensert",
    "github_project": "molgraph",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "molgraph"
}