NavVerma/Guide_Scrambler

Guide_Scrambler

Non-targeting control (NTC) guide generator for Cas13d. Generates scrambled or universal spacers, applies a full intrinsic-flag battery, predicts crRNA fold integrity, and screens off-targets against transcriptome-aware databases plus optional NCBI core_nt. Designed so an NTC behaves like a real Cas13d guide minus its target.

Current version: 2.4.0 (June 2026). See CHANGELOG below.

Quick start (for users)

1. 1.Open <https://navverma-guide-scrambler.hf.space/>
2. 2.Pick mode (Scrambled or Universal), set parameters
3. 3.Choose hosts to avoid (Human + E. coli pre-selected; add more via the autocomplete chip input)
4. 4.Choose off-target databases (Ensembl/RefSeq transcripts + NCBI core_nt; both default on)
5. 5.Click Generate candidates — passing guides appear in a sortable table
6. 6.Click a row to see the spacer self-fold SVG, DR+spacer fold SVG, full metrics, design flags, and per-organism host risk
7. 7.Tick candidates → Submit selected to BLAST → expand any hit to view the 3-line alignment pileup

Modes

• —Scrambled — permutes a user-supplied input sequence. Preserves length and mono-nucleotide composition (optional dinucleotide preservation). Each scramble must additionally clear a fold-similarity gate (MFE delta, base-pair distance, mean p(unpaired) delta) so the scrambled crRNA folds similarly to the input.
• —Universal — de novo random spacers with user-controlled length and target GC fraction. Default GC = 50% (Cas13d-ideal).

Both modes feed candidates through the same gates:

1. 1.DR integrity (priority gate) — folds the candidate together with the Cas13d WT DR. Only ok passes; warn and disrupted are rejected as of v2.3.
2. 2.Spacer self-fold (hard filter, v2.3) — fold_mfe >= -0.5 kcal/mol. Strongly self-structured spacers are rejected.
3. 3.Intrinsic flags — length (22-30 nt optimal), U6 terminator (>=4 consecutive T = hard fail), GC content (40-60% pass / 30-70% warn / outside = fail), restriction-site hits (BbsI, BsaI, BsmBI, EcoRI, BamHI, NotI, XbaI, SalI, HindIII, XhoI), G-quadruplex motifs, Wessels-Konermann 2020 position-preference PWM.
4. 4.Fold-similarity (scrambled only) — tri-axial comparison of the spacer-self fold against the input.
5. 5.Host pre-filter BLAST — over-generates 3x, kicks off async BLAST against user-selected hosts, auto-filters HIGH risk and deprioritizes MEDIUM.
6. 6.User-driven BLAST — second pass on user-selected candidates against a broader user-configurable organism list. v4 effective-mismatch ladder with Wessels 2020 seed window (positions 15-21, 1-based, DR-proximal). Two backends in parallel: RefSeq transcripts (fast, transcript-aware) + NCBI core_nt (slow, comprehensive). Hits deduped across backends.

Rescue logic (scrambled mode)

If no scramble passes every gate within the attempt budget, the app surfaces:

• —Best-failing scramble — closest to passing, with every failure shown.
• —Minimal-edit closest-passing variant — greedy point edits to the best-failing candidate that resolve hard failures while preserving as much of the scramble as possible. Edited positions are highlighted in red on the sequence and listed individually.

Note: rescue + best-failing candidates do NOT pass through the v2.3 hard filters (DR-OK + MFE >= -0.5). They are diagnostic outputs intended to show "the closest we could get" when nothing strictly passes.

API endpoints

Source layout

app.py                  FastAPI server, routes, candidate evaluation pipeline
ntc_generator.py        NTC core: shuffle, evaluate, rank, rescue. Hard filter lives here too.
guide_flags.py          Intrinsic flag battery (ported from Cas13d Access)
crrna_fold.py           DR-integrity gate via ViennaRNA (ported from Cas13d Access)
fold_similarity.py      Spacer-self fold + tri-axial similarity scoring (scrambled mode)
blast_remote.py         NCBI remote BLAST submission, polling, parsing, v4 mismatch classifier
ensembl_transcripts.py  Transcript-aware BLAST backend (uses NCBI refseq_rna under the hood; v2.4)
taxid_lookup.py         NCBI taxonomy autocomplete
static/
  index.html            Frontend shell + Section 1/2/3 markup
  app.js                All UI logic: state, table rendering, fold SVG renderer, BLAST polling
  style.css             Cas13d Access-aligned palette (#1f694c accent, Inter + JetBrains Mono)
  favicon.svg
Dockerfile              HF Spaces Docker SDK
requirements.txt        Python deps (FastAPI, uvicorn, pydantic, ViennaRNA)
.dockerignore
.gitignore

Developer guide

Local development

git clone https://huggingface.co/spaces/NavVerma/Guide_Scrambler
cd Guide_Scrambler
pip install -r requirements.txt
uvicorn app:app --reload --port 7860

Open <http://localhost:7860>. Frontend is static — edits to static/*.js and static/*.css are picked up on reload without restarting uvicorn.

ViennaRNA: required for the fold-similarity and DR-integrity gates. If unavailable locally, those features degrade gracefully (return unavailable flag) and the rest of the app still runs.

Editing in the HF Space directly

The HF Space has a built-in web editor at:

<https://huggingface.co/spaces/NavVerma/Guide_Scrambler/tree/main>

You can edit any file in the browser. Saving commits to main. The Space rebuilds automatically (typically 60-120 s). Watch progress in the Logs tab. If the build fails, the previous version stays live.

Deploying from a local workspace

The build/commit pipeline used during development is:

# /home/user/workspace/build_commit_ndjson.py
# Reads all files under guide_scrambler/, posts a single commit to HF Spaces
# via the NDJSON commit endpoint. Uses the saved write token.
python build_commit_ndjson.py guide_scrambler

The HF write token is stored as a custom credential; the script reads it from the credential preset.

Version bumps

app.py defines APP_VERSION. Bump it on every deploy and update the /api/health response. CHANGELOG below should also be updated.

State persistence

Frontend state (candidates, selected seqs, hosts, backend selection, last BLAST job) is stored in localStorage under the key guide_scrambler.state.v1. Schema changes should bump that suffix to invalidate stale sessions cleanly.

Backend state (BLAST jobs, host pre-filter jobs) is in-memory only. Restart the Space and active jobs are lost. The frontend handles this by detecting an unknown job_id on resume and falling back to a "start fresh" banner.

How the host pre-filter BLAST works

1. 1.POST /api/generate returns immediately with candidates + a host_filter_job_id
2. 2.Backend kicks off a thread that calls the BLAST classifier against the over-generated pool
3. 3.Frontend polls /api/generate/host_filter every 5 s, applies risk badges to rows in place
4. 4.Candidates marked HIGH are filtered out of the final passing list; MEDIUM are deprioritized

This async pattern exists because HF Spaces has a 30 s edge-proxy timeout. Long-running synchronous handlers get killed mid-request.

How the user-driven BLAST works

Same pattern: POST /api/blast/start returns a job_id, frontend polls /api/blast/status/{job_id} until done. Two backends (Ensembl/RefSeq + NCBI corent) run in parallel per host; results are merged with dedup by `(accession, hstart, hend, hstrand)`, preferring transcript-source hits when both fire on the same locus.

Common edit recipes

• —Change a flag threshold — edit guide_flags.py. Each flag is a flag_* function returning a FlagDict. The level (pass/warn/fail) drives the candidate's n_fail and n_warn counters.
• —Change the hard filter rules — search for the comment Hard filter requested 2026-05-29 in ntc_generator.py and app.py. Two redundant filters by design.
• —Add a new BLAST backend — implement a module mirroring ensembl_transcripts.search_transcripts(spacer, taxid) returning the same hit-dict shape. Wire into app.py's blast job runner alongside the Ensembl + NCBI calls.
• —Change the fold SVG style — edit renderFoldSvg in static/app.js. Pure inline SVG, no library.
• —Adjust the v4 mismatch ladder — blast_remote.py:classify_hit plus the wobble weight (0.5) at the top of the file. The same ladder applies to both backends.

Changelog

v2.4.0 (2026-06-01)

• —Dual off-target backends: RefSeq transcripts (transcript-aware, fast) + NCBI core_nt (comprehensive). Both default on, user-toggleable.
• —New ensembl_transcripts.py module (uses NCBI refseq_rna under the hood after Ensembl REST was confirmed to lack a short-sequence endpoint).
• —BLAST results: click-to-expand 3-line alignment pileups with seed-window tint, mismatch coloring (red), wobble coloring (amber), per-hit source pill (RefSeq / NCBI).
• —Top-10 hits per organism with "Show all N" disclosure.

v2.3.0 (2026-05-29)

• —Hard filters: fold_mfe >= -0.5 kcal/mol AND DR integrity = OK only.
• —Inline SVG fold visualization in expanded panels (spacer self-fold + DR+spacer crRNA fold with arc connectors).
• —BLAST results UI redesigned in Cas13d Access pattern: per-spacer cards with chip strip + expandable per-organism detail.
• —"Copy structure" button next to each fold SVG.

v2.2.0 (2026-05-29)

• —Section 2 refactored from card stack to sortable table with sticky header.
• —Click-to-expand inline detail panel (one open at a time).
• —Toolbar: "Copy sequences" + "Copy as TSV" (Alt-click for selected-only).
• —Per-row copy icon for individual spacer sequences with toast confirmation.
• —Live host-risk updates wired to table rows by data-seq.

v2.1.0 (2026-05-28)

• —Bug fixes: taxid autocomplete kwarg mismatch, stale BLAST results on regenerate, reload banner showing for completed jobs.

v2.0.0 (2026-05-28)

• —Upfront host selection + number of guides in Section 1 with Cas13d Access organism-chip UX.
• —Async host pre-filter BLAST: over-generate 3x, BLAST in background, live-update card risk badges as results arrive.
• —Section 3 BLAST host input pre-populated from Section 1.
• —localStorage persistence with smart reload + resume.
• —Cas13d Access visual parity: Inter + JetBrains Mono, accent green #1f694c, ink ramp, two-column metric cards.

v1.x (April-May 2026)

• —Initial release: scrambled + universal modes, intrinsic flags, fold-similarity, NCBI BLAST off-target screen, rescue logic.

References

• —Konermann S. et al., Transcriptome Engineering with RNA-Targeting Type VI-D CRISPR Effectors. Cell 173, 665-676 (2018).
• —Wessels H.-H. & Konermann S., Massively parallel Cas13 screens reveal principles for guide RNA design. Nat Biotechnol 38, 722-727 (2020).
• —Méndez-Mancilla A. et al., Chemically modified guide RNAs enhance CRISPR-Cas13 transcript depletion. Cell Chem Biol 29, 311-318 (2022).
• —Wessels H.-H. et al., Prediction of on-target and off-target activity of CRISPR-Cas13d guide RNAs using deep learning (TIGER). Nat Biotechnol 42, 1430-1440 (2024).