Author: Ruining Dong
Date: 2026-04-28

# svaRetro Quick Overview

Ruining Dong

#### 2026-04-28

# Contents

# 1 Introduction

This vignette outlines a workflow of detecting retrotransposed transcripts (RTs) from Variant Call Format (VCF) using the `svaRetro` package.

# 2 Installation

The `svaRetro` package can be installed from Bioconductor as follows:

    if (!requireNamespace("BiocManager", quietly = TRUE)) {
      install.packages("BiocManager")
    }
    BiocManager::install("svaRetro")

# 3 Using GRanges for structural variants: a breakend-centric data structure

This package uses a breakend-centric event notation adopted from the `StructuralVariantAnnotation` package. In short, breakends are stored in a GRanges object with strand used to indicate breakpoint orientation, where breakpoints are represented using a `partner` field containing the name of the breakend at the other side of the breakend. This notation was chosen as it simplifies the annotations of RTs which are detected at breakend-level.

# 4 Workflow

## 4.1 Loading data from VCF

VCF data is parsed into a `VCF` object using the `readVCF` function from the Bioconductor package `VariantAnnotation`. Simple filters could be applied to a `VCF` object to remove unwanted calls. The `VCF` object is then converted to a `GRanges` object with breakend-centric notations using `StructuralVariantAnnotation`. More information about `VCF` objects and breakend-centric GRanges object can be found by consulting the vignettes in the corresponding packages with `browseVignettes("VariantAnnotation")` and `browseVignettes("StructuralVariantAnnotation")`.

    library(StructuralVariantAnnotation)
    library(VariantAnnotation)
    library(svaRetro)

    RT_vcf <- readVcf(system.file("extdata", "diploidSV.vcf", package = "svaRetro"))

    RT_gr <- StructuralVariantAnnotation::breakpointRanges(RT_vcf,
      nominalPosition = TRUE
    )
    head(RT_gr)

Note that `StructuralVariantAnnotation` requires the `GRanges` object to be composed entirely of valid breakpoints. Please consult the vignette of the `StructuralVariantAnnotation` package for ensuring breakpoint consistency.

## 4.2 Identifying Retrotransposed Transcripts

The package provides `rtDetect` to identify RTs using the provided SV calls. This is achieved by detecting intronic deletions, which are breakpoints at exon-intron (and intron-exon) boundaries of a transcript. Fusions consisting of an exon boundary and a second genomic location are reported as potential insertion sites. Due to the complexity of RT events, insertion sites can be discovered on both left and right sides, only one side, or none at all.

    library(TxDb.Hsapiens.UCSC.hg19.knownGene)
    library(dplyr)
    hg19.genes <- TxDb.Hsapiens.UCSC.hg19.knownGene

    RT <- rtDetect(RT_gr, hg19.genes, maxgap = 10, minscore = 0.8)

The output is a list of `GRanges` object consisting of two sets of `GRanges` calls, `insSite` and `junctions`, containing candidate insertion sites and exon-exon junctions respectively. Candidate insertion sites are annotated by the source transcripts and whether exon-exon junctions are detected for the source transcripts. RT junction breakends are annotated by the UCSC exon IDs, corresponding transcripts, and NCBI gene symbols.

    RT$SKA3
    #> $junctions
    #> GRanges object with 14 ranges and 17 metadata columns:
    #>                                  seqnames    ranges strand | paramRangeID                    REF         ALT      QUAL      FILTER               sourceId                partner      svtype     svLen      insSeq    insLen       event    HOMLEN      exon                                      txs         exons gene_symbol
    #>                                     <Rle> <IRanges>  <Rle> |     <factor>            <character> <character> <numeric> <character>            <character>            <character> <character> <numeric> <character> <numeric> <character> <numeric> <integer>                                   <list>        <list>      <list>
    #>    MantaDEL:245251:6:6:0:0:0_bp2       13  21729832      - |           NA TCTGCAACAGATACAAATAA..           T       999        PASS MantaDEL:245251:6:6:.. MantaDEL:245251:6:6:..         DEL      -542                     0        <NA>         1    589252 ENST00000298260.8_4,ENST00000314759.6_11        589252        SKA3
    #>    MantaDEL:245251:5:8:0:0:0_bp2       13  21732061      - |           NA                      G       <DEL>       999        PASS MantaDEL:245251:5:8:.. MantaDEL:245251:5:8:..         DEL     -2110        <NA>         0        <NA>         2    589253 ENST00000298260.8_4,ENST00000314759.6_11        589253        SKA3
    #>    MantaDEL:245251:5:9:0:0:0_bp2       13  21734038      - |           NA                      A       <DEL>       525        PASS MantaDEL:245251:5:9:.. MantaDEL:245251:5:9:..         DEL     -1776        <NA>         0        <NA>         4    589254 ENST00000298260.8_4,ENST00000314759.6_11        589254        SKA3
    #>   MantaDEL:245251:7:10:0:0:0_bp2       13  21735929      - |           NA                      T       <DEL>       539        PASS MantaDEL:245251:7:10.. MantaDEL:245251:7:10..         DEL     -1802        <NA>         0        <NA>         1    589255 ENST00000298260.8_4,ENST00000314759.6_11        589255        SKA3
    #>   MantaDEL:245251:4:11:0:0:0_bp2       13  21742127      - |           NA                      A       <DEL>       999        PASS MantaDEL:245251:4:11.. MantaDEL:245251:4:11..         DEL     -6112        <NA>         0        <NA>         2    589256 ENST00000298260.8_4,ENST00000314759.6_11        589256        SKA3
    #>                              ...      ...       ...    ... .          ...                    ...         ...       ...         ...                    ...                    ...         ...       ...         ...       ...         ...       ...       ...                                      ...           ...         ...
    #>    MantaDEL:245251:5:9:0:0:0_bp1       13  21732261      + |           NA                      A       <DEL>       525        PASS MantaDEL:245251:5:9:.. MantaDEL:245251:5:9:..         DEL     -1776        <NA>         0        <NA>         4    589253 ENST00000298260.8_4,ENST00000314759.6_11        589253        SKA3
    #>   MantaDEL:245251:7:10:0:0:0_bp1       13  21734126      + |           NA                      T       <DEL>       539        PASS MantaDEL:245251:7:10.. MantaDEL:245251:7:10..         DEL     -1802        <NA>         0        <NA>         1    589254 ENST00000298260.8_4,ENST00000314759.6_11        589254        SKA3
    #>   MantaDEL:245251:4:11:0:0:0_bp1       13  21736014      + |           NA                      A       <DEL>       999        PASS MantaDEL:245251:4:11.. MantaDEL:245251:4:11..         DEL     -6112        <NA>         0        <NA>         2    589255 ENST00000298260.8_4,ENST00000314759.6_11        589255        SKA3
    #>    MantaDEL:245251:3:4:0:0:0_bp1       13  21742538      + |           NA                      A       <DEL>       999        PASS MantaDEL:245251:3:4:.. MantaDEL:245251:3:4:..         DEL     -3939        <NA>         0        <NA>         2    589256 ENST00000298260.8_4,ENST00000314759.6_11 589256,589257        SKA3
    #>    MantaDEL:245251:2:3:0:0:0_bp1       13  21746642      + |           NA                      T       <DEL>       999        PASS MantaDEL:245251:2:3:.. MantaDEL:245251:2:3:..         DEL     -3870        <NA>         0        <NA>         2    589258 ENST00000298260.8_4,ENST00000314759.6_11 589258,589259        SKA3
    #>   -------
    #>   seqinfo: 25 sequences (1 circular) from GRCh37.p13 genome
    #>
    #> $insSite
    #> GRanges object with 0 ranges and 18 metadata columns:
    #>    seqnames    ranges strand | paramRangeID         REF         ALT      QUAL      FILTER    sourceId     partner      svtype     svLen      insSeq    insLen       event    HOMLEN  exons    txs rtFound rtFoundSum gene_symbol
    #>       <Rle> <IRanges>  <Rle> |     <factor> <character> <character> <numeric> <character> <character> <character> <character> <numeric> <character> <numeric> <character> <numeric> <list> <list>  <list>  <logical>      <list>
    #>   -------
    #>   seqinfo: 25 sequences (1 circular) from GRCh37.p13 genome

# 5 Visualising breakpoint pairs via circos plots

One way of visualising RT is by circos plots. Here we use the package `circlize` to demonstrate the visualisation of insertion site and exon-exon junctions.

To generate a simple circos plot of RT event with SKA3 transcript:

    library(circlize)
    rt_chr_prefix <- c(RT$SKA3$junctions, RT$SKA3$insSite)
    GenomeInfoDb::seqlevelsStyle(rt_chr_prefix) <- "UCSC"
    pairs <- breakpointgr2pairs(rt_chr_prefix)
    pairs

To see supporting breakpoints clearly, we generate the circos plot according to the loci of event.

    circos.initializeWithIdeogram(
      data.frame(
        V1 = c("chr13", "chr11"),
        V2 = c(21720000, 108585000),
        V3 = c(21755000, 108586000),
        V4 = c("q12.11", "q24.3"),
        V5 = c("gneg", "gpos50")
      )
    )
    circos.genomicLink(
      as.data.frame(S4Vectors::first(pairs)),
      as.data.frame(S4Vectors::second(pairs))
    )

    circos.clear()

# 6 SessionInfo

    sessionInfo()
    #> R version 4.6.0 Patched (2026-04-24 r89963)
    #> Platform: aarch64-apple-darwin23
    #> Running under: macOS Tahoe 26.3.1
    #>
    #> Matrix products: default
    #> BLAS:   /Library/Frameworks/R.framework/Versions/4.6/Resources/lib/libRblas.0.dylib
    #> LAPACK: /Library/Frameworks/R.framework/Versions/4.6/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.1
    #>
    #> locale:
    #> [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
    #>
    #> time zone: America/New_York
    #> tzcode source: internal
    #>
    #> attached base packages:
    #> [1] stats4    stats     graphics  grDevices utils     datasets  methods   base
    #>
    #> other attached packages:
    #>  [1] circlize_0.4.18                          dplyr_1.2.1                              TxDb.Hsapiens.UCSC.hg19.knownGene_3.22.1 GenomicFeatures_1.64.0                   AnnotationDbi_1.74.0                     svaRetro_1.18.0                          StructuralVariantAnnotation_1.28.0       VariantAnnotation_1.58.0                 Rsamtools_2.28.0                         Biostrings_2.80.0                        XVector_0.52.0                           SummarizedExperiment_1.42.0              Biobase_2.72.0                           MatrixGenerics_1.24.0                    matrixStats_1.5.0                        rtracklayer_1.72.0                       GenomicRanges_1.64.0                     Seqinfo_1.2.0                            IRanges_2.46.0                           S4Vectors_0.50.0                         BiocGenerics_0.58.0                      generics_0.1.4                           BiocStyle_2.40.0
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] tidyselect_1.2.1         blob_1.3.0               bitops_1.0-9             fastmap_1.2.0            RCurl_1.98-1.18          GenomicAlignments_1.48.0 XML_3.99-0.23            digest_0.6.39            lifecycle_1.0.5          pwalign_1.8.0            KEGGREST_1.52.0          RSQLite_2.4.6            magrittr_2.0.5           compiler_4.6.0           rlang_1.2.0              sass_0.4.10              tools_4.6.0              yaml_2.3.12              knitr_1.51               S4Arrays_1.12.0          bit_4.6.0                curl_7.1.0               DelayedArray_0.38.0      abind_1.4-8              BiocParallel_1.46.0      grid_4.6.0               colorspace_2.1-2         tinytex_0.59             cli_3.6.6                rmarkdown_2.31           crayon_1.5.3             otel_0.2.0               httr_1.4.8               rjson_0.2.23             DBI_1.3.0                cachem_1.1.0             stringr_1.6.0            assertthat_0.2.1         parallel_4.6.0
    #> [40] BiocManager_1.30.27      restfulr_0.0.16          vctrs_0.7.3              Matrix_1.7-5             jsonlite_2.0.0           bookdown_0.46            bit64_4.8.0              magick_2.9.1             jquerylib_0.1.4          glue_1.8.1               codetools_0.2-20         shape_1.4.6.1            stringi_1.8.7            GenomeInfoDb_1.48.0      BiocIO_1.22.0            UCSC.utils_1.8.0         tibble_3.3.1             pillar_1.11.1            htmltools_0.5.9          BSgenome_1.80.0          R6_2.6.1                 evaluate_1.0.5           lattice_0.22-9           png_0.1-9                cigarillo_1.2.0          memoise_2.0.1            bslib_0.10.0             Rcpp_1.1.1-1.1           SparseArray_1.12.0       org.Hs.eg.db_3.23.1      xfun_0.57                pkgconfig_2.0.3          GlobalOptions_0.1.4