bio-genome-annotation-ncrna-annotation

What this skill does

## Version Compatibility

Reference examples tested with: Infernal 1.1.4+, Rfam 15+ (CM library), tRNAscan-SE 2.0.12+, barrnap 0.9+, ARAGORN 1.2+, pandas 2.2+.

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

The **Rfam release version** drives results (Rfam 15 has ~4,200+ families); record it. The downloaded `Rfam.cm` ships pre-calibrated, so only `cmpress` is needed before `cmscan`. If code throws an error, introspect the installed tool and adapt rather than retrying.

# Non-Coding RNA Annotation

**"Find non-coding RNAs in my genome"** -> Scan an assembly for structured ncRNA families using covariance models (sequence + secondary structure jointly), with specialist detectors for tRNA and the expression boundary for miRNA/lncRNA.
- CLI: `cmscan --cut_ga --rfam --nohmmonly --fmt 2 --clanin Rfam.clanin Rfam.cm genome.fa` (Infernal), `tRNAscan-SE -B genome.fa`

## The Single Most Important Modern Insight -- ncRNA Homology Is Structure-Conserved, Not Sequence-Conserved

Protein annotation rides on sequence/ORF signal; structured-ncRNA annotation rides on **base-pairing covariation**. A G-C pair can become A-U across evolution while the *structure* is preserved - both positions mutate together (compensatory substitution). To a sequence-only tool these look like two mismatches; to a covariance model (a profile SCFG, the Rfam/Infernal engine) the *correlated* change is the strongest possible evidence of homology. Three consequences:

1. **BLAST is categorically the wrong tool for structured ncRNA.** Two RNase P RNAs may share <60% identity (BLAST sees noise) yet have unmistakable shared structure. Use Infernal covariance models, not BLAST. R-scape (Rivas 2017 *Nat Methods* 14:45) is the statistical test for whether a structure is *actually* conserved - it found no significant covariation support for the proposed structures of HOTAIR, SRA, and Xist-RepA.
2. **A homology-based annotation is a recall floor, never a count.** A CM can only exist for a family whose structure is conserved across enough divergent sequences to seed a model - so fast-evolving and lineage-specific ncRNAs are invisible *by design*, and the floor drops further for organisms far from the curation spotlight. Report "at least N conserved-family loci," never "the genome has N ncRNAs."
3. **Whole classes need expression evidence, not genomic search.** miRNAs are hypotheses until small-RNA-seq confirms the Dicer processing signature; lncRNAs are not annotatable by homology at all (no conserved structure) - they are transcript catalogs. Use specialist tools where the biology has a sharper signal (tRNAscan-SE, miRDeep2-with-reads).

## Tool Taxonomy

| RNA class | Tool | Citation | Method |
|-----------|------|----------|--------|
| tRNA | tRNAscan-SE 2.0 | Chan 2021 *NAR* | isotype-specific Infernal CMs + pseudogene/high-confidence logic |
| rRNA (fast) | barrnap | Seemann (software) | nhmmer HMM profiles; kingdom flag; prokaryotic-pipeline default |
| rRNA (structure-aware) | Infernal + Rfam SSU/LSU | Nawrocki 2013 | CM; better boundaries / unusual taxa |
| tmRNA (+ bacterial tRNA) | ARAGORN | Laslett 2004 | heuristic cloverleaf + tmRNA models |
| miRNA | miRDeep2 (+ small-RNA-seq) | Friedländer 2012 | Dicer-processing model on read pileups |
| C/D, H/ACA snoRNA | snoscan / snoReport | Lowe 1999 | guide-target complementarity / SVM |
| Everything else structured | Infernal `cmscan` vs Rfam | Nawrocki 2013 | covariance models; the general engine |
| lncRNA | StringTie + CPC2/CPAT/FEELnc | - | transcript assembly + coding-potential, NOT CM search |

RNAmmer is the legacy rRNA tool (license-encumbered, HMMER2) - use barrnap instead unless reproducing old annotations.

## Decision Tree by Scenario

| Scenario | Recommended | Why |
|----------|-------------|-----|
| Prokaryote, fast complete annotation | barrnap + tRNAscan-SE `-B`/ARAGORN + Infernal/Rfam | what Bakta/Prokka/PGAP wrap |
| tRNA is the question | always tRNAscan-SE 2.0 (not Rfam's generic tRNA model) | isotype, pseudogene, intron, high-confidence logic |
| rRNA, speed matters | barrnap | seconds per genome |
| Broad ncRNA sweep of a new genome | Infernal `cmscan` vs full Rfam.cm (GA + clan competition) | structure-aware, family-typed |
| miRNA | demand small-RNA-seq; miRDeep2 | genomic hairpin prediction is unreliable |
| lncRNA | transcript assembly + coding-potential | not structurally conserved; no CM |
| Claim a conserved structure | R-scape covariation test (report power) | thermodynamic fold != selected structure |
| Bacterial AMR/CRISPR arrays | -> prokaryotic-annotation / CRISPRCasFinder | array detection is a separate tool class |

## Infernal / cmscan (the General ncRNA Engine)

```bash
# Rfam ships pre-calibrated; press it once, then scan (cmscan = many models vs one genome)
cmpress Rfam.cm
cmscan -Z <dbsize_Mb> --cut_ga --rfam --nohmmonly \
       --tblout out.tblout --fmt 2 --clanin Rfam.clanin \
       Rfam.cm genome.fa > out.cmscan
grep -v " = " out.tblout > out.deoverlapped.tblout   # drop within-clan overlaps
```

- `--cut_ga` (gathering threshold): the single most important correctness flag. Each family has a curator-set, per-family bit-score threshold; a fixed E-value would treat a 70-nt tRNA model and a 2,900-nt LSU model identically, which is wrong. **Overriding GA to "find more" imports the false positives the curator deliberately excluded.**
- `--nohmmonly` forces full CM (structure-aware) scoring so scores are GA-comparable.
- `-Z <dbsize_Mb>` = total_residues x 2 / 1e6 (both strands), making E-values run-comparable.
- `--fmt 2 --clanin Rfam.clanin` + the `grep -v " = "` deoverlap step is **mandatory, not a nicety**: clans group related families (the tRNA models, SSU/LSU rRNA), so one locus hits several models and the raw table double-counts (a 16S locus becomes "several rRNA genes").

## tRNAscan-SE 2.0

```bash
tRNAscan-SE -B -o trna.out -f trna.ss -m trna.stats --gff trna.gff3 genome.fa   # bacterial
```

Modes: `-E` eukaryotic (default), `-B` bacterial, `-A` archaeal, `-G` general (mixed/metagenome), `-M mammal`/`-M vert` mitochondrial, `-O` organellar (disables pseudogene checking). **Domain choice is not cosmetic** - the wrong mode mis-scores and miscalls isotypes; there is no auto-detect. Report the **high-confidence set**, not raw hits (raw counts include pseudogenes/SINEs and can be 2-10x inflated in eukaryotes). The pseudogene flag is reliable in eukaryotic nuclear genomes but false-positive-prone in organelles/odd mito-tRNAs (truncated arms read as "decayed") - hence `-O`/`-D`.

## barrnap (rRNA)

```bash
barrnap --kingdom bac genome.fa > rrna.gff3   # bac | arc | euk | mito
```

Reports partial rRNA at contig edges as `(partial)`. **rDNA copy number from an assembly is essentially always wrong** - near-identical rRNA arrays collapse in short-read assemblies, so the annotated count is a floor (off by orders of magnitude in eukaryotes); use long reads or read depth for true copy number.

## Parsing and Combining ncRNA Calls with Python

**Goal:** Merge Infernal and tRNAscan-SE into one ncRNA annotation, preferring the specialist for tRNA.

**Approach:** Parse the deoverlapped Infernal table, drop its tRNA rows (tRNAscan-SE is the authority for tRNA), and combine with the tRNAscan-SE high-confidence set; keep evidence provenance per class.

```python
import pandas as pd

def parse_infernal_tbl(tbl_file):
    rows = []
    with open(tbl_file) as f:
        for line in f:
            if line.startswith('#'):
                continue
            p = line.split()
            if len(p) < 18:
                continue
            rows.append({'rfam_name': p[1], 'seqid': p[3], 'strand': p[11],
                         'score': float(p[16]), 'evalue': float(p[17])})
    df = pd.DataFrame(rows)
    return df[~df['rfam_name'].str.co