bio-genome-engineering-grna-design

What this skill does

## Version Compatibility

Reference examples tested with: BioPython 1.83+, CRISPOR 5.0+ (web/CLI).

Before using code patterns, verify installed versions match. If versions differ:
- Python: `pip show <package>` then `help(module.function)` to check signatures
- CLI: `<tool> --version` then `<tool> --help` to confirm flags

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

Output depends on inputs more than tool versions: on-target scores are **model-specific and not interchangeable** (a 0.7 Azimuth score is not a 0.7 CRISPRscan score), and the **valid model is set by how the guide is delivered/transcribed**, not by preference. Record the nuclease, the delivery context (U6/lentiviral vs in-vitro T7/RNP), and the reference genome build used for any off-target step.

# Guide RNA Design

**"Design guide RNAs to knock out my gene"** -> Establish the delivery context, scan the target for the nuclease's PAM on both strands, drop guides that fail hard filters, rank survivors with the context-valid on-target model, choose the cut site by exon/transcript biology, and prefer guides whose predicted indel spectrum is frameshift-rich.
- Python: enumerate PAMs and apply hard filters with `Bio.Seq` + `re`; compute a Bae-style microhomology out-of-frame score
- CLI/web: `crispor.py <genome> in.fa out.tsv` aggregates the context-appropriate on-target score + off-target nomination per genome
- Web/code: inDelphi / FORECasT / Lindel for the full repair-outcome distribution

## The Single Most Important Modern Insight -- a guide produces a reproducible indel *distribution*, not "a cut", and knockout success is a property of that distribution

Two facts that naive design ignores and that pass review constantly:

1. **On-target efficiency scores are weak, context-locked predictors.** Rule Set 2, CRISPRscan, and DeepCas9 scores correlate with measured cutting at only **Spearman ~0.4 across realistic contexts** (~0.7 is the ceiling even within one matched context; the *same* guides re-tested in another cell line correlate ~0.37-0.48). Each was trained on one assay -- U6-Pol-III lentiviral vs in-vitro T7 vs RNP -- and **does not transfer** across nuclease, delivery, promoter, cell type, or temperature (Haeussler 2016). Using CRISPRscan (T7/zebrafish-trained) to rank guides for a U6 lentiviral screen is a category error. **Rank to shortlist, then design 3-6 guides and validate** -- never trust the rank as truth.

2. **Efficient editing is not knockout.** A cut yields a *characteristic, reproducible* set of indels (Shen 2018; Allen 2019; Chen 2019); roughly **1/3 of indels are in-frame**, so a 95%-efficient guide can still leave functional protein. Worse, even a confirmed frameshift may not eliminate protein -- translation reinitiation, exon skipping, NMD escape, and transcriptional adaptation rescue ~1/3 of verified knockouts (Smits 2019; Mou 2017; El-Brolosy 2019). So the modern question is **"which guide, at which site, produces a high out-of-frame fraction in an NMD-competent, constitutive transcript region?"** -- couple an *outcome model* to *exon biology*, not just an efficiency score. Verify the knockout at the **protein** level.

## On-Target Score Taxonomy -- each model is valid for ONE context

| Model | Citation | Trained on (valid for) | Notes |
|-------|----------|------------------------|-------|
| Rule Set 1 | Doench 2014 *Nat Biotechnol* 32:1262 | U6 mammalian | superseded; origin of GC/position rules |
| **Rule Set 2 / Azimuth** | Doench/Fusi 2016 *Nat Biotechnol* 34:184 | **U6/lentiviral mammalian KO -- the default for screens & cell lines** | gradient-boosted; best U6 predictor (Haeussler 2016) |
| **CRISPRscan** | Moreno-Mateos 2015 *Nat Methods* 12:982 | **in-vitro T7 / embryo injection -- NOT U6** | wrong tool for lentiviral screens |
| DeepSpCas9 | Kim 2019 *Sci Adv* 5:eaax9249 | SpCas9 mammalian; strong transfer | CNN |
| **DeepHF** | Wang 2019 *Nat Commun* 10:4284 | conditions on the **enzyme variant** (WT, eSpCas9, HF1) | use when using a high-fidelity Cas9 |
| **DeepCpf1 / Seq-deepCpf1** | Kim 2018 *Nat Biotechnol* 36:239 | **AsCas12a** (Deep adds chromatin) | use for Cas12a, not Cas9 |

Treat any score as a **rank-and-shortlist** signal (Spearman ~0.4 across context), never an oracle.

## Nuclease & PAM Taxonomy -- expanding PAM range trades away activity/specificity

| Nuclease | PAM | Guide | Cut | When |
|----------|-----|-------|-----|------|
| **SpCas9 (WT)** | 5'-NGG-3' | 20 nt | blunt, ~3 bp 5' of PAM | default workhorse; most data, most scores |
| SaCas9 | 5'-NNGRRT-3' | ~21 nt | blunt | ~1 kb smaller -> **fits a single AAV** (Ran 2015) |
| SpCas9-NG | 5'-NG-3' | 20 nt | blunt | relaxed PAM; lower activity at many sites (Nishimasu 2018) |
| xCas9 | NG, GAA, GAT | 20 nt | blunt | broad PAM, high specificity, site-variable/modest activity (Hu 2018) |
| SpRY | near-PAMless (NRN>NYN) | 20 nt | blunt | "target anywhere"; pays in activity + off-target breadth (Walton 2020) |
| AsCas12a / LbCas12a | 5'-TTTV-3' (5' PAM) | ~20-23 nt | staggered 5' overhang | AT-rich targets; self-processing crRNA array = easy multiplexing |
| enAsCas12a | expanded (TTTV + non-canonical) | ~20-23 nt | staggered | ~2x activity + broadened range (Kleinstiver 2019) |

Default to WT-SpCas9-NGG; escalate to NG/xCas9/SpRY only when no acceptable NGG sits in the required window, and expect to validate harder (the valid on-target score and the off-target burden both change).

## Decision Tree by Scenario

| Scenario | Recommended | Why |
|----------|-------------|-----|
| Single-gene KO, NGG in an early constitutive exon | SpCas9 + Rule Set 2/Azimuth shortlist -> outcome model -> off-target | frameshift in an NMD-competent exon kills all isoforms |
| In-vitro-transcribed / embryo / RNP injection | score with **CRISPRscan**, apply T7 (not U6) filters | Rule Set 2 is invalid here; TTTT/5'G Pol-III rules do not apply |
| AT-rich target, no good NGG; or multiplex KO | Cas12a (TTTV) + DeepCpf1 | PAM availability and crRNA-array multiplexing, not on-target score, are limiting |
| AAV in-vivo delivery | SaCas9 (NNGRRT) | packaging limit dictates the compact nuclease, which dictates the PAM set |
| Functional/negative-selection screen | tile sgRNAs across the **conserved functional domain** (Shi 2015) | domain indels are LoF even in-frame -> more true nulls than 5'-exon targeting |
| Have ranked candidates, need specificity | -> off-target-prediction | on-target score does not predict specificity |
| Scale to many genes | -> crispr-screens/library-design | pooled library construction |
| Single base change / no DSB tolerated | -> base-editing-design or prime-editing-design | scarless, DSB-free; KO-by-stop also avoids indels |

## Enumerate and Filter Candidate Guides

**Goal:** Return valid candidate spacers for a target, on both strands, dropping guides that cannot work in the chosen delivery context.

**Approach:** Scan both strands for the nuclease's PAM, extract the protospacer upstream (Cas9) or downstream (Cas12a) of each PAM, and apply hard filters -- reject `TTTT` (Pol-III terminator) for U6/H1 expression, flag a missing 5' G for U6 (prepend a G rather than replace the first base), and note GC outside ~40-70% as a soft penalty. Ranking comes from the context-valid model (route to CRISPOR), not from a hand-rolled score.

```python
from Bio.Seq import Seq
import re

GC_MIN, GC_MAX = 0.40, 0.70   # outside this band on-target activity falls off (Doench 2014); soft penalty

def find_guides(sequence, pam='NGG', guide_length=20):
    '''Enumerate SpCas9 (NGG) spacers on both strands; spacer is 5' of the PAM.'''
    seq = sequence.upper()
    guides = []
    for m in re.finditer(r'(?=([ACGT]GG))', seq):
        pos = m.start()
        if pos >= guide_length:
            guides.append({'spacer': seq[pos - guide_length:pos], 'pam': seq[pos:pos + 3],