Quality Flags Reference
Complete reference of all quality flags that SPACER assigns to guide RNA candidates, their trigger conditions, and biological implications.
What Are Quality Flags?
Quality flags are discrete indicators attached to guide RNA candidates that highlight specific sequence or structural concerns. Unlike the assay score (which is a continuous 0.0–1.0 value), flags are categorical warnings that signal a particular type of problem.
Flags are informational — they do not directly affect the assay score or tier classification. A guide can be classified as Excellent-tier while still carrying one or more flags. However, flags provide critical context that researchers should consider when making final guide selection decisions.
Severity Levels
Each flag carries one of two severity levels defined by the Severity enum:
| Severity | Meaning |
|---|---|
| Warning | Minor concern — the spacer may still work well, but the issue should be noted during guide selection. |
| Critical | Significant concern — the spacer is likely to have reduced efficacy. Strong recommendation to choose an alternative. |
IssueCode Reference
| Flag | Severity | Trigger Condition | Biological Impact |
|---|---|---|---|
| LOW_GC | Warning | GC content < 40% | AT-rich spacers bind weakly to the target, reducing specificity and sensitivity. The crRNA-target duplex may dissociate before Cas enzyme activation. |
| HIGH_GC | Warning | GC content > 60% | GC-rich spacers form stable intramolecular structures (hairpins, G-quadruplexes) that compete with target binding. May also cause synthesis issues. |
| POLY_T | Critical | 4+ consecutive T/U nucleotides | TTTT/UUUU acts as a Pol III termination signal, causing premature truncation of the crRNA when expressed from U6 or similar promoters. |
| HOMOPOLYMER | Warning | 5+ consecutive identical bases | Homopolymer runs increase oligo synthesis error rates (insertions/deletions) and can form problematic secondary structures, especially poly-G. |
| BAD_PFS | Warning | Unfavorable Cas13 protospacer flanking sequence | Some Cas13 variants have PFS preferences. An unfavorable PFS reduces collateral cleavage activation efficiency. |
| SELF_FOLD | Warning | Self-folding ΔG < -2 kcal/mol | High self-complementarity indicates the spacer forms stable hairpins, reducing the effective concentration of properly folded crRNA available for target binding. |
| INSUFFICIENT_CONTEXT | Warning | Spacer too close to sequence boundary | ML activity prediction was skipped because the required flanking context (10 nt on each side) could not be extracted. The guide is scored without the ML activity component. |
QualityFlags Struct
Every scored spacer includes a QualityFlags struct with the following fields, providing both raw metrics and the derived issue list:
| Field | Type | Description |
|---|---|---|
| gc_content | f64 (0.0–1.0) | GC content as a fraction |
| gc_optimal | bool | Whether GC falls within the optimal range (default 40–60%) |
| max_homopolymer_run | u8 | Length of the longest consecutive single-base run |
| has_poly_t | bool | Whether a poly-T/U stretch of 4+ was detected |
| pfs_favorable | Option<bool> | PFS status for Cas13 (None for Cas12) |
| self_folding_dg | Option<f64> | Self-folding free energy in kcal/mol (None if structure prediction disabled) |
| insufficient_context | bool | Whether ML scoring was skipped due to boundary proximity |
| issues | QualityIssue[] | List of raised issues, each with severity, code, and human-readable message |
Flag Interactions
Guides can carry multiple flags simultaneously. Certain flag combinations are particularly concerning:
| Flag Combination | Concern | Recommendation |
|---|---|---|
| POLY_T + HOMOPOLYMER | Expected overlap — poly-T is a specific type of homopolymer. The dual flag reinforces the severity. | Avoid for Pol III expression. Consider only if using synthetic crRNAs. |
| HIGH_GC + SELF_FOLD | GC-rich sequences are more prone to stable hairpins. These guides may be substantially impaired. | Strongly avoid. Likely significant secondary structure issues. |
| INSUFFICIENT_CONTEXT + LOW_GC | No ML score and weak target binding — the guide is ranked on heuristics alone and those heuristics are unfavorable. | Avoid. Poor candidates with incomplete scoring. |
| HOMOPOLYMER + HIGH_GC | Often indicates a poly-G run, which forms G-quadruplexes. Among the most problematic guide properties. | Avoid unless no alternatives exist. Check if the run is poly-G specifically. |
Interpreting Flags in Context
Flags should be interpreted alongside the assay score and tier, not in isolation:
- Excellent-tier + 1 flag: Generally safe to proceed. The flag identifies a minor concern that did not significantly impact the overall score. Review the specific flag and make a judgment call.
- Good-tier + 1–2 flags: Usable but warrant closer inspection. The flags explain why this guide did not reach Excellent tier. Prefer unflagged alternatives when available.
- Fair/Poor-tier + multiple flags: These guides have multiple compounding issues. Only use if you must target a specific region and no better alternatives exist.
POLY_T flag deserves special attention. Unlike other flags that indicate probabilistic risks, POLY_T signals a near-certain functional failure for Pol III-expressed crRNAs. It is the only flag with Critical severity. Always check for POLY_T before selecting a guide for promoter-driven expression.