# 🚀 `mini3di` [](https://github.com/althonos/mini3di/stargazers)
*A [NumPy](https://numpy.org/) port of the [`foldseek`](https://github.com/steineggerlab/foldseek) code for encoding structures to 3di.*
[](https://github.com/althonos/mini3di/actions)
[](https://codecov.io/gh/althonos/mini3di/)
[](https://choosealicense.com/licenses/gpl-3.0/)
[](https://pypi.org/project/mini3di)
[](https://anaconda.org/bioconda/mini3di)
[](https://pypi.org/project/mini3di/#files)
[](https://pypi.org/project/mini3di/#files)
[](https://pypi.org/project/mini3di/#files)
[](https://github.com/althonos/mini3di/)
[](https://git.embl.de/larralde/mini3di/)
[](https://github.com/althonos/mini3di/issues)
[](https://mini3di.readthedocs.io)
[](https://github.com/althonos/mini3di/blob/master/CHANGELOG.md)
[](https://pepy.tech/project/mini3di)
## 🗺️ Overview
[`foldseek`](https://github.com/steineggerlab/foldseek) is a method developed
by van Kempen *et al.*[\[1\]](#ref1) for the fast and accurate search of
protein structures. In order to search proteins structures at a large scale,
it first encodes the 3D structure into sequences over a structural alphabet,
3di, which captures tertiary amino acid interactions.
`mini3di` is a pure-Python package to encode 3D structures of proteins into
the 3di alphabet, using the trained weights from the `foldseek` VQ-VAE model.
This library only depends on NumPy and is available for all modern Python
versions (3.7+).
<!-- ### 📋 Features -->
## 🔧 Installing
Install the `mini3di` package directly from [PyPi](https://pypi.org/project/mini3di)
which hosts universal wheels that can be installed with `pip`:
```console
$ pip install mini3di
```
<!-- Otherwise, `mini3di` is also available as a [Bioconda](https://bioconda.github.io/)
package:
```console
$ conda install -c bioconda mini3di
``` -->
<!-- ## 📖 Documentation
A complete [API reference](https://mini3di.readthedocs.io/en/stable/api.html)
can be found in the [online documentation](https://mini3di.readthedocs.io/),
or directly from the command line using
[`pydoc`](https://docs.python.org/3/library/pydoc.html):
```console
$ pydoc mini3di
``` -->
## 💡 Example
`mini3di` provides a single `Encoder` class, which expects the 3D coordinates
of the **Cα**, **Cβ**, **N** and **C** atoms from each peptide residue. For
residues without **Cβ** (Gly), simply write the coordinates as `math.nan`.
Call the `encode_atoms` method to get a sequence of 3di states:
```python
from math import nan
import mini3di
encoder = mini3di.Encoder()
states = encoder.encode_atoms(
ca=[[32.9, 51.9, 28.8], [35.0, 51.9, 26.6], ...],
cb=[[ nan, nan, nan], [35.3, 53.3, 26.4], ...],
n=[ [32.1, 51.2, 29.8], [35.3, 51.5, 28.1], ...],
c=[ [34.4, 51.7, 29.1], [36.1, 51.1, 25.8], ...],
)
```
The states returned as output will be a NumPy array of state indices. To turn
it into a sequence, use the `build_sequence` method of the encoder:
```python
sequence = encoder.build_sequence(states)
print(sequence)
```
The encoder can work directly with Biopython objects, if Biopython is available.
A helper method `encode_chain` to extract the atom coordinates from
a [`Bio.PDB.Chain`](https://biopython.org/docs/latest/api/Bio.PDB.Chain.html)
and encoding them directly. For instance, to encode all the chains from a
[PDB file](https://en.wikipedia.org/wiki/Protein_Data_Bank_(file_format)):
```python
import pathlib
import mini3di
from Bio.PDB import PDBParser
encoder = mini3di.Encoder()
parser = PDBParser(QUIET=True)
struct = parser.get_structure("8crb", pathlib.Path("tests", "data", "8crb.pdb"))
for chain in struct.get_chains():
states = encoder.encode_chain(chain)
sequence = encoder.build_sequence(states)
print(chain.get_id(), sequence)
```
## 💭 Feedback
### ⚠️ Issue Tracker
Found a bug? Have an enhancement request? Head over to the [GitHub issue
tracker](https://github.com/althonos/mini3di/issues) if you need to report
or ask something. If you are filing in on a bug, please include as much
information as you can about the issue, and try to recreate the same bug
in a simple, easily reproducible situation.
### 🏗️ Contributing
Contributions are more than welcome! See
[`CONTRIBUTING.md`](https://github.com/althonos/mini3di/blob/main/CONTRIBUTING.md)
for more details.
## 📋 Changelog
This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html)
and provides a [changelog](https://github.com/althonos/mini3di/blob/master/CHANGELOG.md)
in the [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) format.
## ⚖️ License
This library is provided under the
[GNU General Public License v3.0](https://choosealicense.com/licenses/gpl-3.0/).
It includes some code ported from `foldseek`, which is licensed under the
[GNU General Public License v3.0](https://choosealicense.com/licenses/gpl-3.0/)
as well.
*This project is in no way not affiliated, sponsored, or otherwise endorsed
by the [original `foldseek` authors](https://github.com/steineggerlab).
It was developed by [Martin Larralde](https://github.com/althonos/) during his
PhD project at the [European Molecular Biology Laboratory](https://www.embl.de/)
in the [Zeller team](https://github.com/zellerlab).*
## 📚 References
- <a id="ref1">\[1\]</a> Kempen, Michel van, Stephanie S. Kim, Charlotte Tumescheit, Milot Mirdita, Jeongjae Lee, Cameron L. M. Gilchrist, Johannes Söding, and Martin Steinegger. ‘Fast and Accurate Protein Structure Search with Foldseek’. Nature Biotechnology, 8 May 2023, 1–4. [doi:10.1038/s41587-023-01773-0](https://doi.org/10.1038/s41587-023-01773-0).
Raw data
{
"_id": null,
"home_page": "https://github.com/althonos/mini3di",
"name": "mini3di",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "bioinformatics, protein, structure, foldseek, 3di",
"author": "Martin Larralde",
"author_email": "martin.larralde@embl.de",
"download_url": "https://files.pythonhosted.org/packages/01/0c/a7dee4a85e3e3000c52ee6dfc95846c1fe4ef1ad69707fab7bbca4ebc556/mini3di-0.1.1.tar.gz",
"platform": "posix",
"description": "# \ud83d\ude80 `mini3di` [](https://github.com/althonos/mini3di/stargazers)\n\n*A [NumPy](https://numpy.org/) port of the [`foldseek`](https://github.com/steineggerlab/foldseek) code for encoding structures to 3di.*\n\n[](https://github.com/althonos/mini3di/actions)\n[](https://codecov.io/gh/althonos/mini3di/)\n[](https://choosealicense.com/licenses/gpl-3.0/)\n[](https://pypi.org/project/mini3di)\n[](https://anaconda.org/bioconda/mini3di)\n[](https://pypi.org/project/mini3di/#files)\n[](https://pypi.org/project/mini3di/#files)\n[](https://pypi.org/project/mini3di/#files)\n[](https://github.com/althonos/mini3di/)\n[](https://git.embl.de/larralde/mini3di/)\n[](https://github.com/althonos/mini3di/issues)\n[](https://mini3di.readthedocs.io)\n[](https://github.com/althonos/mini3di/blob/master/CHANGELOG.md)\n[](https://pepy.tech/project/mini3di)\n\n## \ud83d\uddfa\ufe0f Overview\n\n[`foldseek`](https://github.com/steineggerlab/foldseek) is a method developed\nby van Kempen *et al.*[\\[1\\]](#ref1) for the fast and accurate search of\nprotein structures. In order to search proteins structures at a large scale,\nit first encodes the 3D structure into sequences over a structural alphabet,\n3di, which captures tertiary amino acid interactions.\n\n`mini3di` is a pure-Python package to encode 3D structures of proteins into\nthe 3di alphabet, using the trained weights from the `foldseek` VQ-VAE model.\n\nThis library only depends on NumPy and is available for all modern Python\nversions (3.7+).\n\n<!-- ### \ud83d\udccb Features -->\n\n\n## \ud83d\udd27 Installing\n\nInstall the `mini3di` package directly from [PyPi](https://pypi.org/project/mini3di)\nwhich hosts universal wheels that can be installed with `pip`:\n```console\n$ pip install mini3di\n```\n\n<!-- Otherwise, `mini3di` is also available as a [Bioconda](https://bioconda.github.io/)\npackage:\n```console\n$ conda install -c bioconda mini3di\n``` -->\n\n<!-- ## \ud83d\udcd6 Documentation\n\nA complete [API reference](https://mini3di.readthedocs.io/en/stable/api.html)\ncan be found in the [online documentation](https://mini3di.readthedocs.io/),\nor directly from the command line using\n[`pydoc`](https://docs.python.org/3/library/pydoc.html):\n```console\n$ pydoc mini3di\n``` -->\n\n## \ud83d\udca1 Example\n\n`mini3di` provides a single `Encoder` class, which expects the 3D coordinates\nof the **C\u03b1**, **C\u03b2**, **N** and **C** atoms from each peptide residue. For\nresidues without **C\u03b2** (Gly), simply write the coordinates as `math.nan`.\nCall the `encode_atoms` method to get a sequence of 3di states:\n```python\nfrom math import nan\nimport mini3di\n\nencoder = mini3di.Encoder()\nstates = encoder.encode_atoms(\n ca=[[32.9, 51.9, 28.8], [35.0, 51.9, 26.6], ...],\n cb=[[ nan, nan, nan], [35.3, 53.3, 26.4], ...],\n n=[ [32.1, 51.2, 29.8], [35.3, 51.5, 28.1], ...],\n c=[ [34.4, 51.7, 29.1], [36.1, 51.1, 25.8], ...],\n)\n```\n\nThe states returned as output will be a NumPy array of state indices. To turn\nit into a sequence, use the `build_sequence` method of the encoder:\n```python\nsequence = encoder.build_sequence(states)\nprint(sequence)\n```\n\nThe encoder can work directly with Biopython objects, if Biopython is available.\nA helper method `encode_chain` to extract the atom coordinates from\na [`Bio.PDB.Chain`](https://biopython.org/docs/latest/api/Bio.PDB.Chain.html)\nand encoding them directly. For instance, to encode all the chains from a\n[PDB file](https://en.wikipedia.org/wiki/Protein_Data_Bank_(file_format)):\n```python\nimport pathlib\n\nimport mini3di\nfrom Bio.PDB import PDBParser\n\nencoder = mini3di.Encoder()\nparser = PDBParser(QUIET=True)\nstruct = parser.get_structure(\"8crb\", pathlib.Path(\"tests\", \"data\", \"8crb.pdb\"))\n\nfor chain in struct.get_chains():\n states = encoder.encode_chain(chain)\n sequence = encoder.build_sequence(states)\n print(chain.get_id(), sequence)\n```\n\n## \ud83d\udcad Feedback\n\n### \u26a0\ufe0f Issue Tracker\n\nFound a bug? Have an enhancement request? Head over to the [GitHub issue\ntracker](https://github.com/althonos/mini3di/issues) if you need to report\nor ask something. If you are filing in on a bug, please include as much\ninformation as you can about the issue, and try to recreate the same bug\nin a simple, easily reproducible situation.\n\n### \ud83c\udfd7\ufe0f Contributing\n\nContributions are more than welcome! See\n[`CONTRIBUTING.md`](https://github.com/althonos/mini3di/blob/main/CONTRIBUTING.md)\nfor more details.\n\n## \ud83d\udccb Changelog\n\nThis project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html)\nand provides a [changelog](https://github.com/althonos/mini3di/blob/master/CHANGELOG.md)\nin the [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) format.\n\n## \u2696\ufe0f License\n\nThis library is provided under the\n[GNU General Public License v3.0](https://choosealicense.com/licenses/gpl-3.0/).\nIt includes some code ported from `foldseek`, which is licensed under the\n[GNU General Public License v3.0](https://choosealicense.com/licenses/gpl-3.0/)\nas well.\n\n*This project is in no way not affiliated, sponsored, or otherwise endorsed\nby the [original `foldseek` authors](https://github.com/steineggerlab).\nIt was developed by [Martin Larralde](https://github.com/althonos/) during his\nPhD project at the [European Molecular Biology Laboratory](https://www.embl.de/)\nin the [Zeller team](https://github.com/zellerlab).*\n\n\n## \ud83d\udcda References\n\n- <a id=\"ref1\">\\[1\\]</a> Kempen, Michel van, Stephanie S. Kim, Charlotte Tumescheit, Milot Mirdita, Jeongjae Lee, Cameron L. M. Gilchrist, Johannes S\u00f6ding, and Martin Steinegger. \u2018Fast and Accurate Protein Structure Search with Foldseek\u2019. Nature Biotechnology, 8 May 2023, 1\u20134. [doi:10.1038/s41587-023-01773-0](https://doi.org/10.1038/s41587-023-01773-0).\n",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "A NumPy port of the foldseek code for encoding structures to 3di.",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/althonos/mini3di/issues",
"Builds": "https://github.com/althonos/mini3di/actions",
"Changelog": "https://github.com/althonos/mini3di/blob/master/CHANGELOG.md",
"Coverage": "https://codecov.io/gh/althonos/mini3di/",
"Homepage": "https://github.com/althonos/mini3di",
"PyPI": "https://pypi.org/project/mini3di"
},
"split_keywords": [
"bioinformatics",
" protein",
" structure",
" foldseek",
" 3di"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "10a95a54ab91aa07389cf1a0d85a8e70c04e8c1951d375ef45d31ec51406aafa",
"md5": "706924227015b733297f2a40ef2c769f",
"sha256": "2bd2e49f4b82f94b9b4a3b50cf6330450f202acecc2e4a849b2e7980bbcf2361"
},
"downloads": -1,
"filename": "mini3di-0.1.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "706924227015b733297f2a40ef2c769f",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7",
"size": 25135,
"upload_time": "2024-05-10T14:56:47",
"upload_time_iso_8601": "2024-05-10T14:56:47.607659Z",
"url": "https://files.pythonhosted.org/packages/10/a9/5a54ab91aa07389cf1a0d85a8e70c04e8c1951d375ef45d31ec51406aafa/mini3di-0.1.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "010ca7dee4a85e3e3000c52ee6dfc95846c1fe4ef1ad69707fab7bbca4ebc556",
"md5": "6562a2cad809a2d63d1a56ba9ac1c122",
"sha256": "eb2673c073b3ddd6713e4d1931c1e129d3f64886486b8db0413eed4630f12cab"
},
"downloads": -1,
"filename": "mini3di-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "6562a2cad809a2d63d1a56ba9ac1c122",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 28656,
"upload_time": "2024-05-10T14:56:48",
"upload_time_iso_8601": "2024-05-10T14:56:48.641880Z",
"url": "https://files.pythonhosted.org/packages/01/0c/a7dee4a85e3e3000c52ee6dfc95846c1fe4ef1ad69707fab7bbca4ebc556/mini3di-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-10 14:56:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "althonos",
"github_project": "mini3di",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mini3di"
}
JSON
