binderqc 0.1.0__tar.gz

binderqc-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[test]"
+      - run: pytest -q

binderqc-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+# Publishes to PyPI whenever you cut a GitHub Release. No stored token:
+# it authenticates to PyPI via OIDC (trusted publishing). Set up the matching
+# pending publisher on PyPI (project binderqc, repo ssiddhantsharma/binderqc,
+# workflow publish.yml) before the first release.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:      # allow manual runs (and re-runs) from the Actions tab
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write        # required for trusted publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

binderqc-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+*.csv
+*.pdb
+*.cif
+.venv/
+.DS_Store
+build/
+dist/
+*.egg-info/
+
+# keep bundled test fixtures despite the *.pdb / *.cif rules above
+!tests/data/
+!tests/data/*.pdb
+!tests/data/*.cif
+.pytest_cache/

binderqc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siddhant Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

binderqc-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: binderqc
+Version: 0.1.0
+Summary: Quality-control and tag-site scoring for designed protein binders, from a predicted complex
+Project-URL: Homepage, https://github.com/ssiddhantsharma/binderqc
+Author: Siddhant Sharma
+License: MIT License
+        
+        Copyright (c) 2026 Siddhant Sharma
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: binder,developability,protein-design,qc,sasa,structural-biology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Requires-Dist: biotite>=1.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Provides-Extra: validation
+Requires-Dist: matplotlib; extra == 'validation'
+Requires-Dist: scipy; extra == 'validation'
+Description-Content-Type: text/markdown
+
+<h1 align="center">binderqc</h1>
+
+<p align="center">
+  Quality control and tag-site scoring for designed protein binders — geometry and
+  sequence only, one CSV row per binder, straight from a predicted complex.
+</p>
+
+<p align="center">
+  <a href="https://github.com/ssiddhantsharma/binderqc/actions/workflows/ci.yml"><img src="https://github.com/ssiddhantsharma/binderqc/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
+</p>
+
+<p align="center">
+  <img src="docs/schematic.png" width="860"
+       alt="From a predicted binder–target complex, binderqc reports interface, pose, grippability, tag site, and developability">
+</p>
+
+## Install
+
+```bash
+pip install -e .          # or: uv pip install -e .
+```
+
+Python 3.10+. Pulls in `biotite`, `numpy`, and `pandas`.
+
+## Usage
+
+```bash
+binderqc --binder-chains A --target-chains B --out out.csv complex.cif some_dir/
+```
+
+```python
+from binderqc import score_structure
+rows = score_structure("complex.pdb", binder_chains=["A"], target_chains=["B"])
+```
+
+Inputs are PDB/CIF files, globs, or directories. Leave `--binder-chains` off to
+guess the binder as the shortest chain (20–250 aa, printed for each file);
+`--target-chains` defaults to the remaining chains.
+
+| flag | default | meaning |
+|---|---|---|
+| `--binder-chains` | auto-guess | comma-separated binder chain ids |
+| `--target-chains` | all non-binder | comma-separated target chain ids |
+| `--interface-cutoff` | `5.0` | heavy-atom contact distance (Å) |
+| `--exposure-cutoff` | `0.25` | relSASA below which a terminus is buried |
+| `--out` | `binderqc.csv` | output CSV path |
+| `--fasta` | off | also write the QC-passing binders to this FASTA |
+
+Example output for the bundled LCB1 minibinder (a few of the columns):
+
+| recommended_tag | binder_bsa | epitope_planarity | epitope_aromatic_n | pi | qc_pass |
+|---|---|---|---|---|---|
+| C | 1021.4 | 3.21 | 11 | 4.17 | True |
+
+Its `warnings` field reads *both termini ~equidistant from interface (ambiguous)* —
+a tag-site advisory, so `qc_pass` stays `True`.
+
+## What it reports
+
+Per binder chain:
+
+- **Interface** — buried surface area and interface residue count.
+- **Pose** — approach angle (end-on vs. lying across the surface).
+- **Grippability** — epitope planarity, hydrophobic fraction, aromatic anchors.
+- **Tag site** — recommended terminus (N/C) and the numbers behind it: relative
+  SASA, CA–CA distance to the paratope, orientation, and a terminal cysteine's SG SASA.
+- **Developability** — sequence liabilities, GRAVY, net charge, pI, MW, ε₂₈₀.
+
+A `warnings` column flags problems (small, flat, or anchorless interfaces;
+buried, ambiguous, or interface-facing tag sites; hydrophobic sequences).
+`qc_pass` is true when there are no *quality* warnings — tag-site advisories like
+an ambiguous terminus don't count — and `--fasta` dumps exactly those binders.
+
+<details>
+<summary>Full column list</summary>
+
+`pdb, binder_chain, target_chains, binder_len, n_interface_res, binder_bsa,
+approach_angle, epitope_planarity, epitope_hydrophobic_frac, epitope_aromatic_n,
+nterm_resnum, nterm_resname, nterm_relsasa, nterm_dist_to_interface,
+nterm_orientation, nterm_sg_sasa, cterm_resnum, cterm_resname, cterm_relsasa,
+cterm_dist_to_interface, cterm_orientation, cterm_sg_sasa, recommended_tag, mw,
+gravy, net_charge_ph74, pi, ext_coeff_280, sequence_liabilities, warnings,
+qc_pass, binder_sequence`
+</details>
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+Runs against a bundled example, PDB 7JZU (the LCB1 minibinder on the SARS-CoV-2
+RBD). `tests/pisa_correctness.py` is a separate script (not part of the unit
+tests) that downloads 18 public complexes from RCSB and PDBePISA and checks the
+interface area against PISA (r ≈ 1.0, ~1% median error):
+
+```bash
+pip install -e ".[validation]"
+python tests/pisa_correctness.py
+```
+
+## License
+
+MIT

binderqc-0.1.0/README.md

@@ -0,0 +1,107 @@
+<h1 align="center">binderqc</h1>
+
+<p align="center">
+  Quality control and tag-site scoring for designed protein binders — geometry and
+  sequence only, one CSV row per binder, straight from a predicted complex.
+</p>
+
+<p align="center">
+  <a href="https://github.com/ssiddhantsharma/binderqc/actions/workflows/ci.yml"><img src="https://github.com/ssiddhantsharma/binderqc/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
+</p>
+
+<p align="center">
+  <img src="docs/schematic.png" width="860"
+       alt="From a predicted binder–target complex, binderqc reports interface, pose, grippability, tag site, and developability">
+</p>
+
+## Install
+
+```bash
+pip install -e .          # or: uv pip install -e .
+```
+
+Python 3.10+. Pulls in `biotite`, `numpy`, and `pandas`.
+
+## Usage
+
+```bash
+binderqc --binder-chains A --target-chains B --out out.csv complex.cif some_dir/
+```
+
+```python
+from binderqc import score_structure
+rows = score_structure("complex.pdb", binder_chains=["A"], target_chains=["B"])
+```
+
+Inputs are PDB/CIF files, globs, or directories. Leave `--binder-chains` off to
+guess the binder as the shortest chain (20–250 aa, printed for each file);
+`--target-chains` defaults to the remaining chains.
+
+| flag | default | meaning |
+|---|---|---|
+| `--binder-chains` | auto-guess | comma-separated binder chain ids |
+| `--target-chains` | all non-binder | comma-separated target chain ids |
+| `--interface-cutoff` | `5.0` | heavy-atom contact distance (Å) |
+| `--exposure-cutoff` | `0.25` | relSASA below which a terminus is buried |
+| `--out` | `binderqc.csv` | output CSV path |
+| `--fasta` | off | also write the QC-passing binders to this FASTA |
+
+Example output for the bundled LCB1 minibinder (a few of the columns):
+
+| recommended_tag | binder_bsa | epitope_planarity | epitope_aromatic_n | pi | qc_pass |
+|---|---|---|---|---|---|
+| C | 1021.4 | 3.21 | 11 | 4.17 | True |
+
+Its `warnings` field reads *both termini ~equidistant from interface (ambiguous)* —
+a tag-site advisory, so `qc_pass` stays `True`.
+
+## What it reports
+
+Per binder chain:
+
+- **Interface** — buried surface area and interface residue count.
+- **Pose** — approach angle (end-on vs. lying across the surface).
+- **Grippability** — epitope planarity, hydrophobic fraction, aromatic anchors.
+- **Tag site** — recommended terminus (N/C) and the numbers behind it: relative
+  SASA, CA–CA distance to the paratope, orientation, and a terminal cysteine's SG SASA.
+- **Developability** — sequence liabilities, GRAVY, net charge, pI, MW, ε₂₈₀.
+
+A `warnings` column flags problems (small, flat, or anchorless interfaces;
+buried, ambiguous, or interface-facing tag sites; hydrophobic sequences).
+`qc_pass` is true when there are no *quality* warnings — tag-site advisories like
+an ambiguous terminus don't count — and `--fasta` dumps exactly those binders.
+
+<details>
+<summary>Full column list</summary>
+
+`pdb, binder_chain, target_chains, binder_len, n_interface_res, binder_bsa,
+approach_angle, epitope_planarity, epitope_hydrophobic_frac, epitope_aromatic_n,
+nterm_resnum, nterm_resname, nterm_relsasa, nterm_dist_to_interface,
+nterm_orientation, nterm_sg_sasa, cterm_resnum, cterm_resname, cterm_relsasa,
+cterm_dist_to_interface, cterm_orientation, cterm_sg_sasa, recommended_tag, mw,
+gravy, net_charge_ph74, pi, ext_coeff_280, sequence_liabilities, warnings,
+qc_pass, binder_sequence`
+</details>
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+Runs against a bundled example, PDB 7JZU (the LCB1 minibinder on the SARS-CoV-2
+RBD). `tests/pisa_correctness.py` is a separate script (not part of the unit
+tests) that downloads 18 public complexes from RCSB and PDBePISA and checks the
+interface area against PISA (r ≈ 1.0, ~1% median error):
+
+```bash
+pip install -e ".[validation]"
+python tests/pisa_correctness.py
+```
+
+## License
+
+MIT

binderqc-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "binderqc"
+version = "0.1.0"
+description = "Quality-control and tag-site scoring for designed protein binders, from a predicted complex"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Siddhant Sharma" }]
+keywords = ["protein-design", "binder", "developability", "qc", "sasa", "structural-biology"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "biotite>=1.0",
+    "numpy>=1.24",
+    "pandas>=2.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest"]
+validation = ["matplotlib", "scipy"]  # for tests/pisa_correctness.py (network benchmark)
+
+[project.scripts]
+binderqc = "binderqc.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/ssiddhantsharma/binderqc"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/binderqc"]

binderqc-0.1.0/src/binderqc/__init__.py

@@ -0,0 +1,7 @@
+"""Score binder termini for tag/conjugation suitability from predicted complexes."""
+
+from .core import score_structure
+from .paths import gather_paths
+
+__version__ = "0.1.0"
+__all__ = ["score_structure", "gather_paths", "__version__"]

binderqc-0.1.0/src/binderqc/cli.py

@@ -0,0 +1,79 @@
+"""Command-line entry point: `binderqc`.
+
+    binderqc --binder-chains B --target-chains A \
+        --out tag_metrics.csv path/to/preds/*.cif a_directory/
+
+Inputs may be files, globs, or directories (recursively scanned for *.pdb/*.cif).
+"""
+
+import argparse
+import os
+import sys
+
+from .core import score_structure
+from .paths import gather_paths
+
+_DESCRIPTION = """\
+Pick the terminus to tag on a designed protein binder.
+
+For each binder chain in a predicted binder-target complex it reports, per
+terminus, the relative SASA (exposure), the CA-CA distance to the paratope, the
+orientation (does the chain point back at the interface?) and the Cys-SG SASA,
+then recommends the terminus farther from the interface and flags buried,
+ambiguous or interface-facing cases. Just geometry: no folding, no GPU, no network.
+"""
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog="binderqc",
+        description=_DESCRIPTION,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    ap.add_argument("inputs", nargs="+", help="PDB/CIF files, globs, or directories")
+    ap.add_argument("--binder-chains", default="", help="comma-separated; default = auto-guess")
+    ap.add_argument("--target-chains", default="", help="comma-separated; default = all non-binder chains")
+    ap.add_argument("--interface-cutoff", type=float, default=5.0,
+                    help="heavy-atom dist (A) to call a binder residue interface (default 5.0)")
+    ap.add_argument("--exposure-cutoff", type=float, default=0.25,
+                    help="relSASA below which a terminus is buried (default 0.25)")
+    ap.add_argument("--out", default="binderqc.csv", help="output CSV path")
+    ap.add_argument("--fasta", default="",
+                    help="also write QC-passing binders (no quality warnings) to this FASTA path")
+    args = ap.parse_args(argv)
+
+    import pandas as pd  # imported here so `--help` works without pandas
+
+    paths = gather_paths(args.inputs)
+    if not paths:
+        sys.exit("No .pdb/.cif files found in inputs.")
+    binder_chains = [c for c in args.binder_chains.split(",") if c]
+    target_chains = [c for c in args.target_chains.split(",") if c]
+
+    rows = []
+    for p in paths:
+        try:
+            rows.extend(score_structure(p, binder_chains, target_chains,
+                                        args.interface_cutoff, args.exposure_cutoff))
+        except Exception as e:  # noqa: BLE001 - keep the batch going, record the failure
+            rows.append({"pdb": p, "error": str(e)})
+
+    df = pd.DataFrame(rows)
+    df.to_csv(args.out, index=False)
+    shown = df.drop(columns=["binder_sequence"], errors="ignore")  # too wide to print
+    with pd.option_context("display.max_columns", None, "display.width", 220):
+        print(shown.to_string(index=False))
+    print(f"\nWrote {len(df)} rows -> {args.out}")
+
+    if args.fasta:
+        clean = [r for r in rows
+                 if not r.get("error") and r.get("qc_pass") and r.get("binder_sequence")]
+        with open(args.fasta, "w") as fh:
+            for r in clean:
+                fh.write(f">{os.path.splitext(r['pdb'])[0]}|{r['binder_chain']}\n{r['binder_sequence']}\n")
+        scored = sum(1 for r in rows if not r.get("error"))
+        print(f"Wrote {len(clean)}/{scored} QC-passing binders -> {args.fasta}")
+
+
+if __name__ == "__main__":
+    main()