bio-crispr-screens-library-design

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:

• CLI: crispor.py --help from the crisporWebsite clone
• Python: Azimuth has no console script; call azimuth.model_comparison.predict(...)

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; guides positioned against the wrong TSS lose most of their knockdown.
• Cas9 KO of essential paralogs: single-KO buffering hides paralog-redundant essentials (42% of constitutively expressed genes never score, 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 on synthetic targets integrated in HEK293T). For Brunello 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 reports both the MIT (Hsu) and CFD guide specificity scores 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: search -50 to +300 around the FANTOM5 highest-rank CAGE peak.
    Reason: Sanson 2018 found +25 to +75 nt downstream of the TSS optimal for CRISPRi,
    so rank candidates toward that band; the search is relaxed outward to fill the
    per-gene guide quota when poorly-annotated TSSs leave too few candidates.'''
    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 v2 CRISPRa uses -550 to -25
    (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,435 paralog pairs within ~49k arrays. Singleton controls (gene A alone, gene B alone) must be included to score genetic interaction = doubleKOLFC - sum(singleKOLFC).

Base editor screens (tiling-library design): 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 ready for chip-based synthesis. Vendor limits differ: Twist oligo pools cap at ~300 nt per oligo with no fixed pool size, GenScript's 92K format spans 20-170 nt, and Agilent OLS 244K spans 30-230 nt.

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')
    # First 33 nt of the Chen 2013 sgRNA(F+E) optimized scaffold. NOTE: lentiGuide-Puro (#52963)
    # and lentiCRISPRv2 (#52961) carry the ORIGINAL scaffold; F+E belongs to lentiCRISPRv2-Opti (#163126).
    scaffold_short = 'GTTTAAGAGCTATGCTGGAAACAGCATAGCAAG'
    oligo = subpool_fwd + spacer + scaffold_short
    if len(oligo) > 200:
        raise ValueError(f'Oligo length {len(oligo)} exceeds the 200 nt design budget; check the vendor limit')
    return oligo

Subpool design: A large synthesis pool 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 all cells are infected and 4% carry >=2 sgRNAs (14% of the infected fraction); at MOI 0.5, 39% are infected and 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. Sci Adv 5:eaax9249. DeepSpCas9.
• Xiang X et al. 2021. Nat Commun 12:3238. CRISPRon.
• Tycko J et al. 2019. Nat Commun 10:4063. Off-target toxicity mitigation in CRISPR screens.
• DeWeirdt PC et al. 2021. Nat Biotechnol 39:94. enAsCas12a optimization.
• Esmaeili Anvar N et al. 2024. Nat Commun 15:3577. 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.
• Shalem O et al. 2014. Science 343:84. Original GeCKO genome-scale knockout library design.

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 - 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