bio-crispr-screens-library-design— agent skill

Version Compatibility

Reference examples tested with: CRISPOR 5.01+, BioPython 1.83+, pandas 2.2+, numpy 1.26+, Azimuth 2.0+ (Doench 2016), CRISPRon 1.0+ (Xiang 2021), DeepSpCas9 1.0+ (Kim 2019).

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show crispor then help(...) to check signatures
• CLI: crispor.py --help, azimuth --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.

sgRNA Library Design

"Design a CRISPR library for my screen" -> Pick a chemistry (Cas9 KO, CRISPRi, CRISPRa, Cas12a, base or prime editor), score candidate guides for on-target activity and off-target liability, position them relative to gene/TSS, add appropriate controls, lay out the oligo for synthesis, and validate the cloned pool.

• Python: crispor.py (web + CLI) for batch genome-wide guide scoring with CFD+MIT off-target
• Python: azimuth (Microsoft Research) for Rule Set 2 on-target predictions (Brunello-style)
• Python: CRISPRon, DeepSpCas9 for modern deep-learning predictors
• R: crisprDesign (Bioconductor) for integrated annotation-aware design

Library Chemistry Decision Tree

Fails when:

• CRISPRi/a targeting wrong TSS: any TSS without FANTOM5 CAGE evidence is suspect; Horlbeck-rule guides outside ±300 from the true TSS have ~10x lower knockdown.
• Cas9 KO of essential paralogs: single-KO buffering masks ~half of constitutively-expressed essentials (Dede 2020); switch to Cas12a multiplex.
• Base editor over an exon-intron boundary: editing-window bystanders create splice variants instead of the intended SNV.

On-Target Scoring: Algorithmic Taxonomy

Reconciliation: When predictors disagree, prefer the model whose training cell line matches the screen line (DeepSpCas9 was trained primarily on HCT116/HEK293T). For Brunello/TKOv3 selection, Azimuth/Rule Set 2 is sufficient because the library was built with it -- introducing a different scorer creates apples-to-oranges ranking with the original library.

Off-Target Scoring

CFD remains the default for genome-wide library design. Critical pitfall: CFD penalizes only mismatches, not bulges; for ≤1 mismatch + 1-bp bulge off-targets, validate empirically with GUIDE-seq or CIRCLE-seq. CRISPOR aggregates MIT + CFD + Elevation in a single output.

Score and Rank sgRNAs for a Target Gene

Goal: Generate ranked sgRNA candidates for a single gene, jointly scored on on-target activity (Rule Set 2 / Azimuth) and off-target liability (CFD).

Approach: Identify all PAM-adjacent 20-nt protospacers in the target gene's coding sequence, retain only those in the first 5-65% of the protein (constitutive-exon convention from Brunello), filter on GC 30-70% and absence of poly-T (≥4 Ts terminates U6), call Azimuth for on-target and CRISPOR for off-target, and select the top N satisfying both criteria.

import re
import pandas as pd
import numpy as np
from Bio.Seq import Seq

def find_sgrna_candidates(cds_sequence, pam='NGG', guide_length=20):
    '''Return all protospacer candidates with PAM coordinates on + strand.
    Caller must filter by exon position and Azimuth/CFD score.'''
    pam_pattern = re.compile(f'(?=([ACGT]{{{guide_length}}}{pam.replace("N", "[ACGT]")}))')
    candidates = []
    for strand, seq in [('+', cds_sequence), ('-', str(Seq(cds_sequence).reverse_complement()))]:
        for m in pam_pattern.finditer(seq):
            spacer = m.group(1)[:guide_length]
            if 'TTTT' in spacer or spacer.count('G') + spacer.count('C') not in range(6, 15):
                continue
            candidates.append({'spacer': spacer, 'strand': strand,
                               'pos_in_cds': m.start() if strand == '+' else len(seq) - m.start() - 23,
                               'gc_frac': (spacer.count('G') + spacer.count('C')) / guide_length})
    return pd.DataFrame(candidates)

def annotate_exon_position(candidates_df, cds_length):
    '''Filter to protospacers within first 5-65% of CDS (Brunello convention).
    Reason: N-terminal indels truncate protein; very-N-terminal hits alt initiation;
    C-terminal hits miss functional domains (Doench 2016 Nat Biotech).'''
    lo, hi = 0.05 * cds_length, 0.65 * cds_length
    return candidates_df[(candidates_df['pos_in_cds'] >= lo) & (candidates_df['pos_in_cds'] <= hi)].copy()

CRISPRi / CRISPRa TSS Targeting

Goal: Position guides relative to the empirical TSS for maximum knockdown (CRISPRi) or activation (CRISPRa).

Approach: Resolve TSS from FANTOM5 CAGE peaks (highest-ranked peak per gene; fall back to Ensembl/RefSeq if absent), define the modality-specific window, score candidate spacers in that window with Rule Set 2 plus the Horlbeck/Sanson CRISPRi/a-tailored rules, and select 5-6 guides per gene biased toward the window center.

def crispri_window(tss_coord, strand='+'):
    '''Dolcetto convention: -50 to +300 from FANTOM5 highest-rank CAGE peak.
    Reason: dCas9-KRAB knockdown is maximal when the spacer sits 25-75 bp
    downstream of TSS (Horlbeck 2016 eLife); widened to ±300 to cover poorly-
    annotated TSSs and broad CpG-island promoters (Sanson 2018 Nat Comm).'''
    if strand == '+':
        return (tss_coord - 50, tss_coord + 300)
    return (tss_coord - 300, tss_coord + 50)

def crispra_window(tss_coord, strand='+'):
    '''Calabrese convention: -150 to -75 upstream of TSS.
    Reason: dCas9-VP64 (and SAM, SunTag) activate maximally when bound
    just upstream of Pol II loading. Horlbeck CRISPRa uses -400 to -50
    (broader, lower per-guide signal). For SAM, prefer Calabrese tightness;
    for SunTag, Horlbeck width is acceptable.'''
    if strand == '+':
        return (tss_coord - 150, tss_coord - 75)
    return (tss_coord + 75, tss_coord + 150)

Critical nuance: Cell-type-specific TSSs differ from the FANTOM5 consensus in ~15% of genes. For tissue-specific screens (e.g., neuron, hepatocyte), re-derive TSSs from a matched CAGE / GRO-seq / PRO-seq dataset before locking guide positions, or knockdown efficiency drops several-fold. The single most common cause of "weak" CRISPRi hits is mis-positioned guides against an alternative TSS.

Genome-Wide Library Selection

dAUC trajectory (essentiality benchmark): GeCKOv2 < Avana < Brunello/TKOv3 (Doench 2016 + Hart 2017). Moving from 4 to 6 sgRNAs/gene gives diminishing returns; the larger gain is moving from Rule Set 1 to Rule Set 2.

Cost-coverage tradeoff: A 77k-guide Brunello at 500x cells/sgRNA needs 38.5M cells in pool, scalable. A 117k-guide Calabrese at 500x needs 59M cells -- often the deciding factor against CRISPRa for difficult-to-grow lines.

PAM Variants and Alternative Cas Enzymes

Decision rule: If the screen requires every possible TSS position (saturation tiling, dense regulatory dissection), use SpRY despite lower activity; otherwise, NGG is best because the on-target predictors were trained on it.

Control Guides

A genome-wide library should include:

Critical pitfall: Using only AAVS1 as the negative control in a Cas9 screen creates a normalization baseline biased toward "any cut is bad." Always add NTCs or non-essentials so that downstream median normalization and PR-AUC against CEGv2 work without baseline-shift artifacts.

Library Composition for Specialized Screens

Paralog buffering (Cas12a multiplex): Build 4-guide arrays where positions 1-2 target gene A and positions 3-4 target paralog gene B. Inzolia covers ~4,000 paralog pairs at ~72k arrays. Singleton controls (gene A alone, gene B alone) must be included to score genetic interaction = double_KO_LFC - sum(single_KO_LFC).

Base editor screens (Sanson GRACE-style): Tile NGG-adjacent spacers across exons; ensure editing window (positions 4-8 from PAM-distal end) lands inside coding exons; flag bystander Cs/As in the window for downstream interpretation. Restrict to 50-90% editing efficiency a priori (filter out predicted low-efficacy guides) -- see [[base-editing-analysis]].

Tiling / regulatory dissection: Dense (every 5-10 bp) CRISPRi or CRISPRa guides across the candidate region; CRISPRi has broader signal width (good for enhancer discovery) but Cas9-indel tiling has sharper resolution (good for pinpointing critical bases). Pair with CRISPR-SURF deconvolution.

Oligo Design for Pooled Synthesis

Goal: Generate the final oligo sequence (full length 60-200 nt) ready for chip-based synthesis (Twist 12K/92K/244K, Genscript, Agilent).

Approach: Add subpool PCR primers (so multiple sublibraries can share a synthesis array), the BsmBI/Esp3I overhang for golden-gate cloning into LentiGuide-Puro (Addgene 52963) or LentiCRISPRv2, and append the tracrRNA scaffold if the array length permits.

def build_oligo(spacer, vector='lentiGuide-Puro', subpool_idx=None):
    '''Construct final oligo for pooled synthesis.

    LentiGuide-Puro / LentiCRISPRv2 use BsmBI (Esp3I) with these overhangs:
        forward: 5'-CACCG[spacer]-3'
        reverse: 5'-AAAC[revcomp(spacer)]C-3'
    For chip synthesis, the spacer is flanked by subpool-specific PCR primers.'''
    subpool_fwd = {
        1: 'GGAAAGGACGAAACACCG',   # subpool 1 forward primer + BsmBI overhang
        2: 'GAGGCACTGGGCAGGTACCG',
    }.get(subpool_idx, 'GGAAAGGACGAAACACCG')
    scaffold_short = 'GTTTAAGAGCTATGCTGGAAACAGCATAGCAAG'  # truncated tracr for short oligos
    oligo = subpool_fwd + spacer + scaffold_short
    if len(oligo) > 200:
        raise ValueError(f'Oligo length {len(oligo)} exceeds Twist 244K limit (200 nt)')
    return oligo

Subpool design: Twist 92K can be partitioned into multiple sublibraries via subpool primers; each sub-PCR amplifies its subpool, allowing one synthesis batch to serve several screens. Typical subpool size: 10k-20k oligos.

Library QC After Cloning

Plasmid pool sequencing convention: 200-500 reads per sgRNA before any biology (i.e. 15-40M reads for a 77k Brunello). This is the baseline against which all downstream depletion is computed; sequencing the plasmid is non-negotiable.

Failure Modes

Wrong TSS in CRISPRi/a library

Trigger: Using Ensembl/RefSeq TSS instead of empirical CAGE peak for genes with broad or non-canonical promoters. Mechanism: dCas9-KRAB knockdown is maximal within ±100 bp of the actual Pol II loading site; canonical annotation can be off by 1-10 kb. Symptom: "Easy" essentials (RPS, RPL, EIF) show normal dropout but newer genes don't; library validates poorly against CEGv2. Fix: Re-derive TSS from FANTOM5 CAGE highest-rank peak; for tissue-specific lines, use matched CAGE or GRO-seq.

Library skew from PCR bias during amplification

Trigger: Amplifying the cloned plasmid pool with too many PCR cycles (>20) or with high-GC-bias polymerase. Mechanism: GC-extreme guides amplify nonlinearly; high-GC guides dominate, low-GC guides drop out. Symptom: Gini >0.2 on plasmid pool; sgRNAs with GC <30% systematically depleted. Fix: Cap PCR at 15 cycles; use Q5 or NEBNext Ultra II (low-bias); sequence at 500x post-amp to confirm Gini.

Oligo-synthesis dropouts in low-complexity guides

Trigger: Chip-synthesis errors at homopolymer runs or guides starting with GGGG. Mechanism: Synthesis chemistry has higher error rate at low-complexity regions; missing oligos cannot be cloned. Symptom: Specific guides absent from plasmid pool despite no design-rule violation. Fix: Re-design replacement guides; for production runs, request 2-3x synthesis depth so dropouts are buffered.

Polyclonality from high MOI

Trigger: Infection at MOI >0.5 to "save cells." Mechanism: Poisson math: at MOI 0.3, 26% of infected cells carry ≥1 sgRNA, 4% carry ≥2; at MOI 0.5, 39% of infected cells carry ≥1, 9% carry ≥2. Symptom: Hits include neutral genes that co-infect with true essentials. Fix: MOI 0.3 strict; titer Cas9-positive cells specifically; re-check by qPCR of integration.

Wrong control proportion

Trigger: <100 non-targeting controls in a 70k library. Mechanism: Null distribution for normalization and FDR rests on the NTC variance; too few NTCs yields unstable median and inflated FDR. Symptom: Erratic gene-level p-values; MAGeCK FDR fluctuates wildly between runs. Fix: ~1% of library (500-1,000) NTCs; supplement with non-essential-gene controls.

Quantitative Thresholds

Common Errors

References

• Doench JG et al. 2014. Nat Biotechnol 32:1262. Rule Set 1.
• Doench JG et al. 2016. Nat Biotechnol 34:184. Rule Set 2, CFD, Brunello/Avana libraries.
• Sanjana NE et al. 2014. Nat Methods 11:783. GeCKOv2.
• Hart T et al. 2017. G3 7:2719. TKOv3 library; CEGv2/NEGv1 reference essentiality gene sets.
• Sanson KR et al. 2018. Nat Commun 9:5416. Dolcetto + Calabrese libraries; CRISPRi/a TSS rules.
• Horlbeck MA et al. 2016. eLife 5:e19760. CRISPRi/a design rules; Horlbeck v2 library.
• Kim HK et al. 2019. Nat Biotechnol 37:657. DeepSpCas9.
• Xiang X et al. 2021. Nat Commun 12:3238. CRISPRon.
• Tycko J et al. 2019. Mol Cell 73:1273. Bassik library design.
• DeWeirdt PC et al. 2021. Nat Biotechnol 39:94. enAsCas12a optimization.
• Bayle JH et al. 2024. Nat Commun 15:3375. Inzolia / in4mer paralog library.
• Dede M et al. 2020. Genome Biol 21:262. Paralog buffering invisible to Cas9 single-KO.
• Joung J et al. 2017. Nat Protoc 12:828. Genome-wide library screen protocol.
• Chen S et al. 2015. Cell 160:1246. Original GeCKO design conventions.

Related Skills

• crispr-screens/screen-qc - Validate library skew, Gini, replicate correlation
• crispr-screens/mageck-analysis - Analyze screens run with the designed library
• crispr-screens/combinatorial-screens - Cas12a multiplex / paralog-pair library design
• crispr-screens/base-editing-analysis - GRACE-style base-editor library design
• crispr-screens/prime-editing-screens - PRIDICT2-optimized pegRNA libraries
• crispr-screens/copy-number-correction - Filter amplicon-driven artifacts in cancer-cell-line screens