grasp-library-designer 0.1.0__tar.gz

grasp_library_designer-0.1.0/LICENSE

@@ -0,0 +1,26 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2026 JustABiologist and contributors
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published
+by the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+---------------------------------------------------------------------------
+
+This distribution includes vendored ligation-fidelity code and Potapov
+frequency matrices from Fleishman-Lab / GGAssembler (dawdlib), licensed
+under AGPL-3.0. See THIRD_PARTY_LICENSES.md.
+
+The full AGPL-3.0 text is available at:
+https://www.gnu.org/licenses/agpl-3.0.html

grasp_library_designer-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include README.md
+include LICENSE
+include THIRD_PARTY_LICENSES.md
+include pyproject.toml
+include requirements.txt
+include grasp_library_designer.ipynb
+include grasp_oneshot_designer.ipynb
+recursive-include grasp_library/data *.gb *.md
+recursive-include third_party/dawdlib_golden_gate *.py *.csv
+global-exclude __pycache__ *.py[cod] .ipynb_checkpoints* *.checkpoint.*

grasp_library_designer-0.1.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: grasp-library-designer
+Version: 0.1.0
+Summary: Codon-optimize GRASP binder DNA for Golden Gate assembly (library + one-shot).
+Author: JustABiologist
+License: AGPL-3.0-only
+Project-URL: Homepage, https://github.com/JustABiologist/grasp-library-designer
+Project-URL: Repository, https://github.com/JustABiologist/grasp-library-designer
+Project-URL: Issues, https://github.com/JustABiologist/grasp-library-designer/issues
+Keywords: GRASP,Golden Gate,codon optimization,synthetic biology,PPR,ligation fidelity
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: biopython>=1.81
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: ipywidgets>=8.0
+Provides-Extra: notebook
+Requires-Dist: jupyter>=1.0; extra == "notebook"
+Requires-Dist: ipykernel>=6.0; extra == "notebook"
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# GRASP Library Designer
+
+Codon-optimize [GRASP](https://academic.oup.com/nar/article/53/20/gkaf1169/8321212) (Farley et al., *NAR* 2025) binder DNA for Golden Gate assembly.
+
+**PyPI package:** `grasp-library-designer`  
+**Import name:** `grasp_library`
+
+Two Colab Forms notebooks:
+
+| Notebook | Purpose |
+|---|---|
+| [`grasp_oneshot_designer.ipynb`](grasp_oneshot_designer.ipynb) | **One target RNA** → binder protein → free GGA cut sites → oligos |
+| [`grasp_library_designer.ipynb`](grasp_library_designer.ipynb) | Redesign / anneal the **42-module combinatorial library**, then GAP-compile a target |
+
+Hard constraints (library path): protein sequence fixed (synonymous codons only); coding Golden Gate overhang bases stay locked in `coding_mask`. Objectives: ligation fidelity (Potapov / GGAssembler), codon optimality, synthesis fitness.
+
+> **License:** AGPL-3.0 (required by the vendored GGAssembler / dawdlib ligation engine). See [`LICENSE`](LICENSE) and [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md).
+
+---
+
+## Install (PyPI)
+
+```bash
+pip install grasp-library-designer
+# optional notebook extras
+pip install "grasp-library-designer[notebook]"
+```
+
+Minimal API check:
+
+```python
+from grasp_library import materialize_project, build_default_config, LigationFidelityCalculator
+
+project = materialize_project()          # creates ./grasp_library_project + GenBank
+config = build_default_config(project / "input")
+print(LigationFidelityCalculator(25, 18).set_fidelity(["AATG", "GATA"]))
+```
+
+Until the package is published on PyPI, install from GitHub (private repo needs a PAT):
+
+```bash
+pip install "git+https://<TOKEN>@github.com/JustABiologist/grasp-library-designer.git@main"
+```
+
+Or clone and install editable:
+
+```bash
+git clone https://github.com/JustABiologist/grasp-library-designer.git
+cd grasp-library-designer
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[notebook,dev]"
+```
+
+---
+
+## Run in Google Colab
+
+Both notebooks use **Colab Forms** (`#@title` / `#@param`, `{display-mode: "form"}`).
+
+### 1. Open a notebook
+
+From GitHub → **Open in Colab**, or upload the `.ipynb`.
+
+### 2. Install
+
+In **0 · Install**, choose:
+
+| Mode | When |
+|---|---|
+| **PyPI** | After the package is on PyPI (`pip install grasp-library-designer`) |
+| **Private GitHub** | Clone this private repo with a `repo`-scoped PAT |
+| **Local editable** | Notebook already lives in a checkout |
+
+### 3a. One-shot
+
+Settings → Preview binder → Design oligos → Export Excel  
+Outputs: `grasp_library_project/output/oneshot/{RNA}/`
+
+### 3b. Combinatorial library
+
+Settings → Import → Redesign overhangs → Anneal → Pareto plot → Export → Compile target  
+Outputs: `grasp_library_project/output/`
+
+Bundled Farley et al. GenBank modules are copied into the project folder on first run via `materialize_project()`.
+
+---
+
+## Run locally (Cursor / Jupyter / VS Code)
+
+```bash
+pip install -e ".[notebook]"
+python -m ipykernel install --user --name grasp-library-designer --display-name "grasp-library-designer"
+```
+
+Select that kernel, open either notebook, run top-to-bottom.
+
+---
+
+## Package layout
+
+```
+grasp_library/                 # installable Python package
+  data/profiles/.../genbank/   # bundled GRASP GenBank modules
+  paths.py                     # materialize_project()
+  ...
+third_party/dawdlib_golden_gate/   # Potapov ligation fidelity (AGPL; also installed)
+grasp_*_designer.ipynb             # Colab Forms UIs (also in sdist)
+```
+
+---
+
+## Build / publish (maintainers)
+
+```bash
+pip install -e ".[dev]"
+python -m build
+twine check dist/*
+# Test PyPI first (recommended):
+twine upload --repository testpypi dist/*
+# Production:
+twine upload dist/*
+```
+
+Requires a PyPI API token (`TWINE_USERNAME=__token__`, `TWINE_PASSWORD=pypi-...`).
+
+---
+
+## Hiding code (Colab / Jupyter / VS Code)
+
+| Frontend | How |
+|---|---|
+| **Google Colab** | Forms: `#@title … {display-mode: "form"}` + `#@param` |
+| **Cursor / VS Code** | **Notebook: Collapse All Cell Inputs** |
+
+**Hide ≠ protect.** Source remains in the `.ipynb`.
+
+---
+
+## License notes
+
+- Distributed package license: **AGPL-3.0** (see [`LICENSE`](LICENSE)).
+- Vendored ligation engine under `third_party/dawdlib_golden_gate/` is AGPL-3.0 (Fleishman-Lab / GGAssembler).
+- GRASP sequences: Farley et al., *Nucleic Acids Res.* 2025.
+
+---
+
+## Quick smoke test
+
+```bash
+python - <<'PY'
+from pathlib import Path
+from grasp_library import (
+    materialize_project,
+    build_default_config,
+    run_oneshot_design,
+    LigationFidelityCalculator,
+)
+from grasp_library.codon_tables import apply_organism_codon_table, load_codon_usage
+
+project = materialize_project()
+input_dir = project / "input"
+cfg = build_default_config(input_dir)
+cfg["optimizer"]["iterations_per_part"] = 200
+apply_organism_codon_table("Escherichia coli (Kazusa)", input_dir / "codon_usage.csv")
+_, codon_data = load_codon_usage(input_dir / "codon_usage.csv", genetic_code=1)
+run_oneshot_design(
+    target_rna="UUACACGUG",
+    codon_data=codon_data,
+    config=cfg,
+    output_dir=project / "output" / "oneshot" / "UUACACGUG",
+    n_fragments=4,
+    fidelity=LigationFidelityCalculator(25, 18),
+)
+print("ok")
+PY
+```

grasp_library_designer-0.1.0/README.md

@@ -0,0 +1,177 @@
+# GRASP Library Designer
+
+Codon-optimize [GRASP](https://academic.oup.com/nar/article/53/20/gkaf1169/8321212) (Farley et al., *NAR* 2025) binder DNA for Golden Gate assembly.
+
+**PyPI package:** `grasp-library-designer`  
+**Import name:** `grasp_library`
+
+Two Colab Forms notebooks:
+
+| Notebook | Purpose |
+|---|---|
+| [`grasp_oneshot_designer.ipynb`](grasp_oneshot_designer.ipynb) | **One target RNA** → binder protein → free GGA cut sites → oligos |
+| [`grasp_library_designer.ipynb`](grasp_library_designer.ipynb) | Redesign / anneal the **42-module combinatorial library**, then GAP-compile a target |
+
+Hard constraints (library path): protein sequence fixed (synonymous codons only); coding Golden Gate overhang bases stay locked in `coding_mask`. Objectives: ligation fidelity (Potapov / GGAssembler), codon optimality, synthesis fitness.
+
+> **License:** AGPL-3.0 (required by the vendored GGAssembler / dawdlib ligation engine). See [`LICENSE`](LICENSE) and [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md).
+
+---
+
+## Install (PyPI)
+
+```bash
+pip install grasp-library-designer
+# optional notebook extras
+pip install "grasp-library-designer[notebook]"
+```
+
+Minimal API check:
+
+```python
+from grasp_library import materialize_project, build_default_config, LigationFidelityCalculator
+
+project = materialize_project()          # creates ./grasp_library_project + GenBank
+config = build_default_config(project / "input")
+print(LigationFidelityCalculator(25, 18).set_fidelity(["AATG", "GATA"]))
+```
+
+Until the package is published on PyPI, install from GitHub (private repo needs a PAT):
+
+```bash
+pip install "git+https://<TOKEN>@github.com/JustABiologist/grasp-library-designer.git@main"
+```
+
+Or clone and install editable:
+
+```bash
+git clone https://github.com/JustABiologist/grasp-library-designer.git
+cd grasp-library-designer
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[notebook,dev]"
+```
+
+---
+
+## Run in Google Colab
+
+Both notebooks use **Colab Forms** (`#@title` / `#@param`, `{display-mode: "form"}`).
+
+### 1. Open a notebook
+
+From GitHub → **Open in Colab**, or upload the `.ipynb`.
+
+### 2. Install
+
+In **0 · Install**, choose:
+
+| Mode | When |
+|---|---|
+| **PyPI** | After the package is on PyPI (`pip install grasp-library-designer`) |
+| **Private GitHub** | Clone this private repo with a `repo`-scoped PAT |
+| **Local editable** | Notebook already lives in a checkout |
+
+### 3a. One-shot
+
+Settings → Preview binder → Design oligos → Export Excel  
+Outputs: `grasp_library_project/output/oneshot/{RNA}/`
+
+### 3b. Combinatorial library
+
+Settings → Import → Redesign overhangs → Anneal → Pareto plot → Export → Compile target  
+Outputs: `grasp_library_project/output/`
+
+Bundled Farley et al. GenBank modules are copied into the project folder on first run via `materialize_project()`.
+
+---
+
+## Run locally (Cursor / Jupyter / VS Code)
+
+```bash
+pip install -e ".[notebook]"
+python -m ipykernel install --user --name grasp-library-designer --display-name "grasp-library-designer"
+```
+
+Select that kernel, open either notebook, run top-to-bottom.
+
+---
+
+## Package layout
+
+```
+grasp_library/                 # installable Python package
+  data/profiles/.../genbank/   # bundled GRASP GenBank modules
+  paths.py                     # materialize_project()
+  ...
+third_party/dawdlib_golden_gate/   # Potapov ligation fidelity (AGPL; also installed)
+grasp_*_designer.ipynb             # Colab Forms UIs (also in sdist)
+```
+
+---
+
+## Build / publish (maintainers)
+
+```bash
+pip install -e ".[dev]"
+python -m build
+twine check dist/*
+# Test PyPI first (recommended):
+twine upload --repository testpypi dist/*
+# Production:
+twine upload dist/*
+```
+
+Requires a PyPI API token (`TWINE_USERNAME=__token__`, `TWINE_PASSWORD=pypi-...`).
+
+---
+
+## Hiding code (Colab / Jupyter / VS Code)
+
+| Frontend | How |
+|---|---|
+| **Google Colab** | Forms: `#@title … {display-mode: "form"}` + `#@param` |
+| **Cursor / VS Code** | **Notebook: Collapse All Cell Inputs** |
+
+**Hide ≠ protect.** Source remains in the `.ipynb`.
+
+---
+
+## License notes
+
+- Distributed package license: **AGPL-3.0** (see [`LICENSE`](LICENSE)).
+- Vendored ligation engine under `third_party/dawdlib_golden_gate/` is AGPL-3.0 (Fleishman-Lab / GGAssembler).
+- GRASP sequences: Farley et al., *Nucleic Acids Res.* 2025.
+
+---
+
+## Quick smoke test
+
+```bash
+python - <<'PY'
+from pathlib import Path
+from grasp_library import (
+    materialize_project,
+    build_default_config,
+    run_oneshot_design,
+    LigationFidelityCalculator,
+)
+from grasp_library.codon_tables import apply_organism_codon_table, load_codon_usage
+
+project = materialize_project()
+input_dir = project / "input"
+cfg = build_default_config(input_dir)
+cfg["optimizer"]["iterations_per_part"] = 200
+apply_organism_codon_table("Escherichia coli (Kazusa)", input_dir / "codon_usage.csv")
+_, codon_data = load_codon_usage(input_dir / "codon_usage.csv", genetic_code=1)
+run_oneshot_design(
+    target_rna="UUACACGUG",
+    codon_data=codon_data,
+    config=cfg,
+    output_dir=project / "output" / "oneshot" / "UUACACGUG",
+    n_fragments=4,
+    fidelity=LigationFidelityCalculator(25, 18),
+)
+print("ok")
+PY
+```

grasp_library_designer-0.1.0/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,11 @@
+# Third-party components
+
+## Fleishman-Lab / GGAssembler (dawdlib golden-gate fidelity)
+
+- Path: `third_party/dawdlib_golden_gate/`
+- Upstream: https://github.com/Fleishman-Lab/GGAssembler
+- Related package: https://github.com/Fleishman-Lab/dawdlib
+- License: AGPL-3.0
+- What was vendored: `gate_data.py` and Potapov/NEB ligation frequency CSVs used by `GGData.reaction_fidelity`
+
+Ligation frequency data originate from Potapov et al., ACS Synth. Biol. (2018).

grasp_library_designer-0.1.0/grasp_library/__init__.py

@@ -0,0 +1,123 @@
+"""GRASP library designer: masked codon optimization with Pareto trade-offs."""
+
+from .ligation_fidelity import LigationFidelityCalculator
+from .objectives import ObjectiveScores, evaluate_design
+from .pareto import (
+    ParetoPoint,
+    dominates,
+    knee_point,
+    optimize_pareto_overhangs,
+    pareto_front,
+)
+from .sample_codon_tables import (
+    SAMPLE_CODON_TABLES,
+    codon_table_dataframe,
+    sample_names,
+    write_sample_codon_table,
+)
+from .import_grasp import (
+    compile_target_gap,
+    import_grasp_profile,
+    pick_parts_for_target,
+)
+from .synthesis_vendors import (
+    ASSEMBLY_ENZYMES,
+    LIGATION_TABLES,
+    SYNTHESIS_VENDORS,
+    apply_enzyme_to_config,
+    apply_ligation_table_to_config,
+    apply_vendor_to_config,
+    enzyme_names,
+    ligation_table_names,
+    twist_length_advice,
+    vendor_names,
+)
+from .control_panel import GraspControlPanel, build_default_config, wire_reload_button
+from .workflows import (
+    run_overhang_redesign,
+    run_library_optimize,
+    rescore_pareto_front_after_anneal,
+    load_and_validate_parts,
+    ensure_grasp_imported,
+    export_optimized_library,
+    compile_and_assemble_target,
+    plot_library_pareto_after_anneal,
+    run_library_redesign_and_anneal,
+)
+from .codon_tables import load_codon_usage, apply_organism_codon_table, validate_parts_for_organism
+from .codon_validation import analyze_cut_site_aa_risks, validate_codon_table_aas
+from .plotting import plot_pareto_front
+from .optimizer import (
+    optimize_coding_sequence,
+    optimize_library,
+    synthesis_qc,
+    simulate_assembled_cds,
+)
+from .oneshot import run_oneshot_design, sanitize_rna_name
+from .binder import rna_to_binder_aa, describe_binder, normalize_target_rna
+from .gga_split import plan_gga_from_optimized_cds, suggest_fragment_count
+from .paths import (
+    bundled_profile_genbank,
+    materialize_project,
+    project_paths,
+)
+
+__all__ = [
+    "LigationFidelityCalculator",
+    "ObjectiveScores",
+    "evaluate_design",
+    "ParetoPoint",
+    "dominates",
+    "pareto_front",
+    "optimize_pareto_overhangs",
+    "knee_point",
+    "SAMPLE_CODON_TABLES",
+    "codon_table_dataframe",
+    "sample_names",
+    "write_sample_codon_table",
+    "import_grasp_profile",
+    "compile_target_gap",
+    "pick_parts_for_target",
+    "SYNTHESIS_VENDORS",
+    "ASSEMBLY_ENZYMES",
+    "LIGATION_TABLES",
+    "vendor_names",
+    "enzyme_names",
+    "ligation_table_names",
+    "apply_vendor_to_config",
+    "apply_enzyme_to_config",
+    "apply_ligation_table_to_config",
+    "twist_length_advice",
+    "GraspControlPanel",
+    "build_default_config",
+    "wire_reload_button",
+    "run_overhang_redesign",
+    "run_library_optimize",
+    "rescore_pareto_front_after_anneal",
+    "load_and_validate_parts",
+    "ensure_grasp_imported",
+    "export_optimized_library",
+    "compile_and_assemble_target",
+    "plot_library_pareto_after_anneal",
+    "run_library_redesign_and_anneal",
+    "load_codon_usage",
+    "apply_organism_codon_table",
+    "validate_parts_for_organism",
+    "analyze_cut_site_aa_risks",
+    "validate_codon_table_aas",
+    "plot_pareto_front",
+    "optimize_coding_sequence",
+    "optimize_library",
+    "synthesis_qc",
+    "simulate_assembled_cds",
+    "run_oneshot_design",
+    "sanitize_rna_name",
+    "rna_to_binder_aa",
+    "describe_binder",
+    "normalize_target_rna",
+    "plan_gga_from_optimized_cds",
+    "suggest_fragment_count",
+    "bundled_profile_genbank",
+    "materialize_project",
+    "project_paths",
+]

grasp_library_designer-0.1.0/grasp_library/binder.py

@@ -0,0 +1,76 @@
+"""RNA → GRASP binder protein (PPR recognition code), no library parts required."""
+
+from __future__ import annotations
+
+from typing import List, Sequence, Tuple
+
+# Classic PPR code: (5th AA, last AA) of each repeat
+_RNA_TO_CODE = {
+    "A": ("T", "N"),
+    "C": ("N", "N"),
+    "G": ("T", "D"),
+    "U": ("N", "D"),
+    "T": ("N", "D"),
+}
+
+# Solvating N-helix from Farley et al. GRASP 9S native assemblies
+NTERM_HELIX = "QGGNSEEPRKSFDERPERGVVS"
+
+# One ~31-aa PPR-like repeat; only the W?AM 5th and PER? last positions vary
+REPEAT_TEMPLATE = "W{fifth}AMISGYAQNGRIDEARELFDKMPER{last}VVS"
+
+
+def normalize_target_rna(sequence: str) -> str:
+    rna = str(sequence).upper().replace("T", "U")
+    rna = "".join(b for b in rna if b in "ACGU")
+    if not rna:
+        raise ValueError("Empty target RNA")
+    if len(rna) not in (9, 14, 19):
+        raise ValueError(
+            f"Target RNA length must be 9, 14, or 19 (got {len(rna)}). "
+            "GRASP binder scaffolds are defined for those sizes."
+        )
+    if any(b not in _RNA_TO_CODE for b in rna):
+        raise ValueError(f"Non-ACGU base in target RNA: {sequence!r}")
+    return rna
+
+
+def rna_to_ppr_pairs(target_rna: str) -> List[Tuple[str, str]]:
+    """Return [(5th, last), ...] recognition pairs for each RNA base."""
+    rna = normalize_target_rna(target_rna)
+    return [_RNA_TO_CODE[b] for b in rna]
+
+
+def rna_to_binder_aa(target_rna: str) -> str:
+    """
+    Build the continuous GRASP binder protein for a target RNA.
+
+    Does **not** use combinatorial library modules — only the PPR code and
+    the validated GRASP repeat scaffold (matches oh-bounded native 9S assemblies).
+    """
+    pairs = rna_to_ppr_pairs(target_rna)
+    parts = [NTERM_HELIX]
+    for fifth, last in pairs:
+        parts.append(REPEAT_TEMPLATE.format(fifth=fifth, last=last))
+    return "".join(parts)
+
+
+def ppr_code_string(target_rna: str) -> str:
+    """Classic concatenated code, e.g. UUACACGUG → NDNDTNNNTNNNTDNDTD."""
+    return "".join(f"{a}{b}" for a, b in rna_to_ppr_pairs(target_rna))
+
+
+def describe_binder(target_rna: str) -> dict:
+    rna = normalize_target_rna(target_rna)
+    aa = rna_to_binder_aa(rna)
+    pairs = rna_to_ppr_pairs(rna)
+    return {
+        "target_rna": rna,
+        "n_bases": len(rna),
+        "ppr_code": ppr_code_string(rna),
+        "ppr_pairs": [f"{a}{b}" for a, b in pairs],
+        "aa_sequence": aa,
+        "aa_length": len(aa),
+        "cds_length": 3 * len(aa),
+        "n_repeats": len(pairs),
+    }