https://github.com/althonos/pyjess
Cython bindings and Python interface to Jess, a 3D template matching software for protein structures.
https://github.com/althonos/pyjess
bioinformatics catalytic-site cython-wrapper enzyme pdb protein-structure python python-interface python-library
Last synced: 6 months ago
JSON representation
Cython bindings and Python interface to Jess, a 3D template matching software for protein structures.
- Host: GitHub
- URL: https://github.com/althonos/pyjess
- Owner: althonos
- License: mit
- Created: 2024-03-07T15:36:44.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-09T14:54:29.000Z (6 months ago)
- Last Synced: 2025-04-11T16:24:41.391Z (6 months ago)
- Topics: bioinformatics, catalytic-site, cython-wrapper, enzyme, pdb, protein-structure, python, python-interface, python-library
- Language: Cython
- Homepage:
- Size: 333 KB
- Stars: 8
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: COPYING
Awesome Lists containing this project
README
# 🐍🔍 PyJess [](https://github.com/althonos/pyjess/stargazers)
*[Cython](https://cython.org/) bindings and Python interface to [Jess](https://github.com/iriziotis/jess), a 3D template matching software.*
[](https://github.com/althonos/pyjess/actions)
[](https://codecov.io/gh/althonos/pyjess/)
[](https://choosealicense.com/licenses/mit/)
[](https://pypi.org/project/pyjess)
[](https://anaconda.org/bioconda/pyjess)
[](https://aur.archlinux.org/packages/python-pyjess)
[](https://pypi.org/project/pyjess/#files)
[](https://pypi.org/project/pyjess/#files)
[](https://pypi.org/project/pyjess/#files)
[](https://github.com/althonos/pyjess/)
[](https://git.lumc.nl/mflarralde/pyjess/)
[](https://github.com/althonos/pyjess/issues)
[](https://pyjess.readthedocs.io)
[](https://github.com/althonos/pyjess/blob/main/CHANGELOG.md)
[](https://pepy.tech/project/pyjess)
## 🗺️ Overview
Jess is an algorithm for constraint-based structural template matching
proposed by Jonathan Barker *et al.*[\[1\]](#ref1). It can be used to identify
catalytic residues from a known template inside a protein structure. Jess
is an evolution of TESS, a geometric hashing algorithm developed by
Andrew Wallace *et al.*[\[2\]](#ref2), removing some pre-computation and
structural requirements from the original algorithm. Jess was further
updated and maintained by [Ioannis Riziotis](https://github.com/iriziotis)
during his PhD in the [Thornton group](https://www.ebi.ac.uk/research/thornton/).
PyJess is a Python module that provides bindings to Jess using
[Cython](https://cython.org/). It allows creating templates, querying them
with protein structures, and retrieving the hits using a Python API without
performing any external I/O.
## 🔧 Installing
PyJess is available for all modern Python versions (3.7+).
It can be installed directly from [PyPI](https://pypi.org/project/pyjess/),
which hosts some pre-built x86-64 wheels for Linux, MacOS, and Windows,
as well as the code required to compile from source with Cython:
```console
$ pip install pyjess
```
Otherwise, PyJess is also available as a [Bioconda](https://bioconda.github.io/)
package:
```console
$ conda install -c bioconda pyjess
```
Check the [*install* page](https://pyjess.readthedocs.io/en/stable/install.html)
of the documentation for other ways to install PyJess on your machine.
## 🔖 Citation
PyJess is scientific software, and builds on top of Jess. Please cite
Jess if you are using it in an academic work, for instance as:
> PyJess, a Python library binding to Jess (Barker *et al.*, 2003).
## 💡 Example
Load templates to be used as references from different template files:
```python
import pathlib
import pyjess
templates = []
for path in sorted(pathlib.Path("vendor/jess/examples").glob("template_*.qry")):
with path.open() as file:
templates.append(pyjess.Template.load(file, id=path.stem))
```
Create a `Jess` instance and use it to query a molecule (a PDB structure)
against the stored templates:
```python
jess = pyjess.Jess(templates)
mol = pyjess.Molecule.load("vendor/jess/examples/test_pdbs/pdb1a0p.ent")
query = jess.query(mol, rmsd_threshold=2.0, distance_cutoff=3.0, max_dynamic_distance=3.0)
```
The hits are computed iteratively, and the different output statistics are
computed on-the-fly when requested:
```python
for hit in query:
print(hit.molecule.id, hit.template.id, hit.rmsd, hit.log_evalue)
for atom in hit.atoms():
print(atom.name, atom.x, atom.y, atom.z)
```
## 🧶 Thread-safety
Once a `Jess` instance has been created, the templates cannot be edited anymore,
making the `Jess.query` method re-entrant. This allows querying several
molecules against the same templates in parallel using a thread pool:
```python
molecules = []
for path in glob.glob("vendor/jess/examples/test_pdbs/*.ent"):
molecules.append(Molecule.load(path))
with multiprocessing.ThreadPool() as pool:
hits = pool.map(jess.query, molecules)
```
*⚠️ Prior to PyJess `v0.2.1`, the Jess code was running some thread-unsafe operations which have now been patched.
If running Jess in parallel, make sure to use `v0.2.1` or later to use the code patched with re-entrant functions*.
## 💭 Feedback
### ⚠️ Issue Tracker
Found a bug ? Have an enhancement request ? Head over to the [GitHub issue tracker](https://github.com/althonos/[pyjess]/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/pyjess/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/pyjess/blob/main/CHANGELOG.md)
in the [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) format.
## ⚖️ License
This library is provided under the [MIT License](https://choosealicense.com/licenses/mit/). The JESS code is distributed under the [MIT License](https://choosealicense.com/licenses/mit/) as well.
*This project is in no way not affiliated, sponsored, or otherwise endorsed
by the JESS authors. 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
- \[1\] Barker, J. A., & Thornton, J. M. (2003). An algorithm for constraint-based structural template matching: application to 3D templates with statistical analysis. Bioinformatics (Oxford, England), 19(13), 1644–1649. [doi:10.1093/bioinformatics/btg226](https://doi.org/10.1093/bioinformatics/btg226).
- \[2\] Wallace, A. C., Borkakoti, N., & Thornton, J. M. (1997). TESS: a geometric hashing algorithm for deriving 3D coordinate templates for searching structural databases. Application to enzyme active sites. Protein science : a publication of the Protein Society, 6(11), 2308–2323. [doi:10.1002/pro.5560061104](https://doi.org/10.1002/pro.5560061104).