pyjess 0.7.0a2__tar.gz → 0.7.0a3__tar.gz

{pyjess-0.7.0a2 → pyjess-0.7.0a3}/CHANGELOG.md

@@ -6,7 +6,18 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 
 ## [Unreleased]
-[Unreleased]: https://github.com/althonos/pyjess/compare/v0.7.0-alpha.2...HEAD
+[Unreleased]: https://github.com/althonos/pyjess/compare/v0.7.0-alpha.3...HEAD
+
+
+## [v0.7.0-alpha.3] - 2025-09-03
+[v0.7.0-alpha.3]: https://github.com/althonos/pyjess/compare/v0.7.0-alpha.2...v0.7.0-alpha.3
+
+### Added
+- Support for parsing `Molecule` objects from CIF files using [`gemmi`](https://gemmi.readthedocs.io/).
+
+### Changed
+- **breaking**: Make `id` and `ignore_endmdl` arguments of `Molecule.load` and `Molecule.loads` keyword-only.
+- Make `altloc` and `insertion_code` arguments of `Atom` optional.
 
 
 ## [v0.7.0-alpha.2] - 2025-09-02

{pyjess-0.7.0a2 → pyjess-0.7.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: pyjess
-Version: 0.7.0a2
+Version: 0.7.0a3
 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>
@@ -56,6 +56,8 @@ Project-URL: PiWheels, https://piwheels.org/project/pyjess/
 Requires-Python: >=3.7
 Provides-Extra: test
 Requires-Dist: importlib-resources; python_version < "3.9" and extra == "test"
+Provides-Extra: cif
+Requires-Dist: gemmi~=0.7.0; extra == "cif"
 Description-Content-Type: text/markdown
 
 # 🐍🔍 PyJess [![Stars](https://img.shields.io/github/stars/althonos/pyjess.svg?style=social&maxAge=3600&label=Star)](https://github.com/althonos/pyjess/stargazers)
@@ -115,7 +117,7 @@ package:
 $ conda install -c bioconda pyjess
 ```
 
-Check the [*install* page](https://pyjess.readthedocs.io/en/stable/install.html)
+Check the [*install* page](https://pyjess.readthedocs.io/en/stable/guide/install.html)
 of the documentation for other ways to install PyJess on your machine.
 
 
@@ -183,9 +185,9 @@ If running Jess in parallel, make sure to use `v0.2.1` or later to use the code
 
 ## ⏱️ 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.
+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     |
 | ----------- | ----------- | --------------------------- | ----------- |
@@ -196,8 +198,8 @@ structures to the $m=7607$ templates of
 | ``v0.6.0``  | 54.5        | 1535.4                      | x11.34      |
 | ``v0.7.0``  | 52.4        | 1597.5                      | **x11.80**  |
 
-*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.*
+*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
 

{pyjess-0.7.0a2 → pyjess-0.7.0a3}/README.md

@@ -55,7 +55,7 @@ package:
 $ conda install -c bioconda pyjess
 ```
 
-Check the [*install* page](https://pyjess.readthedocs.io/en/stable/install.html)
+Check the [*install* page](https://pyjess.readthedocs.io/en/stable/guide/install.html)
 of the documentation for other ways to install PyJess on your machine.
 
 
@@ -123,9 +123,9 @@ If running Jess in parallel, make sure to use `v0.2.1` or later to use the code
 
 ## ⏱️ 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.
+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     |
 | ----------- | ----------- | --------------------------- | ----------- |
@@ -136,8 +136,8 @@ structures to the $m=7607$ templates of
 | ``v0.6.0``  | 54.5        | 1535.4                      | x11.34      |
 | ``v0.7.0``  | 52.4        | 1597.5                      | **x11.80**  |
 
-*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.*
+*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
 

{pyjess-0.7.0a2 → pyjess-0.7.0a3}/include/jess/atom.pxd

@@ -10,8 +10,8 @@ cdef extern from "Atom.h" nogil:
         int resSeq
         char iCode
         double[3] x
-        double occupancy
-        double tempFactor
+        float occupancy
+        float tempFactor
         char[4] segID
         char[3] element
         int charge

pyjess-0.7.0a3/patches/Atom.c.patch

@@ -0,0 +1,13 @@
+diff --git a/src/Atom.c b/src/Atom.c
+index ab602d7..6285beb 100644
+--- a/src/Atom.c
++++ b/src/Atom.c
+@@ -25,7 +25,7 @@ static void Atom_copyToken(char *d,const char *s,int n)
+ 	d[n]=0;
+ 	for(i=0; i<n; i++)
+ 	{
+-		if(isspace(d[i])) d[i]='_';
++		if(isspace(d[i]) || !d[i]) d[i]='_';
+ 	}
+ }
+ 

{pyjess-0.7.0a2 → pyjess-0.7.0a3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "pyjess"
-version = "0.7.0-alpha.2"
+version = "0.7.0-alpha.3"
 description = "Cython bindings and Python interface to JESS, a 3D template matching software."
 readme = "README.md"
 requires-python = ">=3.7"
@@ -47,6 +47,7 @@ classifiers = [
 
 [project.optional-dependencies]
 test = ["importlib-resources ; python_version < '3.9'"]
+cif = ["gemmi ~=0.7.0"]
 
 [tool.scikit-build]
 build-dir = "build/{build_type}"

{pyjess-0.7.0a2 → pyjess-0.7.0a3}/src/pyjess/_jess.pyi

@@ -17,9 +17,25 @@ __version__: str
 
 class Molecule(Sequence[Atom]):
     @classmethod
-    def load(cls, file: Union[TextIO, str, os.PathLike[str]], id: Optional[str] = None, ignore_endmdl: bool = False) -> Molecule: ...
+    def load(
+        cls,
+        file: Union[TextIO, str, os.PathLike[str]],
+        format: Literal["pdb", "cif"] = "pdb",
+        *,
+        id: Optional[str] = None,
+        ignore_endmdl: bool = False,
+        use_author: bool = False,
+    ) -> Molecule: ...
     @classmethod
-    def loads(cls, text: str, id: Optional[str] = None, ignore_endmdl: bool = False) -> Molecule: ...
+    def loads(
+        cls,
+        text: str,
+        format: Literal["pdb", "cif"] = "pdb",
+        *,
+        id: Optional[str] = None,
+        ignore_endmdl: bool = False,
+        use_author: bool = False,
+    ) -> Molecule: ...
     def __init__(self, atoms: Sequence[Atom] = (), id: Optional[str] = None): ...
     def __len__(self) -> int: ...
     @typing.overload
@@ -47,16 +63,16 @@ class Atom:
         *,
         serial: int,
         name: str,
-        altloc: str,
         residue_name: str,
         chain_id: str,
         residue_number: int,
-        insertion_code: str,
         x: float,
         y: float,
         z: float,
         occupancy: float = 0.0,
         temperature_factor: float = 0.0,
+        altloc: str = " ",
+        insertion_code: str = " ",
         segment: str = "",
         element: str = "",
         charge: int = 0,

{pyjess-0.7.0a2 → pyjess-0.7.0a3}/src/pyjess/_jess.pyx

@@ -70,6 +70,111 @@ def nullcontext(return_value=None):
 
 # --- Classes ----------------------------------------------------------------
 
+cdef class _MoleculeParser:
+    cdef str id
+
+    def __init__(self, str id = None):
+        self.id = id
+
+cdef class _PDBMoleculeParser(_MoleculeParser):
+    cdef bint ignore_endmdl
+
+    def __init__(self, str id = None, bint ignore_endmdl = False):
+        super().__init__(id=id)
+        self.ignore_endmdl = ignore_endmdl
+
+    def loads(self, text, molecule_type):
+        return self.load(io.StringIO(text), molecule_type)
+
+    def load(self, file, molecule_type):
+        cdef str id = self.id
+        try:
+            handle = open(file)
+        except TypeError:
+            handle = nullcontext(file)
+        with handle as f:
+            atoms = []
+            for line in f:
+                if line.startswith("HEADER"):
+                    if id is None:
+                        id = line[62:66].strip() or None
+                elif line.startswith(("ATOM", "HETATM")):
+                    atoms.append(Atom.loads(line))
+                elif line.startswith("ENDMDL"):
+                    if not self.ignore_endmdl:
+                        break
+        return molecule_type(atoms, id=id)
+
+
+cdef class _CIFMoleculeParser(_MoleculeParser):
+    cdef object gemmi
+    cdef bint use_author
+
+    _PRIMARY_COLUMNS = [
+        'id', 'type_symbol', 'label_atom_id', 'label_alt_id', 'label_comp_id',
+        'label_asym_id', 'label_seq_id', '?pdbx_PDB_ins_code', 'Cartn_x',
+        'Cartn_y', 'Cartn_z', 'occupancy', 'B_iso_or_equiv',
+        '?pdbx_formal_charge', '?group_PDB',
+    ]
+
+    _AUTH_COLUMNS = [
+        'id', 'type_symbol', 'auth_atom_id', 'label_alt_id', 'auth_comp_id',
+        'auth_asym_id', 'auth_seq_id', '?pdbx_PDB_ins_code', 'Cartn_x',
+        'Cartn_y', 'Cartn_z', 'occupancy', 'B_iso_or_equiv',
+        '?pdbx_formal_charge', '?group_PDB',
+    ]
+
+    def __init__(self, str id = None, bint use_author = False):
+        super().__init__(id=id)
+        self.gemmi = __import__('gemmi')
+        self.use_author = use_author
+
+    def _load_block(self, document, molecule_type):
+        block = document.sole_block()
+        cols = self._AUTH_COLUMNS if self.use_author else self._PRIMARY_COLUMNS
+        table = block.find('_atom_site.', cols)
+
+        if not table:
+            raise ValueError("missing columns in CIF files")
+
+        atoms = []
+        for row in table:
+            if table.has_column(14) and row[14] != "ATOM":
+                continue
+            atom = Atom(
+                serial=int(row[0]),
+                element=row[1],
+                name=row[2],
+                altloc=' ' if row[3] == "." else row[3], # FIXME: replace with None?
+                residue_name=row[4],
+                chain_id=row[5],
+                residue_number=int(row[6]),
+                insertion_code=' ' if not row.has(7) or row[7] == "?" else row[7],
+                x=float(row[8]),
+                y=float(row[9]),
+                z=float(row[10]),
+                occupancy=float(row[11]),
+                temperature_factor=float(row[12]),
+                # str segment = '', # FIXME?
+                charge=0 if not row.has(13) or row[13] == "?" else int(row[13]),
+            )
+            atoms.append(atom)
+
+        id = block.name if self.id is None else self.id
+        return molecule_type(atoms, id=id)
+
+    def loads(self, text, molecule_type):
+        document = self.gemmi.cif.read_string(text)
+        return self._load_block(document, molecule_type)
+
+    def load(self, file, molecule_type):
+        if hasattr(file, "read"):
+            document = self.gemmi.cif.read_string(file.read())
+        else:
+            document = self.gemmi.cif.read_file(file)
+        return self._load_block(document, molecule_type)
+
+
 cdef class Molecule:
     """A molecule structure, as a sequence of `Atom` objects.
 
@@ -84,20 +189,31 @@ cdef class Molecule:
     cdef str        _id
 
     @classmethod
-    def loads(cls, text, str id = None, bint ignore_endmdl = False):
+    def loads(cls, text, str format = "pdb", *, str id = None, bint ignore_endmdl = False):
         """Load a molecule from a PDB string.
 
         Arguments:
             file (`str`, `os.PathLike`, or file-like object): Either the path
                 to a file, or a file-like object opened in **text mode**
-                containing a PDB molecule.
+                containing a molecule.
+            format (`str`): The format to parse the file. Supported formats
+                are: ``pdb`` for the Protein Data Bank format, or ``cif``
+                for Crystallographic Information File format (additionally
+                requires the `gemmi` module).
+
+        Keyword Arguments:
             id (`str`, optional): The identifier of the molecule. If `None`
                 given, the parser will attempt to extract it from the
-                ``HEADER`` line.
+                ``HEADER`` line (for PDB files) or the block name (for CIF
+                files).
             ignore_endmdl (`bool`): Pass `True` to make the parser read all
                 the atoms from the PDB file. By default, the parser only
                 reads the atoms of the first model, and stops at the first
-                ``ENDMDL`` line.
+                ``ENDMDL`` line. *Ignored for CIF files.*
+            use_author (`bool`): Pass `True` to use the author-defined
+                labels while parsing CIF files, e.g. read the chain name
+                from ``_atom_site.auth_asym_id`` rather than
+                ``_atom_site.label_asym_id``.
 
         Returns:
             `~pyjess.Molecule`: The molecule parsed from the PDB file.
@@ -106,45 +222,61 @@ cdef class Molecule:
             `Molecule.load` to load a PDB molecule from a file-like
             object or from a path.
 
+        .. versionadded:: 0.7.0
+            The ``format`` argument, and support for CIF parsing.
+
         """
         return cls.load(io.StringIO(text), id=id, ignore_endmdl=ignore_endmdl)
 
     @classmethod
-    def load(cls, file, str id = None, bint ignore_endmdl = False):
+    def load(
+        cls,
+        file, str format = "pdb",
+        *,
+        str id = None,
+        bint ignore_endmdl = False,
+        bint use_author = False,
+    ):
         """Load a molecule from a PDB file.
 
         Arguments:
             file (`str`, `os.PathLike`, or file-like object): Either the path
                 to a file, or a file-like object opened in **text mode**
-                containing a PDB molecule.
+                containing a molecule.
+            format (`str`): The format to parse the file. Supported formats
+                are: ``pdb`` for the Protein Data Bank format, or ``cif``
+                for Crystallographic Information File format (additionally
+                requires the `gemmi` module).
+
+        Keyword Arguments:
             id (`str`, optional): The identifier of the molecule. If `None`
                 given, the parser will attempt to extract it from the
-                ``HEADER`` line.
+                ``HEADER`` line (for PDB files) or the block name (for CIF
+                files).
             ignore_endmdl (`bool`): Pass `True` to make the parser read all
                 the atoms from the PDB file. By default, the parser only
                 reads the atoms of the first model, and stops at the first
-                ``ENDMDL`` line.
+                ``ENDMDL`` line. *Ignored for CIF files.*
+            use_author (`bool`): Pass `True` to use the author-defined
+                labels while parsing CIF files, e.g. read the chain name
+                from ``_atom_site.auth_asym_id`` rather than
+                ``_atom_site.label_asym_id``.
 
         Returns:
             `~pyjess.Molecule`: The molecule parsed from the PDB file.
 
+        .. versionadded:: 0.7.0
+            The ``format`` argument, and support for CIF parsing.
+
         """
-        try:
-            handle = open(file)
-        except TypeError:
-            handle = nullcontext(file)
-        with handle as f:
-            atoms = []
-            for line in f:
-                if line.startswith("HEADER"):
-                    if id is None:
-                        id = line[62:66].strip() or None
-                elif line.startswith(("ATOM", "HETATM")):
-                    atoms.append(Atom.loads(line))
-                elif line.startswith("ENDMDL"):
-                    if not ignore_endmdl:
-                        break
-        return cls(atoms, id=id)
+        cdef _MoleculeParser parser
+        if format == "pdb":
+            parser = _PDBMoleculeParser(id=id, ignore_endmdl=ignore_endmdl)
+        elif format == "cif":
+            parser = _CIFMoleculeParser(id=id, use_author=use_author)
+        else:
+            raise ValueError(f"invalid value for `format` argument: {format!r}")
+        return parser.load(file, molecule_type=cls)
 
     def __cinit__(self):
         self._mol = NULL
@@ -367,21 +499,21 @@ cdef class Atom:
         *,
         int serial,
         str name,
-        str altloc,
         str residue_name,
         str chain_id,
         int residue_number,
-        str insertion_code,
         double x,
         double y,
         double z,
         double occupancy = 0.0,
         double temperature_factor = 0.0,
+        str altloc = ' ',
+        str insertion_code = ' ',
         str segment = '',
         str element = '',
         int charge = 0,
     ):
-        """__init__(self, *, serial, name, altloc, residue_name, chain_id, residue_number, insertion_code, x, y, z, occupancy=0.0, temperature_factor=0.0, segment='', element='', charge=0)\n--\n
+        """__init__(self, *, serial, name, residue_name, chain_id, residue_number, x, y, z, occupancy=0.0, temperature_factor=0.0, altloc=' ', insertion_code=' ', segment='', element='', charge=0)\n--\n
 
         Create a new atom.
 
@@ -424,6 +556,7 @@ cdef class Atom:
         copy_token(self._atom.segID, segment.encode('ascii').ljust(3, b'\0'), 3)
         copy_token(self._atom.element, element.encode('ascii').ljust(2, b'\0'), 2)
 
+        # FIXME
         _name = bytearray(name, 'ascii')
         if len(_name) < 4:
             _name.insert(0, ord('_'))