---
title: 'needLR: Long-Read SV Annotation Tool'
url: https://www.emergentmind.com/topics/needlr
type: topic
---

# needLR: Long-Read SV Annotation Tool

Searching arXiv for the primary paper and closely related long-read SV annotation work to ground the article.
needLR is a structural variant (SV) annotation tool for long-read sequencing data that supports filtering and prioritization of candidate pathogenic SVs by combining population allele frequencies, genomic-context annotations, and gene-phenotype associations [2512.08175]. It is designed for long-read–derived SVs of at least \(50\) bp and uses a pre-computed or user-supplied population reference to assign frequencies at population scale. In evaluation using population data from 500 presumably healthy individuals across nine test cases with known pathogenic SVs, needLR assigned allele frequencies to over \(97.5\%\) of detected SVs and reduced the average number of novel genic SVs to \(121\) per case while retaining all known pathogenic variants [2512.08175].

## 1. Concept and scope

needLR addresses a practical problem in long-read SV analysis: raw callsets are large, while disease-oriented interpretation typically requires rapid reduction to a smaller set of novel or rare, genically relevant candidates. The tool operationalizes this by annotating each query SV with population allele frequency, overlap with genomic features, and overlap with OMIM-associated genes [2512.08175].

The input model is constrained. Query SV calls are provided as one or more VCF files of long-read–derived SVs \(\ge 50\) bp, produced by a supported caller such as Sniffles v2.5.2. The records must carry the caller’s `FILTER=PASS` flag and lie on chromosomes \(1\)–\(22\), \(X\), \(Y\), or \(MT\). The same reference FASTA must be used both at SV-calling time and during downstream annotation. Population support is provided through a pre-merged VCF of 500 Oxford Nanopore–sequenced 1KGP samples, corresponding to 1,000 haplotypes, or through a user-supplied custom population VCF generated in the same manner via Sniffles and Truvari [2512.08175].

This design places needLR in a specific niche: long-read SV interpretation rather than de novo SV discovery. A plausible implication is that its principal value lies not in altering the upstream caller’s sensitivity, but in reorganizing downstream evidence so that rarity, context, and disease relevance can be inspected jointly.

## 2. Pipeline architecture and implementation

needLR is implemented in bash and depends on Truvari v4.2.2, BEDTools v2.31.1, and BCFtools v1.19. Source code, documentation, and pre-computed population allele frequency data are available under an MIT license [2512.08175].

Its workflow is a four-stage pipeline:

| Stage | Tool | Function |
|---|---|---|
| 1 | BCFtools | Filter and normalize raw query VCFs |
| 2 | Truvari v4.2.2 | Merge query SVs against the population VCF |
| 3 | BCFtools | Extract genotype counts and compute allele frequencies |
| 4 | BEDTools intersect | Overlay SVs with genomic annotation tracks |

In stage 1, BCFtools filters and normalizes the raw query VCFs, retaining only SVs \(\ge 50\) bp with `FILTER=PASS` on canonical chromosomes. In stage 2, Truvari merges each query SV against the population VCF using user-adjustable matching parameters that account for alignment imprecision in long reads. The matching criteria include sequence similarity threshold, size similarity tolerance, and reference-distance tolerance; examples given are at least \(70\%\) sequence similarity, \(\pm 30\%\) size similarity, and \(\pm 500\) bp reference distance. The merged VCF records link a query SV to its population-level allele cluster [2512.08175].

In stage 3, BCFtools extracts genotype counts from the merged VCF to compute overall and superpopulation-specific allele frequencies, performs Hardy–Weinberg equilibrium filtering, and labels low-quality genotypes. In stage 4, BEDTools intersect overlays the query SV coordinates against annotation tracks including genes, exons, repeats, segmental duplications, centromeres, telomeres, high-confidence regions, and assembly gaps [2512.08175].

The paper summarizes this as a streamlined workflow of BCFtools \(\rightarrow\) Truvari \(\rightarrow\) BCFtools \(\rightarrow\) BEDTools. It also states that, with pre-computed population backends, one genome is processed in approximately 20 minutes on a single thread [2512.08175].

## 3. Population allele-frequency estimation

After Truvari merging, each merged SV group yields genotype counts

\[
n_{00} = \text{number of homozygous-reference genotypes}
\]

\[
n_{01} = \text{number of heterozygotes}
\]

\[
n_{11} = \text{number of homozygous-alternate genotypes}
\]

from which needLR computes the total number of called alleles

\[
N_{\text{total}} = 2 \cdot (n_{00} + n_{01} + n_{11})
\]

and the number of alternate alleles

\[
N_{\text{alt}} = 2 \cdot n_{11} + n_{01}.
\]

The overall allele frequency is then

\[
f = \frac{N_{\text{alt}}}{N_{\text{total}}}.
\]

Superpopulation-specific frequencies \(f_s\) are computed in the same way within each 1KGP superpopulation, reported as `AF_AFR`, `AF_EAS`, `AF_EUR`, `AF_AMR`, and `AF_SAS` [2512.08175].

Multi-allelic SVs are handled by splitting records with more than one ALT allele into separate biallelic records prior to counting, ensuring that each allele’s frequency is computed independently. SV records failing Hardy–Weinberg equilibrium, using a default \(\chi^2\) threshold of \(p < 1 \times 10^{-6}\), or carrying low-quality genotype flags from BCFtools such as `DP <10`, are marked as low quality and removed from frequency calculations [2512.08175].

The paper distinguishes two frequency-based categories. A novel SV is a query SV whose merged cluster has \(f=0\) in the population VCF:

\[
f = 0 \Rightarrow \text{SV is called “unique” to the query sample.}
\]

A rare SV is one with allele frequency below a user-specified threshold, with default

\[
f < 0.01 \Rightarrow \text{“rare”.}
\]

Users may specify other thresholds, such as \(f < 0.005\) for “very rare” [2512.08175].

## 4. Annotation model and prioritization logic

needLR overlays each SV against 12 annotation tracks. These include genes and exons from GENCODE v45 canonical transcripts, OMIM-associated genes, short tandem repeats and variable-number tandem repeats from Vamos, RepeatMasker elements, segmental duplications from GIAB stratifications v3.3, centromeres, pericentromeres with \(+5\) Mbp flanks, telomeres defined as 5 Mbp chromosome ends, high-confidence regions from GIAB DEFRABB, and assembly gaps from UCSC [2512.08175].

The annotation layer is intended to support prioritization rather than to produce a single composite pathogenicity score. needLR tags SVs overlapping exons of OMIM-annotated genes, but the paper explicitly states that the tool itself does not assign a composite pathogenicity score. Instead, it proposes combining three factors: rarity, genomic context tier, and known gene–phenotype links via OMIM IDs in the BED files [2512.08175].

An example prioritization logic is given:

- **Tier 1**: \(f = 0\) and overlaps an OMIM exon  
- **Tier 2**: \(f < 0.01\) and overlaps an OMIM exon  
- **Tier 3**: \(f < 0.01\) and overlaps a non-OMIM exon  

This suggests a filtering regime in which frequency is the first partition, genic and exonic status the second, and OMIM association the third. A plausible implication is that needLR is optimized for analyst-driven triage workflows in which a modest candidate list is preferable to an opaque scalar ranking.

## 5. Evaluation and empirical behavior

The control cohort consisted of 500 healthy Oxford Nanopore genomes. In that setting, needLR assigned allele frequencies to more than \(97.5\%\) of all long-read SVs detected in a typical genome, implying that fewer than \(2.5\%\) could not be matched to the control VCF. The resulting allele-frequency spectrum was highly skewed: more than \(80\%\) of SVs had \(f < 0.01\), with a long tail of common SVs extending to approximately \(f \approx 0.50\) [2512.08175].

The validation set comprised nine test cases with known pathogenic SVs. All nine positive-control SVs—five deletions, three insertions, and one inversion—were retained when applying the default needLR filters of novel plus genic, yielding a true-positive rate of \(100\%\). At the same time, needLR reduced the burden of novel genic SVs to an average of 121 per sample, with mean \(=121\) and range approximately \(85\)–\(134\) [2512.08175].

The paper also frames performance in standard classification terms. With \(TP\), \(FP\), \(TN\), and \(FN\) defined conventionally,

\[
\text{Sensitivity (Recall)} = \frac{TP}{TP + FN}
\]

\[
\text{Specificity} = \frac{TN}{TN + FP}
\]

\[
\text{Precision (PPV)} = \frac{TP}{TP + FP}.
\]

For the nine-sample validation,

\[
TP = 9,\quad FN = 0 \Rightarrow \text{Sensitivity} = \frac{9}{9+0} = 1.00 \; (100\%).
\]

The paper further reports that common SVs filtered were approximately \(97\%\), giving specificity of approximately \(0.97\), while precision was approximately

\[
\frac{9}{9 + 483 - 9} \approx 0.018.
\]

It notes that users typically apply additional context-based filters to improve this precision [2512.08175]. This is important interpretively: needLR is presented as an effective reduction and annotation layer, but not as a complete end-point classifier of pathogenicity.

## 6. Outputs, assumptions, and prospective extensions

needLR produces three principal outputs. The tabular output `sample_needLR.tsv` contains one line per query SV and columns including `CHR`, `POS`, `END`, `SVTYPE`, `SVLEN`, `REFCNT`, `ALTCNT`, `AF_overall`, superpopulation-specific allele frequencies, and Boolean-style context fields such as `In_GENCODE`, `In_OMIM`, `In_STR`, and `In_Segdup`. The VCF output `sample_needLR.vcf.gz` is a VCF v4.2 file whose INFO fields carry the same annotations along with tags such as `AF`, `AC`, `AN`, and `HWE_flag`. A log file summarizes filtering statistics, stage-wise SV counts, and parameter settings [2512.08175].

The current implementation makes several assumptions. Breakend SVs and calls greater than 1 Mbp are excluded by default because these were enriched for false positives. Sex-chromosome allele counts may be mis-called in homozygous versus hemizygous states by Sniffles2. The method currently relies on a single SV caller, Sniffles2, although other callers may be integrated in future versions. Finally, the population frequency reference derives from 500 individuals in 1KGP; while diverse, this may underrepresent very rare population-specific SVs [2512.08175].

The paper lists several extensions: support for additional long-read SV callers such as cuteSV, SVIM, and pbsv; trio and pedigree mode for de novo SV identification; compatibility with additional assemblies including T2T-CHM13; and integration of machine-learning–based pathogenicity predictors such as a CADD-SV score together with richer regulatory and promoter annotation from ENCODE and Roadmap [2512.08175]. These are not part of the present system, but they delineate the intended trajectory of the framework.

In summary, needLR is a long-read SV annotation and filtering pipeline centered on population-scale frequency estimation, genomic-context overlap, and OMIM-linked prioritization. Its principal empirical result is that a population-matched, long-read–specific annotation backend can retain known pathogenic SVs while reducing the candidate burden to a tractable number of novel genic events [2512.08175].

Source: https://www.emergentmind.com/topics/needlr