pdb-md 0.1.0__tar.gz

pdb_md-0.1.0/LICENSE

@@ -0,0 +1,32 @@
+BSD 3-Clause License
+
+Copyright (c) 2002, Thomas Hamelryck
+Copyright (c) 2026, Joe Hoye Dow
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

pdb_md-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.5
+Name: pdb-md
+Version: 0.1.0
+Summary: Pre- and post-processing toolkit for PDB/MMCIF structure files in molecular dynamics workflows.
+Project-URL: Homepage, https://github.com/MaybeBio/PDB-MD-Suite
+Project-URL: Issues, https://github.com/MaybeBio/PDB-MD-Suite/issues
+Author-email: Joe Hoye Dow <luxunisgod123@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
+Requires-Dist: biopython>=1.87
+Requires-Dist: typer>=0.27.1
+Description-Content-Type: text/markdown
+
+# 🔬 PDB/MMCIF segment selector
+
+> Formerly published on PyPI as `pdb-select`. That name is deprecated — use `pdb-md`.
+
+> PDB file segmentation tool, extract specific chains and residue ranges from PDB/MMCIF files.   
+
+# Installation
+
+```bash
+pip install pdb-md
+```
+
+# Usage
+
+```bash
+pdb-md --help
+                                                                        
+ Usage: pdb-md [OPTIONS] COMMAND [ARGS]...                                                                                                                                          
+                                                                                                                                                                                        
+ Segment selector for PDB/MMCIF Structure file                                                                                                                                          
+                                                                                                                                                                                        
+╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ --install-completion          Install completion for the current shell.                                                                                                              │
+│ --show-completion             Show completion for the current shell, to copy it or customize the installation.                                                                       │
+│ --help                        Show this message and exit.                                                                                                                            │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ select  Select segments from a PDB or MMCIF structure file.                                                                                                                          │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯                                                                        
+```
+
+> ⚠️ Warning: Sequence index matching to Uniprot only be tested in AlphaFold PDB files. 
+> 
+> Check for SIFTS 
+
+```bash
+pdb-md select  --help
+                                                                                                                                                                                        
+ Usage: pdb-md select [OPTIONS]                                                                                                                                                     
+                                                                                                                                                                                        
+ Select segments from a PDB or MMCIF structure file.                                                                                                                                    
+                                                                                                                                                                                        
+╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ *  --input    -I      <path>  Input PDB or MMCIF file [required]                                                                                                                     │
+│    --output   -O      <path>  Output PDB file, defaults to <input stem>_selected.pdb in the current working directory                                                                │
+│ *  --segment  -s      <str>   Segments to select, either 'chain' (whole chain, e.g. A) or 'chain:start-end' (e.g. A:1-10). Repeatable. [required]                                    │
+│    --help                     Show this message and exit.                                                                                                                            │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+example:
+
+```bash
+pdb-md select -I znf263_all_hs7_30_0.54_0.37_model_0.cif -O znf263_all_hs7_30_0.54_0.37_model_0_selected.pdb -s A:369-683 -s B -s C -s D -s E -s F -s G -s H -s I -s J -s K:1-47 -s L:29-75 
+```
+
+change from 
+![](./figs/image1.png) to
+![](./figs/image.png)

pdb_md-0.1.0/README.md

@@ -0,0 +1,59 @@
+# 🔬 PDB/MMCIF segment selector
+
+> Formerly published on PyPI as `pdb-select`. That name is deprecated — use `pdb-md`.
+
+> PDB file segmentation tool, extract specific chains and residue ranges from PDB/MMCIF files.   
+
+# Installation
+
+```bash
+pip install pdb-md
+```
+
+# Usage
+
+```bash
+pdb-md --help
+                                                                        
+ Usage: pdb-md [OPTIONS] COMMAND [ARGS]...                                                                                                                                          
+                                                                                                                                                                                        
+ Segment selector for PDB/MMCIF Structure file                                                                                                                                          
+                                                                                                                                                                                        
+╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ --install-completion          Install completion for the current shell.                                                                                                              │
+│ --show-completion             Show completion for the current shell, to copy it or customize the installation.                                                                       │
+│ --help                        Show this message and exit.                                                                                                                            │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ select  Select segments from a PDB or MMCIF structure file.                                                                                                                          │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯                                                                        
+```
+
+> ⚠️ Warning: Sequence index matching to Uniprot only be tested in AlphaFold PDB files. 
+> 
+> Check for SIFTS 
+
+```bash
+pdb-md select  --help
+                                                                                                                                                                                        
+ Usage: pdb-md select [OPTIONS]                                                                                                                                                     
+                                                                                                                                                                                        
+ Select segments from a PDB or MMCIF structure file.                                                                                                                                    
+                                                                                                                                                                                        
+╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ *  --input    -I      <path>  Input PDB or MMCIF file [required]                                                                                                                     │
+│    --output   -O      <path>  Output PDB file, defaults to <input stem>_selected.pdb in the current working directory                                                                │
+│ *  --segment  -s      <str>   Segments to select, either 'chain' (whole chain, e.g. A) or 'chain:start-end' (e.g. A:1-10). Repeatable. [required]                                    │
+│    --help                     Show this message and exit.                                                                                                                            │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+example:
+
+```bash
+pdb-md select -I znf263_all_hs7_30_0.54_0.37_model_0.cif -O znf263_all_hs7_30_0.54_0.37_model_0_selected.pdb -s A:369-683 -s B -s C -s D -s E -s F -s G -s H -s I -s J -s K:1-47 -s L:29-75 
+```
+
+change from 
+![](./figs/image1.png) to
+![](./figs/image.png)

pdb_md-0.1.0/pdb_md/MultiChainSelector.py

@@ -0,0 +1,55 @@
+from .SingleChainSelector import SingleChainSelector
+
+class MultiChainSelector:
+    """Only accepts residues with right chainid, between start and end.
+
+    Remove hydrogens, waters and ligands. Only use model 0 by default.
+
+    collector for multiple SingleChainSelector objects, to be used with PDBIO
+    """
+
+    def __init__(self, selectors: list[SingleChainSelector], model_id: int = 0):
+        """Initialize the class."""
+        # chain id must be uniquely provided in one specific selector
+        ids = [selector.chain_id for selector in selectors]
+        if len(ids) != len(set(ids)):
+            raise ValueError(f"Duplicate chain_id in selectors: {ids}") 
+        self.selectors = selectors
+        self.model_id = model_id
+    def accept_model(self, model):
+        """Verify if model match the model identifier."""
+        # model - only keep model 0
+        if model.get_id() == self.model_id:
+            return 1
+        return 0
+    def accept_chain(self, chain):
+        """Verify if chain match the chain identifier."""
+        # every chain in the structure is accepted only if it is accepted by any of the selectors (by its chain selector function)
+        for selector in self.selectors:
+            # or
+            # if chain.get_id() == selector.chain_id:
+            if selector.accept_chain(chain):
+                return 1
+        return 0
+
+    def accept_residue(self, residue):
+        """Verify if a residue sequence is between the start and end sequence of a specific selector."""
+        # residue - between start and end
+        for selector in self.selectors:
+            # eg. selector is [SingleChainSelector(chain_id='A', regions=[(1, 10), (20, 30)], model_id=0),
+            # SingleChainSelector(chain_id='B', regions=[(5, 15)], model_id=0)]
+            # then, for residue 5-10 whether in A or B, it will be accepted but lose the information of which selector accepted it
+            # so, only the selector with the matching chain id of the residue has the right to accept the residue or not
+            if selector.chain_id == residue.get_parent().get_id():
+                return selector.accept_residue(residue)
+        return 0
+
+    def accept_atom(self, atom):
+        """Verify if atoms are not Hydrogen."""
+        # we can also define it specifically for each selector
+        # only the selector with the matching chain id of the atom's parent residue has the right to accept the atom or not
+        # atoms - get rid of hydrogens
+        for selector in self.selectors:
+            if selector.chain_id == atom.get_parent().get_parent().get_id():
+                return selector.accept_atom(atom)
+        return 0

pdb_md-0.1.0/pdb_md/SingleChainSelector.py

@@ -0,0 +1,102 @@
+# this script is adapted and modified from https://github.com/biopython/biopython/blob/master/Bio/PDB/Dice.py
+
+# Copyright (C) 2002, Thomas Hamelryck (thamelry@binf.ku.dk)
+#
+# This file is part of the Biopython distribution and governed by your
+# choice of the "Biopython License Agreement" or the "BSD 3-Clause License".
+# Please see the LICENSE file that should have been included as part of this
+# package.
+#
+# Modifications for pdb-md: Copyright (C) 2026, Joe Hoye Dow
+# Licensed under the BSD 3-Clause License (see LICENSE).
+
+"""Code for chopping up (dicing) a structure.
+
+This module is used internally by the Bio.PDB.extract() function.
+"""
+
+import re
+import warnings
+
+from Bio import BiopythonWarning
+from Bio.PDB.PDBIO import PDBIO
+from .utils import consolidate_ranges
+
+_hydrogen = re.compile("[123 ]*H.*")
+
+
+class SingleChainSelector:
+    """Only accepts residues with right chainid, between start and end.
+
+    Remove hydrogens, waters and ligands. Only use model 0 by default.
+
+    Modified to support multiple regions selected.
+
+    Pass regions=None to keep the whole chain instead of specific ranges.
+    """
+
+    def __init__(
+        self,
+        chain_id,
+        regions: list[tuple[int, int]] | None = None,
+        model_id=0,
+    ):
+        """Initialize the class.
+
+        A regions of None means "whole chain" and an empty list means "keep
+        nothing"; the two stay distinguishable because consolidate_ranges would
+        collapse both to an empty list otherwise.
+        """
+        self.chain_id = chain_id
+        self.regions = None if regions is None else consolidate_ranges(regions)
+        self.model_id = model_id
+
+    def accept_model(self, model):
+        """Verify if model match the model identifier."""
+        # model - only keep model 0
+        if model.get_id() == self.model_id:
+            return 1
+        return 0
+
+    def accept_chain(self, chain):
+        """Verify if chain match chain identifier."""
+        if chain.get_id() == self.chain_id:
+            return 1
+        return 0
+
+    def accept_residue(self, residue):
+        """Verify if a residue sequence is between the start and end sequence."""
+        # residue - between start and end
+        hetatm_flag, resseq, icode = residue.get_id()
+        if hetatm_flag != " ":
+            # skip HETATMS
+            return 0
+        if icode != " ":
+            warnings.warn(
+                f"WARNING: Icode {icode} at position {resseq}", BiopythonWarning
+            )
+        # whole chain: every standard residue is accepted
+        if self.regions is None:
+            return 1
+        # or if any(start <= resseq <= end for start, end in self.regions)
+        for start, end in self.regions:
+            if start <= resseq <= end:
+                return 1
+        return 0
+
+    def accept_atom(self, atom):
+        """Verify if atoms are not Hydrogen."""
+        # atoms - get rid of hydrogens
+        name = atom.get_id()
+        if _hydrogen.match(name):
+            return 0
+        else:
+            return 1
+
+# extract function only works for a single chain, useless now that we have MultiChainSelector
+def extract(structure, chain_id, regions, filename):
+    """Write out selected portion to filename."""
+    sel = SingleChainSelector(chain_id, regions)
+    io = PDBIO()
+    io.set_structure(structure)
+    io.save(filename, sel)

pdb_md-0.1.0/pdb_md/cli.py

@@ -0,0 +1,98 @@
+import re
+from pathlib import Path
+from typing import Optional
+
+import typer
+from Bio.PDB import MMCIFParser, PDBIO, PDBParser
+
+from .MultiChainSelector import MultiChainSelector
+from .SingleChainSelector import SingleChainSelector
+
+app = typer.Typer(help="Segment selector for PDB/MMCIF Structure file", no_args_is_help=True)
+
+# Rules for typer: When the app registers only one command and has no callback, this command will be directly promoted to the root command (single-command collapse), and the subcommand layer will no longer exist.
+# Adding @app.callback() explicitly declares "this is a command group"
+@app.callback()
+def main():
+    """Segment selector for PDB/MMCIF structure files."""
+
+
+@app.command("select", no_args_is_help=True)
+def select_cmd(
+    input_file: Path = typer.Option(..., "--input", "-I", help="Input PDB or MMCIF file"),
+    output_file: Optional[Path] = typer.Option(
+        None,
+        "--output",
+        "-O",
+        help="Output PDB file, defaults to <input stem>_selected.pdb in the current working directory",
+    ),
+    segments: list[str] = typer.Option(
+        ...,
+        "--segment",
+        "-s",
+        help="Segments to select, either 'chain' (whole chain, e.g. A) or 'chain:start-end' (e.g. A:1-10). Repeatable.",
+    ),
+):
+    """Select segments from a PDB or MMCIF structure file."""
+    if not input_file.exists():
+        raise ValueError(f"Input file {input_file} does not exist.")
+
+    # Determine the parser based on file extension
+    suffix = input_file.suffix.lower()
+    if suffix == ".pdb":
+        parser = PDBParser()
+    elif suffix == ".cif":
+        parser = MMCIFParser()
+    else:
+        raise ValueError("Unsupported file format. Please provide a .pdb or .cif file.")
+
+    # Parse the structure
+    structure = parser.get_structure("structure", input_file)
+
+    # Create SingleChainSelector objects; a segment without a colon selects a whole chain
+    selectors = []
+    for seg in segments:
+        if ":" not in seg:
+            chain_id = seg.strip()
+            if not chain_id:
+                raise ValueError(
+                    f"Invalid segment: {seg!r}. Expected 'chain' or 'chain:start-end'."
+                )
+            selectors.append(SingleChainSelector(chain_id, None))
+            continue
+        chain_id, range_str = seg.split(":", 1)
+        match = re.fullmatch(r"(\d+)-(\d+)", range_str)
+        if not match:
+            raise ValueError(f"Invalid range format: {range_str}. Expected format is start-end.")
+        start, end = map(int, match.groups())
+        selectors.append(SingleChainSelector(chain_id, [(start, end)]))
+
+    # Warn about chain ids that are absent from the model that gets written (model 0),
+    # so a typo does not silently produce an empty output file
+    existing_chains = {
+        chain.get_id()
+        for model in structure.get_models()
+        if model.get_id() == 0
+        for chain in model
+    }
+    for selector in selectors:
+        if selector.chain_id not in existing_chains:
+            typer.echo(
+                f"WARNING: chain {selector.chain_id} not found in {input_file}", err=True
+            )
+
+    # Create MultiChainSelector
+    multi_selector = MultiChainSelector(selectors)
+
+    # Write out selected portion to output file, defaulting to <input stem>_selected.pdb
+    if not output_file:
+        output_file = Path(input_file.stem + "_selected.pdb")
+    io = PDBIO()
+    io.set_structure(structure)
+    # PDBIO.save only accepts a filename string or an open filehandle, not a Path
+    io.save(str(output_file), multi_selector)
+    typer.echo(f"Wrote {output_file}")
+
+
+if __name__ == "__main__":
+    app()

pdb_md-0.1.0/pdb_md/utils.py

@@ -0,0 +1,34 @@
+# some utility functions defined
+
+def consolidate_ranges(ranges: list[tuple[int, int]]) -> list[tuple[int, int]]:
+    """
+    Description
+    -----------
+    Consolidate a list of tuple ranges into a list of non-overlapping ranges, and sort in ascending order
+
+    Args
+    ----
+    ranges: list[tuple[int, int]]
+        A list of tuple ranges, e.g. [(1, 5), (3, 7), (10, 12)]
+
+    Returns
+    -------
+    list[tuple[int, int]]: A list of non-overlapping ranges, sorted in ascending order
+    
+    """
+    if not ranges:
+        return []
+    # first sort the ranges by the start value in ascending order
+    ranges.sort(key=lambda x: x[0])
+    # start with the first range
+    consolidated = [ranges[0]]
+    # start comparison
+    for current in ranges[1:]:
+        previous = consolidated[-1]
+        if current[0] <= previous[1] + 1:
+            previous[1] = max(previous[1], current[1])
+        else:
+            consolidated.append(current)
+    return consolidated
+
+    

pdb_md-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pdb-md"
+version = "0.1.0"
+authors = [
+  {name = "Joe Hoye Dow", email = "luxunisgod123@gmail.com"}
+  ]
+description = "Pre- and post-processing toolkit for PDB/MMCIF structure files in molecular dynamics workflows."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Operating System :: OS Independent"
+]
+
+
+# use pip show to check
+dependencies = [
+  "biopython>=1.87", 
+  "typer>=0.27.1", 
+]
+
+[project.urls]
+Homepage = "https://github.com/MaybeBio/PDB-MD-Suite"
+Issues = "https://github.com/MaybeBio/PDB-MD-Suite/issues"
+
+[project.scripts]                                                                                            
+pdb-md = "pdb_md.cli:app"
+
+[tool.hatch.build.targets.wheel]                                                                             
+packages = ["pdb_md"]