Prepare splicejam data environment from a TxDb annotation package

Usage

splicejamDataFromTxDb(
  txdb,
  ann_lib = NULL,
  tx2geneDF = NULL,
  detectedTx = NULL,
  detectedGenes = NULL,
  filesDF = NULL,
  color_sub = NULL,
  verbose = FALSE,
  ...
)

Arguments

txdb

TxDb object, typically loaded from a Bioconductor annotation package such as TxDb.Mmusculus.UCSC.mm10.knownGene.

ann_lib

character string naming an installed Bioconductor organism annotation package (e.g. "org.Mm.eg.db"). Must correspond to the same organism as txdb. No cross-validation is performed.

When NULL as default, it will try to generate a suitable annotation name using the txdb metadata 'Organism', using the first letter of the first two words in the organism name. This process works for most common species, but will fail for things like E. coli K12.

tx2geneDF

data.frame, default NULL.

When NULL, ann_lib is used to derive tx2geneDF.
When provided, it is used and ann_lib is ignored.
- The 'gene_id' values must exactly match: names(GenomicFeatures::genes(txdb, single.strand.genes.only=FALSE)).
- The 'gene_name' column will be used to name gene data.
- The 'transcript_id' values must exactly match values 'tx_name' from: GenomicFeatures::transcripts(txdb).

detectedTx

character vector of transcript_id values representing detected (expressed) transcripts. When NULL (default), all transcripts in the TxDb are used. Values not found in tx2geneDF$transcript_id are silently dropped.

detectedGenes

character vector of gene_name (SYMBOL) values representing genes of interest. When NULL (default), genes are derived from detectedTx via tx2geneDF. Values not found in tx2geneDF$gene_name are silently dropped.

filesDF

optional data.frame with at minimum colnames "sample_id", "url", "type". Stored in the returned environment unchanged.

color_sub

optional named character vector of R colors, whose names should match filesDF$sample_id. When filesDF is provided but color_sub is NULL, colors are derived automatically using colorjam::group2colors().

verbose

logical whether to print verbose output.

...

additional arguments are ignored.

Value

environment containing:

flatExonsByGene — GRangesList with non-overlapping exons per gene, named by gene_name.
flatExonsByTx — GRangesList with non-overlapping exons per transcript, named by transcript_id.
tx2geneDF — data.frame with colnames "transcript_id", "gene_id", "gene_name", subset to detected transcripts and genes.
detectedTx — character vector of retained transcript IDs.
detectedGenes — character vector of retained gene names.
filesDF — included when provided (otherwise absent).
color_sub — included when provided or derived from filesDF.

Details

This function is an alternative to sashimiDataConstants() for users who prefer to supply a Bioconductor TxDb annotation package such as 'TxDb.Mmusculus.UCSC.mm10.knownGene', rather than a GTF file.

It calls makeTx2geneFromTxdb() to build the transcript-to-gene data.frame 'tx2geneDF', then derives exonsByTx, cdsByTx, flatExonsByTx, and flatExonsByGene from the TxDb using the same flattenExonsBy() machinery as the GTF-based workflow.

Subsetting logic

When detectedTx and/or detectedGenes are provided, they are used to subset the full annotation:

detectedTx is intersected with tx2geneDF$transcript_id. Providing detectedTx also limits the available genes via tx2geneDF.
detectedGenes is intersected with tx2geneDF$gene_name. Providing detectedGenes also limits the available transcripts via tx2geneDF.
Both filters are applied simultaneously; the resulting tx2geneDF is the source of truth from which detectedTx and detectedGenes are re-derived.
When neither is provided, all transcripts and genes in the TxDb are used.

Examples

if (FALSE) { # \dontrun{
# Prepare TxDb for mouse mm10 genome
system.time({
   sjenv_txdb <- splicejamDataFromTxDb(
      txdb=TxDb.Mmusculus.UCSC.mm10.knownGene::TxDb.Mmusculus.UCSC.mm10.knownGene,
      detectedGenes=unique(sjenvtest$tx2geneDF$gene_name),
      filesDF=sjenvtest$filesDF,
      ann_lib="org.Mm.eg.db")
})
# 8 to 12 seconds to prep the environment

# optionally display progress bar
progressr::handlers(global=TRUE)
system.time({
   splicejamFigure(sjenv_txdb,
      gene="Gria1",
      geneAxisSize=8,
      use_memoise=TRUE)
})

# Use subset of transcript_id which happen
# to be compatible with sjenvtest on mm10.
# Note the flat gene exons still used all
# transcripts. Rebuild from TxDb to resolve.
use_detectedTx <- subset(sjenvtest$tx2geneDF,
   gene_name %in% 'Gria1')$transcript_id
system.time({
   splicejamFigure(sjenv_txdb,
      gene="Gria1",
      geneAxisSize=8,
      minJunctionScore=100,
      detectedTx=use_detectedTx,
      use_exon_range=c("exon17", "exon20"),
      use_memoise=TRUE)
})
} # }