pyjess 0.5.2__cp313-cp313-macosx_11_0_arm64.whl → 0.6.0__cp313-cp313-macosx_11_0_arm64.whl

pyjess/_jess.pyi

@@ -221,4 +221,5 @@ class Jess(Generic[_T], Sequence[_T]):
         max_candidates: int = 1000,
         ignore_chain: bool = False,
         best_match: bool = False,
+        reorder: bool = True,
     ) -> Query[_T]: ...

pyjess/_jess.pyx

@@ -329,8 +329,9 @@ cdef class Atom:
                 atom metadata from.
 
         """
-        cdef bytearray b
-        cdef Atom      atom
+        cdef const unsigned char* s
+        cdef bytearray            b
+        cdef Atom                 atom
 
         if isinstance(text, str):
             b = bytearray(text, 'utf-8')
@@ -339,14 +340,15 @@ cdef class Atom:
         if not b.endswith(b'\n'):
             b.append(b'\n')
         b.append(b'\0')
+        s = b
 
         atom = cls.__new__(cls)
-        atom._atom = <_Atom*> malloc(sizeof(_Atom))
-        if atom._atom == NULL:
-            raise MemoryError("Failed to allocate atom")
-
-        if not jess.atom.Atom_parse(atom._atom, b):
-            raise ValueError(f"Failed to parse atom: {text!r}")
+        with nogil:
+            atom._atom = <_Atom*> malloc(sizeof(_Atom))
+            if atom._atom == NULL:
+                raise MemoryError("Failed to allocate atom")
+            if not jess.atom.Atom_parse(atom._atom, <const char*> s):
+                raise ValueError(f"Failed to parse atom: {text!r}")
 
         return atom
 
@@ -1582,6 +1584,7 @@ cdef class Jess:
         int max_candidates = 1000,
         bint ignore_chain = False,
         bint best_match = False,
+        bint reorder = True,
     ):
         """Scan for templates matching the given molecule.
 
@@ -1600,10 +1603,27 @@ cdef class Jess:
                 the atoms to match.
             best_match (`bool`): Pass `True` to return only the best match
                 to each template.
+            reorder (`bool`): Whether to enable template atom reordering
+                to accelerate matching in the scanner algorithm. Pass 
+                `False` to reverse to the original, slower algorithm
+                which matches atoms in the same order as they appear in
+                the template, at the cost
 
         Returns:
             `~pyjess.Query`: An iterator over the query hits.
 
+        Caution:
+            Since ``v0.6.0``, this function uses an optimized variant of
+            the Jess scanning algorithm which minimized the number of steps
+            needed to generate matches, by re-ordering the order the 
+            template atoms are iterated upon. Because of this change,
+            the query may return *exactly* the same matches but in an order 
+            that *differs* from the original Jess version. If you really
+            need results in the original order, set ``reorder`` to `False`.
+
+        .. versionadded:: 0.6.0
+            The ``reorder`` argument, defaulting to `True`.
+
         """
         cdef Query query = Query.__new__(Query)
         query.ignore_chain = ignore_chain
@@ -1617,5 +1637,6 @@ cdef class Jess:
             molecule._mol,
             distance_cutoff,
             max_dynamic_distance,
+            reorder,
         )
         return query

pyjess/tests/test_jess.py

@@ -204,7 +204,7 @@ class TestJess(unittest.TestCase):
             self.assertAlmostEqual(hit.log_evalue, -2.04, places=1)
 
     @unittest.skipUnless(files, "importlib.resources not available")
-    def test_mcsa_query(self):
+    def test_mcsa_query_no_reorder(self):
         with files(data).joinpath("1.3.3.tpl").open() as f:
             template = Template.load(f)
             jess = Jess([template])
@@ -213,7 +213,7 @@ class TestJess(unittest.TestCase):
         with files(data).joinpath("1AMY+1.3.3.txt").open() as f:
             results = list(filter(None, f.read().split("REMARK")))
 
-        hits = list(jess.query(molecule, 2, 4, 4))
+        hits = list(jess.query(molecule, 2, 4, 4, reorder=False))
         self.assertEqual(len(hits), len(results))
         for hit, block in zip(hits, results):
             self.assertIs(hit.template, template)
@@ -251,3 +251,63 @@ class TestJess(unittest.TestCase):
                 self.assertAlmostEqual(atom.occupancy, float(atom_line[55:61]), places=3)
                 self.assertAlmostEqual(atom.temperature_factor, float(atom_line[61:67]), places=3)
 
+    @unittest.skipUnless(files, "importlib.resources not available")
+    def test_mcsa_query_reorder(self):
+        with files(data).joinpath("1.3.3.tpl").open() as f:
+            template = Template.load(f)
+            jess = Jess([template])
+        with files(data).joinpath("1AMY.pdb").open() as f:
+            molecule = Molecule.load(f)
+        with files(data).joinpath("1AMY+1.3.3.txt").open() as f:
+            results = list(filter(None, f.read().split("REMARK")))
+
+        hits = list(jess.query(molecule, 2, 4, 4, reorder=True))
+        self.assertEqual(len(hits), len(results))
+
+        # `reorder=True` means that we may get results in a different order
+        # to Jess, so we need to match the hits in the file by residue number
+        # to make sure we compare them consistently.
+        
+        results_by_serials = {}
+        for block in results:
+            lines = block.strip().splitlines()
+            serials = tuple([ int(line.split()[1]) for line in lines[1:-1] ])
+            results_by_serials[serials] = block
+
+        for hit in hits:
+            self.assertIs(hit.template, template)
+            block = results_by_serials[tuple(atom.serial for atom in hit.atoms(False))]
+
+            lines = block.strip().splitlines()
+            query_id, rmsd, template_id, _, determinant, _, logE = lines[0].split()
+            self.assertEqual(query_id, "1AMY")
+            self.assertAlmostEqual(float(rmsd), hit.rmsd, places=3)
+            self.assertAlmostEqual(float(determinant), hit.determinant, places=1)
+            self.assertAlmostEqual(float(logE), hit.log_evalue, places=1)
+
+            atom_lines = lines[1:-1]
+            atoms = hit.atoms()
+            self.assertEqual(len(atoms), len(atom_lines))
+            for atom, atom_line in zip(atoms, atom_lines):
+                self.assertEqual(atom.serial, int(atom_line[7:12]))
+                self.assertEqual(atom.name, atom_line[13:17].strip())
+                self.assertEqual(atom.residue_name, atom_line[17:21].strip())
+                self.assertEqual(atom.chain_id, atom_line[21:23].strip())
+                self.assertEqual(atom.residue_number, int(atom_line[23:27]))
+                self.assertAlmostEqual(atom.x, float(atom_line[31:39]), places=3)
+                self.assertAlmostEqual(atom.y, float(atom_line[39:47]), places=3)
+                self.assertAlmostEqual(atom.z, float(atom_line[47:55]), places=3)
+                self.assertAlmostEqual(atom.occupancy, float(atom_line[55:61]), places=3)
+                self.assertAlmostEqual(atom.temperature_factor, float(atom_line[61:67]), places=3)
+
+            atoms = hit.atoms(transform=False)
+            self.assertEqual(len(atoms), len(atom_lines))
+            for atom, atom_line in zip(atoms, atom_lines):
+                self.assertEqual(atom.serial, int(atom_line[7:12]))
+                self.assertEqual(atom.name, atom_line[13:17].strip())
+                self.assertEqual(atom.residue_name, atom_line[17:21].strip())
+                self.assertEqual(atom.chain_id, atom_line[21:23].strip())
+                self.assertEqual(atom.residue_number, int(atom_line[23:27]))
+                self.assertAlmostEqual(atom.occupancy, float(atom_line[55:61]), places=3)
+                self.assertAlmostEqual(atom.temperature_factor, float(atom_line[61:67]), places=3)
+

{pyjess-0.5.2.dist-info → pyjess-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: pyjess
-Version: 0.5.2
+Version: 0.6.0
 Summary: Cython bindings and Python interface to JESS, a 3D template matching software.
 Keywords: bioinformatics,structure,template,matching
 Author-Email: Martin Larralde <martin.larralde@embl.de>
@@ -93,7 +93,9 @@ 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.
+performing any external I/O. It's also more than 10x faster than Jess thanks to
+[algorithmic optimizations](https://pyjess.readthedocs.io/en/latest/guide/optimizations.html)
+added to improve the original Jess code while producing consistent results.
 
 
 ## 🔧 Installing
@@ -127,7 +129,8 @@ Jess if you are using it in an academic work, for instance as:
 
 ## 💡 Example
 
-Load templates to be used as references from different template files:
+Load [`Template`](https://pyjess.readthedocs.io/en/latest/api/template.html#pyjess.Template) 
+objects to be used as references from different template files:
 
 ```python
 import pathlib
@@ -135,11 +138,10 @@ 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))
+    templates.append(pyjess.Template.load(path, id=path.stem))
 ```
 
-Create a `Jess` instance and use it to query a molecule (a PDB structure)
+Create a [`Jess`](https://pyjess.readthedocs.io/en/latest/api/jess.html#pyjess.Jess) instance and use it to query a [`Molecule`](https://pyjess.readthedocs.io/en/latest/api/molecule.html#pyjess.Molecule) (a PDB structure)
 against the stored templates:
 
 ```python
@@ -161,9 +163,11 @@ for hit in query:
 
 ## 🧶 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:
+Once a [`Jess`](https://pyjess.readthedocs.io/en/latest/api/jess.html#pyjess.Jess) 
+instance has been created, the templates cannot be edited anymore,
+making the [`Jess.query`](https://pyjess.readthedocs.io/en/latest/api/jess.html#pyjess.Jess.query) method re-entrant and thread-safe. This allows querying 
+several molecules against the same templates in parallel using e.g a 
+[`ThreadPool`](https://docs.python.org/3/library/multiprocessing.html#multiprocessing.pool.ThreadPool):
 
 ```python
 molecules = []
@@ -177,8 +181,22 @@ with multiprocessing.ThreadPool() as pool:
 *⚠️ 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*.
 
-<!-- ## ⏱️ Benchmarks -->
+## ⏱️ Benchmarks
 
+The following table reports the runtime of PyJess to match $n=132$ protein 
+structures to the $m=7607$ templates of 
+[EnzyMM](https://github.com/RayHackett/enzymm), using $J=12$ threads to parallelize.
+
+| Version     | Runtime (s) | Match Speed (N * M / s * J) | Speedup     |
+| ----------- | ----------- | --------------------------- | ----------- |
+| ``v0.4.2``  | 618.1       | 135.4                       | N/A         |
+| ``v0.5.0``  | 586.3       | 142.7                       | x1.05       |
+| ``v0.5.1``  | 365.6       | 228.9                       | x1.69       |
+| ``v0.5.2``  | 327.2       | 255.7                       | x1.88       |
+| ``v0.6.0``  | 54.5        | 1535.4                      | **x11.34**  |
+
+*Benchmarks were run on a quiet [i7-1255U](https://www.intel.com/content/www/us/en/products/sku/226259/intel-core-i71255u-processor-12m-cache-up-to-4-70-ghz/specifications.html) CPU running @4.70GHz with 10 physical cores / 12 logical
+cores.*
 
 ## 💭 Feedback
 
@@ -211,7 +229,7 @@ This library is provided under the [MIT License](https://choosealicense.com/lice
 *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
+at the [Leiden University Medical Center](https://www.lumc.nl/en/) in
 the [Zeller team](https://github.com/zellerlab).*
 
 

{pyjess-0.5.2.dist-info → pyjess-0.6.0.dist-info}/RECORD

@@ -1,20 +1,20 @@
-pyjess-0.5.2.dist-info/RECORD,,
-pyjess-0.5.2.dist-info/WHEEL,sha256=xL_I_TleH-YV9h3oMcQi1F0DSqA1tyOenDLO1uzk5E8,114
-pyjess-0.5.2.dist-info/METADATA,sha256=tsCMCW4Qh7vkECoA8aybf9sb0I8QTcdifZ7P7SDm1oI,11248
-pyjess-0.5.2.dist-info/licenses/COPYING,sha256=gLCfHtBLTrghVX7GkpmZqoozWMNN46502m_OUiYy01Y,1103
-pyjess/_jess.pyi,sha256=PhDo0l5LoYyLQPC2l-ZwyXKmyrC7y8T0i-yQYwcx--4,7015
+pyjess-0.6.0.dist-info/RECORD,,
+pyjess-0.6.0.dist-info/WHEEL,sha256=xL_I_TleH-YV9h3oMcQi1F0DSqA1tyOenDLO1uzk5E8,114
+pyjess-0.6.0.dist-info/METADATA,sha256=OG5zbwpmxVLSmlQQ6xvyicRYKB6JrLBkDa-zhmWa6js,12882
+pyjess-0.6.0.dist-info/licenses/COPYING,sha256=gLCfHtBLTrghVX7GkpmZqoozWMNN46502m_OUiYy01Y,1103
+pyjess/_jess.pyi,sha256=3FLL_E4q_fWlThfTwnas56zpdDFoN5z_xYD0aY-0-dk,7045
 pyjess/CMakeLists.txt,sha256=Oa0pniEQx9jXyFCJGyrswn9ahWSSVuW1madyeP6StoI,35
-pyjess/_jess.cpython-313-darwin.so,sha256=-TNSeSLkDrCyuEzaFTNXUuDyywCJRTdSwaolGy01O0U,367736
+pyjess/_jess.cpython-313-darwin.so,sha256=qFT8uG8RvbvbeELpaICQNnQhVaADGJB8UTIeNNMMqaM,368248
 pyjess/__init__.py,sha256=h4XXLdS4FnyVa-MBs_k3eZMG1jWxeiOJnwfBaJA9gyQ,745
 pyjess/.gitignore,sha256=uQBOufp4v50qn0aZKv6zbSo00cjfB-v9KySog7rlmIU,19
-pyjess/_jess.pyx,sha256=7fZoPrLnUBXmE9eCq1wiBBrbGIcuOxyn9Szbct-nBKw,51879
+pyjess/_jess.pyx,sha256=5qCasXyFa0e2BfhiFfx5Qlt7xiZeb7CFfwzfFgfVfTs,53007
 pyjess/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pyjess/tests/__init__.py,sha256=ka1wkfXesesZ3f6p5Dg55P4YYyS3R4gKRmhpQRtWVec,599
 pyjess/tests/test_molecule.py,sha256=RHBE0yL_j71nQOwXJ6t_PzkZi4BaFPY5Q0VwKWM6elk,5311
 pyjess/tests/utils.py,sha256=dsaphex7qomJCvSHWnVy79iYDPGiL59xqGAtRoVAeWc,196
 pyjess/tests/test_hit.py,sha256=qN0qcGWHdvM9PZzBLWwuORhAXaZLp9c-CuZgO3GAbr8,1212
 pyjess/tests/test_atom.py,sha256=omNznNbRXMDt2j1plAUlfWPGCfmtkYpj2jysEX1zQuY,4631
-pyjess/tests/test_jess.py,sha256=tEu0K2B2-zLEMPFgQ1wk7lXhsZuRDyMzm58crT6G_ZY,11363
+pyjess/tests/test_jess.py,sha256=qNXtgQ9IWJ0NH4MRhFPMQ54ocpLaxwJRP-0lZv_N0Ns,14710
 pyjess/tests/test_template.py,sha256=XMLELYRB4j7xavziZ-ntq15PjhNHNfJJkctUq9BkvEI,4541
 pyjess/tests/test_template_atom.py,sha256=s9tJ_SAgvKeGwbVjaTWY-EtsUeQp3eu4NF5ja3oO_84,3405
 pyjess/tests/data/pdb1lnb.pdb,sha256=E9Jjy4qQ75O1UKIXcVyVJHE1XDNx1Rb7ENPVrehW6N8,270054