PEN-ASSEMBLE
Programmable Enzyme Networks — Automated Strategy and Scoring Engine for Molecular Bridge-recombinase Library Engineering
Part of PEN-STACK — the four-package computational biology pipeline for programmable genome editor discovery. Paper 4 of 5 · genome-atlas → mech-class → pen-score → pen-assemble → PEN-COMPARE (in prep)
What is PEN-ASSEMBLE?
Most gene therapies today use CRISPR–Cas9, which cuts both strands of DNA (a double-strand break) to make its edit. While powerful, DSBs activate cellular damage responses, introduce unwanted insertions or deletions, and limit cargo size.
IS110-family bridge recombinases work differently: they insert large DNA payloads — up to 50 kilobases — at specific genomic sites without ever cutting both DNA strands. They are guided by a short RNA molecule (the bridging RNA, or bRNA), and their targeting can be reprogrammed simply by swapping the bRNA guide sequence. This makes them highly attractive for safe, precise, large-cargo gene therapy.
PEN-ASSEMBLE is the computational nomination pipeline that asks: can we design IS110-family variants that are even better than the natural protein IS621? It evaluates 1,029 candidate designs across four orthogonal engineering strategies — domain-swapping, ortholog discovery, immunogenicity reduction, and backbone redesign — using the 8-axis PenScore composite metric. Every step is pre-registered, fully reproducible, and independently verified.
Key finding
16 designs beat IS621 (the current gold-standard bridge recombinase) on the pre-registered PenScore threshold of 0.929. The top candidate — a Monte Carlo deimmunized IS621 variant — scores 0.9673, combining a +11.8% improvement in immunogenicity over IS621 while preserving full mechanistic activity. All five pre-registered predictions PASS, supporting publication with a strong claim.
Why PEN-ASSEMBLE Was Built
The problem
IS110-family bridge recombinases are a large and largely uncharacterised protein family — NCBI holds over 31,000 sequences. Deciding which ones are worth synthesising and testing in a wet-lab requires answering four independent questions simultaneously:
- Is the mechanism correct? — Does this protein actually perform DSB-free insertion, or will mech-class's gradient-boosted model mis-call it as a nuclease?
- Is the structure viable? — Does ESMFold predict a well-folded protein with high pLDDT at the active site?
- Is it therapeutically fit? — Is it compact enough for AAV delivery? Low-immunogenicity enough for repeat dosing? Programmable?
- Does it beat what we already have? — IS621 is the current best-characterised bridge recombinase; any new candidate must demonstrably surpass it.
No single tool answered all four questions. Researchers were left doing manual, ad-hoc assessments with no reproducible scoring framework and no pre-registered standards.
The solution
PEN-ASSEMBLE assembles the four upstream PEN-STACK packages into a single, fully automated nomination pipeline:
QUESTION ANSWERED BY HOW
─────────────────────── ──────────────────────── ────────────────────────────
Is the mechanism right? mech-class v0.5.4 IS110 Tier-A hard gate
(PF01548 + PF02371 Pfam)
Is the structure good? ESMFold + quality gates pLDDT ≥ 90 global,
≥ 95 at active-site
Is it therapeutically pen-score v0.1.3 8-axis PenScore
fit? (IS621 = 0.957) composite metric
Does it beat IS621? Pre-registered Verbatim lockpoint 0.929
comparison (locked before analysis)
The pipeline is end-to-end reproducible: every input, gate, weight, and prediction threshold was committed to GitHub and SHA-256 locked before any candidate was scored.
Who is it for?
| Audience | How they use PEN-ASSEMBLE |
|---|---|
| Wet-lab gene therapy groups | Download the 16 top-ranked designs with synthesis sheets. No re-running needed — the catalog is pre-built. |
| Computational biologists | Use the Designer API to generate and rank new IS110-family designs against the same scoring framework. |
| Tool developers | Benchmark a new genome editor against IS621 and ISCro4 using the 8-axis PenScore framework in pen-score. |
| Reproducibility researchers | Audit the complete pre-registration → execution → deviation log → post-hoc rescoring chain. Every decision is documented. |
How PEN-ASSEMBLE Works
Component diagram
PEN-ASSEMBLE is not a monolith — it is an assembly layer that wires together four specialised packages:
EXTERNAL PACKAGES PEN-ASSEMBLE INTERNALS
═══════════════════ ═══════════════════════════════════════════
┌───────────────────────────────────────┐
┌─────────────────┐ accession IDs │ STRATEGY GENERATION (Steps 01–11) │
│ genome-atlas │──────────────────► │ │
│ v0.7.2 │ 28 enzyme nodes │ A: Domain-Swap B: Ortholog Scan │
│ │ ESM-2 embeddings │ 15 chimeras 992 NCBI IS110s │
│ Knowledge │ │ │
│ graph of │ │ C: Deimmunize D: ProteinMPNN │
│ genome editors │ │ MC substitution Sequence design │
└─────────────────┘ │ on IS621 from IS621 PDB │
│ │
│ 1,041 candidates │
└─────────────────┬─────────────────────┘
│
▼
┌─────────────────┐ IS110 hard gate ┌───────────────────────────────────────┐
│ mech-class │──────────────────► │ TRIAGE PIPELINE (Step 12) │
│ v0.5.4 │ DSB-free confirm │ │
│ │ PF01548+PF02371 │ Gate 1 │ PFAM domain check │
│ Mechanism │ │ │ PF01548 (IS110 transposase) │
│ classifier │ │ │ PF02371 (HTH domain) │
│ IS110 Tier-A │ │ Gate 2 │ ESMFold pLDDT ≥ 90 global │
│ gate │ │ Gate 3 │ Active-site pLDDT ≥ 95 │
└─────────────────┘ │ Gate 4 │ Length 300–400 aa │
│ Gate 5 │ mech-class IS110 Tier-A │
│ │
│ 1,029 designs pass │
└─────────────────┬─────────────────────┘
│
▼
┌─────────────────┐ 8-axis weights ┌───────────────────────────────────────┐
│ pen-score │──────────────────► │ PenScore EVALUATION (Steps 13–16) │
│ v0.1.3 │ IS621 lockpoints │ │
│ │ use-case profile │ S_DSB × 0.24 (DSB avoidance) │
│ Writer scoring │ │ S_Spec × 0.14 (targeting prec.) │
│ framework │ │ S_Cargo × 0.19 (payload capacity) │
│ IS621 = 0.957 │ │ S_Deliv × 0.19 (AAV compat.) │
│ SpCas9 = 0.402 │ │ S_Immuno × 0.09 (immunogenicity) │
└─────────────────┘ │ S_Prog × 0.05 (programmability) │
│ S_Mature × 0.05 (tech. maturity) │
│ S_Energy × 0.05 (ATP independence) │
└─────────────────┬─────────────────────┘
│
▼
┌───────────────────────────────────────┐
│ OUTPUT CATALOG (Steps 17–25) │
│ │
│ 1,029 designs ranked by PenScore │
│ │
│ 16 designs > 0.929 ◄── P1 PASS │
│ 2 designs > 0.957 ◄── secondary │
│ │
│ ┌────────────┐ ┌─────────────────┐ │
│ │ Parquet / │ │ 16 wet-lab │ │
│ │ CSV catalog│ │ synthesis sheets│ │
│ └────────────┘ └─────────────────┘ │
│ ┌────────────┐ ┌─────────────────┐ │
│ │ HTML design│ │ Pre-reg SHA-256 │ │
│ │ browser │ │ lock record │ │
│ └────────────┘ └─────────────────┘ │
└───────────────────────────────────────┘
Pipeline stages in plain language
| Stage | What happens | Key package used |
|---|---|---|
| Strategy generation (Steps 01–11) | Four independent algorithms each produce a batch of IS110-family protein sequences. Strategy A: recombine domain boundaries. Strategy B: screen NCBI. Strategy C: optimise IS621 for low immunogenicity. Strategy D: ask ProteinMPNN for alternative sequences that fold into the same 3D shape. | genome-atlas |
| Triage (Step 12) | Every candidate passes through 5 quality gates. Anything that fails is logged and dropped. 12 of the original 1,041 candidates are removed here. | mech-class |
| PenScore evaluation (Steps 13–16) | Each surviving design is scored on 8 independent axes, then combined into a single PenScore. The IS621 reference lockpoint (0.929, pre-registered) acts as the pass/fail threshold. | pen-score |
| Catalog assembly (Steps 17–25) | The 1,029 scored designs are written to Parquet and CSV, an interactive HTML browser is generated, and 16 wet-lab synthesis sheets are produced for the P1-passing designs. | pen-assemble |
Key design decisions
Why four strategies instead of one? Because no single approach can overcome all limitations. Strategy B (NCBI scan) finds natural diversity but natural proteins are not optimised for human therapy. Strategy C (deimmunization) reduces immune reactivity but doesn't change the sequence radically. Strategy D (ProteinMPNN) redesigns the backbone but stays near IS621. Running all four in parallel and scoring them on the same metric reveals which approach actually wins — and the answer (Strategy D + C) was not obvious before the analysis.
Why pre-registration? Because post-hoc threshold selection is the most common source of irreproducibility in computational biology. Every threshold in this pipeline (0.929, ≥ 5 beaters, Δ ≥ 0.10 for immunogenicity) was publicly committed and SHA-256 locked before a single protein was scored. This means the result — 16 beaters, 5/5 predictions PASS — is a genuine, non-inflated positive finding.
Why build on pen-score instead of just comparing raw axis values? Raw axis values are not commensurable: a 0.05 improvement in S_DSB is not equivalent to a 0.05 improvement in S_Immuno. pen-score uses evidence-based weights derived from clinical AAV gene therapy requirements, so the composite PenScore reflects actual therapeutic relevance, not just mathematical convenience.
The PEN-STACK Pipeline
PEN-ASSEMBLE is the fourth package in a four-paper computational stack. Each package provides critical inputs to the next:
PEN-STACK: Programmable Enzyme Networks
Systematic Tool for Atlas and Knowledge (v0.5.1, 2026)
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ genome-atlas │ │ mech-class │ │ pen-score │ │ pen-assemble │
│ Paper 1 │───►│ Paper 2 │───►│ Paper 3 │───►│ Paper 4 ◄ YOU │
│ v0.7.2 │ │ v0.5.4 │ │ v0.1.3 │ │ v0.5.2 │
│ │ │ │ │ │ │ │
│ Knowledge graph │ │ Mechanism │ │ 8-axis PenScore │ │ Design catalog │
│ 28 enzyme │ │ classifier │ │ framework │ │ 1,029 IS110 │
│ systems │ │ IS110 Tier-A │ │ IS621 = 0.957 │ │ candidates │
│ AUROC 0.9714 │ │ gate (DSB_FREE) │ │ evoCAST = 0.441 │ │ 16 beat IS621 │
│ │ │ F1 = 0.986 │ │ S_Energy axis │ │ 5/5 PASS │
└──────────────────┘ └──────────────────┘ └──────────────────┘ └──────────────────┘
│ │ │ │
│ Provides │ Provides │ Provides │
│ • Accession IDs │ • IS110 gate │ • PenScore formula │ Produces
│ • 28 system nodes │ • DSB-free confirm │ • 8 axis weights │ • Wet-lab sheets
│ • ESM-2 embeddings │ • OOD probe set │ • IS621 lockpoints │ • Design browser
│ • Knowledge edges │ │ • Use-case profiles │ • Pre-reg record
| Package | What it does | Key result | Repo |
|---|---|---|---|
| genome-atlas | Builds a knowledge graph of 28 DNA-editing enzyme systems from UniProt, PDB, and AlphaFold data | AUROC 0.9714 on protein–domain link prediction; 70% accuracy on 10 published therapeutic scenarios | v0.7.2 |
| mech-class | Classifies any genome editor by its biochemical mechanism (DSB nuclease / DSB-free recombinase / transposase) and corrects 31,870 mis-classified IS110-family proteins | Tier-A macro-F1 = 0.9862; IS110 hard gate via PF01548 + PF02371 Pfam domains | v0.5.4 |
| pen-score | Scores any genome editor on 8 axes covering safety, specificity, cargo capacity, delivery compatibility, immunogenicity, programmability, maturity, and energy independence | IS621 scores 0.957; SpCas9 scores 0.402; 7 clinical weight profiles | v0.1.3 |
| pen-assemble (this repo) | Generates, screens, and ranks IS110-family design candidates using genome-atlas accession data, mech-class IS110 gating, and pen-score evaluation | 1,029 designs, 16 beat IS621, 5/5 pre-reg predictions PASS | v0.5.2 |
Key Results at a Glance
| Metric | Value |
|---|---|
| Total candidate designs generated | 1,041 |
| Designs passing all triage gates | 1,029 |
| Designs beating IS621 pre-registered lockpoint (PenScore > 0.929) | 16 (primary, P1 PASS) |
| Designs beating calibrated lockpoint (PenScore > 0.9255) | 32 (secondary analysis) |
| Designs beating IS621 v0.1.2 lockpoint (PenScore > 0.957) | 2 (secondary, 8-axis) |
| Pre-registered predictions passing | 5 / 5 |
| Publication policy | PUBLISH with strong claim |
| Top design PenScore | 0.9673 (IS621_deimmunized_v2) |
| Top design immunogenicity gain over IS621 | +11.8% (S_Immuno: 0.7594 → 0.8777) |
Top-5 Designs (diversity-enforced, P5)
| Rank | Design ID | Strategy | PenScore (v0.1.0) | Notable Feature |
|---|---|---|---|---|
| 1 | IS621_deimmunized_v2_Y255K_... |
C — Deimmunization | 0.9673 | Best immunogenicity: +11.8% over IS621 |
| 2 | C_targeted_001 |
C — Deimmunization | 0.9586 | Targeted deimmunization, fewer substitutions |
| 3 | D8PEA4 |
D — ProteinMPNN | 0.9353 | IS110 ortholog, 314 aa, compact for delivery |
| 4 | D016_IS621_ProtMPNN_T0.1_sample23 |
D — ProteinMPNN | 0.9319 | Backbone redesign on IS621 ESMFold structure |
| 5 | A_007 (diversity-enforced) |
A — Domain-Swap | 0.9209 | Ensures ≥ 3 strategies represented in top-5 |
Four Design Strategies
IS110-family bridge recombinases are a large protein family. Rather than randomly screening sequences, PEN-ASSEMBLE uses four targeted engineering strategies — each attacking the problem from a different angle:
Strategy A · Domain-Swap Chimeras (15 designs)
What: Recombine the catalytic scaffold from IS621 with guide-RNA recognition modules from related IS110 orthologs.
Why: Different orthologs have evolved different RNA-binding geometries. Chimeric fusions may combine IS621's high activity with improved bRNA flexibility.
Outcome: 15 chimeras, none beat IS621 (best PenScore: 0.921). Domain boundaries are tightly conserved — naive chimeras suffer structural penalties.
Strategy B · IS110 Ortholog Discovery (992 designs)
What: Screen all IS110-family sequences in NCBI (>31,000 candidates) through 7 quality gates: PFAM domain verification (PF01548 + PF02371), ESMFold pLDDT ≥ 90 globally and ≥ 95 at active-site residues, length 300–400 aa, and mech-class IS110 Tier-A confirmation.
Why: Natural diversity is enormous. Some orthologs may already score higher than IS621 on delivery (shorter protein → better AAV packaging) or specificity.
Outcome: 992 candidates pass all gates, none beat IS621 (best: 0.917). Natural IS110s are well-optimised for their ecological niche but not for human therapeutics.
Strategy C · Monte Carlo Deimmunization (2 designs)
What: Apply iterative single-substitution Monte Carlo sampling to IS621's sequence, accepting only mutations that reduce MHC-II predicted binding (fewer immune epitopes) while preserving the active-site residues and overall fold stability.
Why: IS621 is a bacterial protein. Human immune systems recognise many of its peptide fragments. Reducing immunogenic peptides is directly relevant to therapeutic safety and repeat-dosing potential.
Outcome: Both deimmunized variants beat IS621. The best — IS621_deimmunized_v2 — improves S_Immuno from 0.759 to 0.878 (+11.8%) while maintaining perfect scores on all other axes. PenScore = 0.9673, rank #1.
Strategy D · ProteinMPNN Backbone Redesign (32 designs)
What: Use ProteinMPNN — a deep learning model for sequence-from-structure design — to generate alternative amino acid sequences compatible with the IS621 ESMFold backbone (PDB: 8WT6). Sequences are conditioned on preserving active-site geometry.
Why: Many valid sequences can fold into the same 3D structure. Some of those alternative sequences may have better expression, stability, or reduced immunogenicity than wild-type IS621.
Outcome: 32 redesigns generated, 14 beat IS621 (PenScore 0.929–0.957). This is the most productive strategy. ProteinMPNN-generated sequences preserve mechanism while improving delivery scores.
PenScore: How Designs Are Ranked
Each candidate design is scored on eight independent axes, all on a [0, 1] scale, then combined into a single composite PenScore. Every IS110-family member scores 1.0 on S_DSB, S_Cargo, S_Prog, and S_Energy by mechanism — so competition happens on the remaining axes.
Current formula (pen-score v0.1.2 — 8-axis)
PenScore = S_DSB × 0.24 + S_Spec × 0.14 + S_Cargo × 0.19
+ S_Deliv × 0.19 + S_Immuno × 0.09 + S_Prog × 0.05
+ S_Mature × 0.05 + S_Energy × 0.05
| Axis | Weight | What it measures | IS621 value |
|---|---|---|---|
S_DSB |
0.24 | Double-strand break avoidance — does the editor cut both DNA strands? IS110 recombinases never do (score = 1.0). CRISPR-Cas9 always does (score = 0.0). | 1.0 |
S_Spec |
0.14 | Guide-RNA target-site specificity — how precisely can the editor be directed to a single genomic location? | 1.0 |
S_Cargo |
0.19 | Payload capacity — how large a DNA insert can the editor integrate? IS110 can handle >50 kb (score = 1.0). Base editors are limited to single nucleotides (score = 0.0). | 1.0 |
S_Deliv |
0.19 | Delivery compatibility — can the protein fit in an AAV capsid? Shorter proteins score higher. IS621 (393 aa) scores above average. | 0.86 |
S_Immuno |
0.09 | Immunogenicity — how many MHC-II epitopes does the protein present? Fewer epitopes → safer for human use → higher score. | 0.759 |
S_Prog |
0.05 | Programmability — can target-site selection be changed by swapping the guide RNA? IS110 uses a bRNA guide (score = 1.0). Fixed-specificity recombinases score 0.0. | 1.0 |
S_Mature |
0.05 | Technology maturity — how many peer-reviewed publications describe this editor? Higher citation counts → score approaching 1.0. | 0.83 |
S_Energy |
0.05 | Energy independence — does the editor require ATP? Walker A/B motif absence → score = 1.0. IS110 is ATP-free. ATPase-driven systems (e.g., evoCAST) score 0.0. | 1.0 |
Pre-registration integrity note: P1 (the primary prediction) used the 7-axis v0.1.0 formula (weights: S_DSB 0.25, S_Spec 0.10, S_Cargo 0.20, S_Deliv 0.15, S_Immuno 0.10, S_Prog 0.15, S_Mature 0.05; no S_Energy axis). The result — 16 designs beat IS621 at 0.929 — is FINAL and cannot be changed retroactively. The v0.1.2 8-axis re-scoring (IS621 = 0.957) is a secondary analysis only. See
RESCORING_v0.1.2.md.
IS621 reference lockpoints:
| Lockpoint | Value | Context |
|---|---|---|
| Verbatim pre-registered | 0.929 | Primary (P1). v0.1.0 formula. Locked before analysis. |
| mech-class v0.5.2 corrected | 0.954 | Secondary. IS110 gate retroactively applied to IS621 itself. |
| pen-score v0.1.2 (8-axis) | 0.957 | Secondary. Current best estimate. Adds S_Energy axis. |
| MHCflurry 2.2.1 recalibrated | 0.9255 | Secondary. 32 beaters under re-calibrated immunogenicity scorer. |
Pipeline Architecture
INPUT: 4 Engineering Strategies
═══════════════════════════════════════════════════════════════════════
Strategy A · Domain-Swap ──────┐
15 IS621-scaffold chimeras │
│
Strategy B · Ortholog Scan ─────┼──► TRIAGE PIPELINE
992 IS110 NCBI candidates │
│ Step 12: ESMFold pLDDT
Strategy C · Deimmunization ────┤ ┌─ Global ≥ 90
Monte Carlo substitution │ └─ Active-site ≥ 95
2 deimmunized IS621 variants │ │
│ Step 13: mech-class IS110 gate
Strategy D · ProteinMPNN ───────┘ PF01548 + PF02371 verified
32 backbone redesigns │
│
1,029 designs pass triage
│
▼
OUTPUT: PEN-SCORE EVALUATION (pen-score v0.1.2)
═══════════════════════════════════════════════
8-axis PenScore per design
IS621 verbatim lockpoint: 0.929 (pre-reg)
IS621 current lockpoint: 0.957 (v0.1.2)
│
├─► 16 designs > 0.929 ◄── P1 PASS (pre-registered)
├─► 2 designs > 0.957
└─► Full 1,029-design catalog
│
┌─────────┼─────────────┐
▼ ▼ ▼
CSV / Parquet HTML Browser 16 Wet-lab
catalog (no server) reference sheets
(Markdown)
Installation
pip install pen-assemble
Or install from source with development extras:
git clone https://github.com/ahmedanees-m/pen-assemble.git
cd pen-assemble
pip install -e ".[dev,docs]"
Requirements: Python ≥ 3.10 · pandas ≥ 2.0 · pyarrow ≥ 14.0 · numpy ≥ 1.24
Quick Start
Load the design catalog
from pen_assemble.catalog import load_catalog, load_p1_beaters, load_top5
# All 1,029 scored designs
df = load_catalog()
print(df[["design_id", "strategy", "pen_score"]].head())
# The 16 designs that beat IS621 (pre-registered P1)
p1 = load_p1_beaters()
print(f"P1 beaters: {len(p1)}") # 16
# Diversity-enforced top-5 (≥3 strategies represented)
top5 = load_top5()
print(top5[["design_id", "strategy", "pen_score"]])
Score any IS110-family design
from pen_assemble.pen_score import pen_score, PenScoreAxes, beats_is621
# All IS110-family designs score 1.0 on mechanism axes by definition.
# The only variable axis for IS110 candidates is S_Immuno (immunogenicity)
# and S_Deliv (protein length / AAV compatibility).
ax = PenScoreAxes(
S_DSB=1.0, # IS110: no double-strand breaks
S_Spec=1.0, # bRNA guide: precise targeting
S_Cargo=1.0, # IS110: large cargo (>50 kb)
S_Deliv=0.92, # 340 aa: compact, AAV-friendly
S_Immuno=0.85, # after Monte Carlo deimmunization
S_Prog=1.0, # bRNA re-targetable
S_Mature=0.83,
S_Energy=1.0, # ATP-free (no Walker A/B motifs)
)
score = pen_score(ax) # composite PenScore
print(f"PenScore: {score:.4f}")
print(f"Beats IS621: {beats_is621(score)}") # True if score > 0.929
print(ax.contributions()) # per-axis breakdown
Codon-optimise for human expression
from pen_assemble.codon import build_expression_orf, gc_content, check_restriction_sites
seq = p1.iloc[0]["protein_sequence"]
orf = build_expression_orf(seq, kozak=True, stop=True)
print(f"ORF length : {len(orf)} bp")
print(f"GC content : {gc_content(orf):.1%}") # target 40–60%
print(f"RE sites : {check_restriction_sites(orf)}") # BsaI, BbsI, etc.
High-level Designer API
from pen_assemble.api import Designer
d = Designer.load()
# Browse and filter the catalog
top = d.select_designs(strategy="C", require_dsb_free=True, top_k=5)
# Run Strategy C deimmunization (requires scaffold FASTA)
variants = d.deimmunize(scaffold_id="IS621", n_variants=50)
# Run Strategy D ProteinMPNN redesign (requires PDB structure)
redesigns = d.redesign_backbone(scaffold_id="IS621", n_designs=25)
Repository Structure
pen-assemble/
│
├── pen_assemble/ # Python package (importable)
│ ├── pen_score.py # PenScore composite formula (8 axes)
│ ├── catalog.py # load_catalog(), load_p1_beaters(), load_top5()
│ ├── codon.py # Human codon optimisation utilities
│ ├── api.py # High-level Designer API
│ ├── cli.py # Command-line entry point (pen-assemble --help)
│ ├── _version.py # Package version (0.5.2)
│ ├── strategies/ # Design generation modules (Steps 01–11)
│ │ ├── domain_swap.py # Strategy A: chimeric fusions
│ │ ├── ortholog_discovery.py # Strategy B: NCBI IS110 screen
│ │ ├── deimmunization.py # Strategy C: Monte Carlo MHC reduction
│ │ └── backbone_redesign.py # Strategy D: ProteinMPNN sequence design
│ ├── triage/ # Multi-gate candidate filtering (Step 12)
│ ├── verification/ # Axis scoring pipeline (Steps 13–16)
│ ├── utils/ # Linker assembly, MHC scoring, PDB parsing
│ └── data/ # YAML configuration files
│
├── catalog/
│ └── release_v0.5.0/ # v0.5.0 FROZEN pre-registration record
│ ├── pen_assemble_catalog.{csv,parquet} # All 1,029 designs
│ ├── p1_beaters_catalog.{csv,parquet} # 16 designs > 0.929
│ ├── p5_top5_catalog.{csv,parquet} # Diversity top-5
│ ├── browser/index.html # Interactive HTML design browser (no server needed)
│ ├── wetlab/ # 16 wet-lab synthesis reference sheets (Markdown)
│ └── validation/ # Pre-registered prediction result JSONs (P1–P5)
│
├── data/ # Rescored and extended catalog outputs
│ ├── catalog_v0.5.1_current.parquet # v0.5.1: 1,029 designs, pen-score v0.1.2 (8-axis)
│ ├── catalog_v0.5.2_current.parquet # v0.5.2: + intrinsic_cargo_mechanism + cell_based_evidence (PEN-COMPARE v3.2)
│ ├── rescore_comparison_v010_v012.csv # Side-by-side v0.1.0 vs v0.1.2 scores
│ ├── rescore_summary_v012.json # Summary statistics (v0.1.2)
│ └── rescore_summary_v052.json # Summary statistics (v0.5.2 schema)
│
├── scripts/ # Numbered pipeline scripts
│ ├── 50_assemble_catalog.py # Builds catalog/ artifacts
│ ├── 51_build_browser.py # Generates interactive HTML browser
│ ├── 52_generate_wetlab_reference.py # Creates 16 wet-lab sheets
│ ├── rescore_v012.py # Re-scores catalog with pen-score v0.1.2
│ └── upgrade_catalog_to_v052.py # Adds v3.2 fields (intrinsic_cargo + cell_based)
│
├── tests/ # 74 pytest tests (Python 3.10 / 3.11 / 3.12)
├── docs/ # Sphinx documentation (furo theme)
│
├── CHANGELOG.md # Version history
├── CITATION.cff # Machine-readable citation metadata
├── CONTRIBUTING.md # Contribution guidelines
├── DESIGN_PROVENANCE.md # Full deviation log (5 documented deviations)
├── RESCORING_v0.1.2.md # Secondary analysis record (8-axis re-scoring)
├── SECURITY.md # Security policy
└── pyproject.toml # Build config, dependencies, coverage settings
Running the Tests
pytest tests/ -v
All 74 tests pass on Python 3.10, 3.11, and 3.12. Coverage is measured on the public API surface (pen_score.py, catalog.py, codon.py) and reported to Codecov. Pipeline-only modules (strategies/, triage/, verification/) require VM-only dependencies (ESM-2, MHCflurry, mech-class extras) and are excluded from CI coverage.
Pre-Registered Predictions
All five predictions were locked (committed and tagged pre-registration-v1.0.0) before any strategy generation script ran. The SHA-256 of the pre-registration YAML is in catalog/release_v0.5.0/validation/all_predictions_summary.json.
| ID | Prediction | Threshold | Result |
|---|---|---|---|
| P1 | ≥ 5 designs beat IS621 verbatim lockpoint | PenScore > 0.929 | ✅ PASS — 16 designs |
| P2 | ≥ 1 design satisfies IS110 mechanism + AAV-compatible | joint gate | ✅ PASS — 1,029 designs |
| P3 | Best Strategy-C design improves S_Immuno over IS621 by ≥ 0.10 | Δ ≥ 0.10 | ✅ PASS — Δ = +0.118 |
| P4 | ≥ 100 Strategy-B candidates with PFAM-verified IS110 domain | count ≥ 100 | ✅ PASS — 992 designs |
| P5 | Top-5 includes designs from ≥ 3 distinct strategies | diversity | ✅ PASS — A, C, D |
Key Deviations from Execution Plan
Full details in DESIGN_PROVENANCE.md.
| # | Deviation | Impact |
|---|---|---|
| D1 | Rosetta gate non-functional — absolute energies, not ΔΔG, cannot be threshold-compared across sequences | Gate auto-passed; pLDDT structural quality proxy used instead |
| D2 | P3 IS621 reference corrected — S_Immuno was placeholder 0.250 in draft; correct value is 0.7594 (MHCflurry) | P3 threshold correctly evaluated from accurate baseline |
| D3 | P5 diversity-enforced — A_007 (0.9209) replaces natural rank-5 D023 (0.9319) | P5 PASS maintained; rank-5 note disclosed |
| D4 | MHCflurry 2.2.1 recalibration — IS621 S_Immuno = 0.7243 under current tool vs 0.7594 at lock-in | Calibrated lockpoint = 0.9255; secondary analysis shows 32 beaters |
| D5 | mech-class ML misclassification — IS110 proteins mis-called as DSB_NUCLEASE by gradient-boosted model alone | Corrected via PFAM domain hard gate (PF01548 + PF02371) in mech-class v0.5.2+ |
Generating the Catalog
The frozen v0.5.0 catalog (catalog/release_v0.5.0/) is never regenerated — it is the pre-registration record. The scripts below produce or update the current catalog:
# Full catalog assembly (produces catalog/release_v0.5.0/ on the VM)
python scripts/50_assemble_catalog.py
# Interactive HTML browser (no server needed — open in any browser)
python scripts/51_build_browser.py
# 16 wet-lab Markdown reference sheets
python scripts/52_generate_wetlab_reference.py
# Re-score with pen-score v0.1.2 (secondary analysis; produces data/)
python scripts/rescore_v012.py --frozen catalog/release_v0.5.0/pen_assemble_catalog.parquet
Part of PEN-STACK
PEN-STACK (Programmable Enzyme Networks — Systematic Tool for Atlas and Knowledge) is a four-paper computational biology pipeline for programmable genome editor discovery and benchmarking.
| Package | Role in the pipeline | Version | Repo |
|---|---|---|---|
| genome-atlas | Foundational knowledge graph of 28 enzyme systems (AUROC 0.9714) | v0.7.2 | |
| mech-class | Biochemical mechanism classifier — IS110 Tier-A gate (F1 = 0.986) | v0.5.4 | |
| pen-score | 8-axis writer scoring framework — IS621 = 0.957, SpCas9 = 0.402 | v0.1.3 | |
| pen-assemble (this repo) | IS110-family design catalog — 1,029 designs, 5/5 predictions PASS | v0.5.2 | |
| PEN-COMPARE (in prep) | Cross-system benchmarking — TrueWriterScore 6-gate classifier | — | — |
Citation
If you use PEN-ASSEMBLE in your work, please cite:
@software{ahmed2026penassemble,
author = {Ahmed, Anees},
title = {{PEN-ASSEMBLE}: Automated Strategy and Scoring Engine
for Molecular Bridge-recombinase Library Engineering},
year = {2026},
version = {v0.5.2},
publisher = {Zenodo},
url = {https://github.com/ahmedanees-m/pen-assemble},
note = {DOI pending Zenodo deposit}
}
Ahmed A. (2026). PEN-ASSEMBLE: Automated Strategy and Scoring Engine for Molecular Bridge-recombinase Library Engineering. v0.5.2. DOI pending.
See CITATION.cff for machine-readable citation metadata (GitHub renders this automatically as a "Cite this repository" widget).
License
MIT © 2026 Anees Ahmed — see LICENSE for details.
Release files for pen-assemble 0.5.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pen_assemble-0.5.2.tar.gz | 100.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pen_assemble-0.5.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 182.1 kB
Release files / pen_assemble-0.5.2.tar.gz
| Download URL | pen_assemble-0.5.2.tar.gz |
|---|---|
| Size | 100.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c75e8da83a61276c9903fac439c044d0495db5f8abb2466577f85973ff4561fd
|
|
BLAKE2b-256 checksum How to use checksums |
e35fae83b690c771fa177ed9594be39d0b5e2dc78ed64cd089c423e24cc019ec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / pen_assemble-0.5.2-py3-none-any.whl
| Download URL | pen_assemble-0.5.2-py3-none-any.whl |
|---|---|
| Size | 81.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
06591b9c8e281591a52110c27ea0e8f81bfde84d21111e8bc6a0dd3c28b869ae
|
|
BLAKE2b-256 checksum How to use checksums |
f4d7ea23c7b10ca37759b88179dcdd8787b8ac80b832bb3eec0205c3a64159fc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|