Prepare sashimi plot required data

Prepare sashimi plot required data, deriving data objects as needed

Usage

sashimiDataConstants(
  gtf = NULL,
  txdb = NULL,
  tx2geneDF = NULL,
  exonsByTx = NULL,
  cdsByTx = NULL,
  detectedTx = NULL,
  detectedGenes = NULL,
  flatExonsByGene = NULL,
  flatExonsByTx = NULL,
  filesDF = NULL,
  color_sub = NULL,
  envir = NULL,
  empty_uses_farrisdata = TRUE,
  use_memoise = TRUE,
  verbose = FALSE,
  ...
)

Arguments

gtf, txdb, tx2geneDF, exonsByTx, cdsByTx

objects used to define the overall set of genes, transcripts, and associated exons and CDS exons. See this function description for more detail. Notes:

gtf can be a local file, in which case it will be loaded from its current path without copying to the current directory, as long as file.exists(gtf) is TRUE, which also means it would not have the prefix "file://". However, when it has the prefix "file://" it will use curl::curl_download() which will copy it to the current directory. In either case, when other files are derived, such as tx2gene or txdb, those files are stored in the current directory.
tx2geneDF is a data.frame with at minimum two columns: gene_name and transcript_id. It is possible to customize these column names, however it is easiest to use these defaults.
exonsByTx and cdsByTx are GRangesList objects, and they are used to derive flatExonsByTx and flatExonsByGene when those objects are not already provided. Also, exonsByTx and cdsByTx are derived using gtf or txdb when necessary to derive flatExonsByTx and flatExonsByGene.

detectedTx, detectedGenes, flatExonsByGene, flatExonsByTx

objects used to derive a specific subset of gene-exon models using only detected transcripts or genes. See this function description for more detail.

detectedTx and detectedGenes are character vectors.
flatExonsByTx and flatExonsByGene are GRangesList, where each GRanges element contains disjoint (non-overlapping) ranges. When not provided, they are derived from exonsByTx and cdsByTx, which also requires tx2geneDF and either gtf or txdb.

filesDF

data.frame, default NULL. This argument is optional, and when supplied it will be included in the output environment. The data.frame must contain colnames:

'sample_id': character name of the sample or sample group, where multiple files for the same sample or sample group all use the same character string.
'url': character with URL or URI link to file or web resource relevant to each data type.
'type': character with type of data, recognizing:
- 'bw': bigwig coverage file
- 'junction': BED or bigBed file, ideally formatted as BED12 format. Scores higher than 1000 in bigBed are recognized in the 'name' column when the 'name' is entirely numeric value.
- 'coverage_gr': character name of coverage values supplied in an object covGR whose values() contain columns of NumericList coverages.

color_sub

character vector of colors, whose names match 'sample_id' in filesDF when supplied. This argument is optional.

envir

environment where data will be prepared, or when envir=NULL a new environment will be created and returned.

empty_uses_farrisdata

logical default TRUE, whether to use data from the Github R package 'jmw86069/farrisdata' if no data is supplied to this function. This behavior is intended to make it easy to use farrisdata to recreate the Sashimi plots in that publication. Note: When the 'farrisdata' R package is not installed, this argument is automatically set to FALSE.

use_memoise

logical default TRUE, whether to use memoise to cache intermediate data files for exons, flattened exons, transcript-gene data, and so on. This mechanism reduces time to render sashimi plots that re-use the same gene. All memoise cache folders are named with "_memoise".

verbose

logical indicating whether to print verbose output.

...

additional arguments are ignored.

default_gene

character string indicating the default gene to use for the initial R-shiny figure.

Value

environment that contains the required data objects for splicejam sashimi plots. Note that the environment itself is updated during processing, so the environment does not need to be returned for the data contained inside it to be updated by this function.

filesDF (if provided)
flatExonsByGene, flatExonsByTx
gtf (if relevant)
detectedGenes, detectedTx
tx2geneDF
default_gene (if relevant)
color_sub (if provided)
cdsByTx, exonsByTx
txdb (if relevant)

Details

This function performs a subset of steps performed by sashimiAppConstants(), focusing only on data required for gene-exon structure.

The sashimiAppConstants() defines other Shiny-specific sections, specifically the 'aboutExtra' and other guides text.

Data derived by this function sashimiDataConstants():

txdb: TranscriptDb object used to derive exonsByTx and cdsByTx if either object does not already exist. If txdb is not supplied, it is derived from gtf using txdbmaker::makeTxDbFromGFF().
tx2geneDF: data.frame with colnames: "transcript_id" and "gene_name".
gtf: character path to a GTF/GFF/GFF3 file, suitable for txdbmaker::makeTxDbFromGFF(). The gtf is only used if tx2geneDF or exonsByTx are not supplied. Note that when gtf points to a remote server, the file is copied to the current working directory for more rapid use. If the file already exists in the local directory, it is re-used.
exonsByTx: GRangesList object, named by "transcript_id", containing all exons for each transcript. It is derived from txdb if not supplied; and names should match tx2geneDF$transcript_id.
cdsByTx: GRangesList object, named by "transcript_id", containing only CDS (protein-coding) exons for each transcript. It is derived from txdb if not supplied; and names should match tx2geneDF$transcript_id.
detectedTx: character vector of tx2geneDF$transcript_id values, representing a subset of transcripts detected above background. See definedDetectedTx() for one strategy to define detected transcripts. If detectedTx does not exist, it is defined by all transcripts present in tx2geneDF$transcript_id. Note this step can be the rate-limiting step in the preparation of flatExonsByTx.
detectedGenes: character vector of values that match tx2geneDF$gene_name. If it is not supplied, it is inferred from detectedTx and tx2geneDF$transcript_id.
flatExonsByGene: GRangesList object containing non-overlapping exons for each gene, whose names match tx2geneDF$gene_name. If not supplied, it is derived using flattenExonsBy() and objects exonsByTx, cdsByTx, detectedTx, and tx2geneDF. This step is the key step for using a subset of detected transcripts, in order to produce a clean gene-exon model.
flatExonsByTx: GRangesList object containing non-overlapping exons for each transcript. If not supplied, it is derived using flattenExonsBy() and objects exonsByTx, cdsByTx, detectedTx, and tx2geneDF. This step is the key step for using a subset of detected transcripts, in order to produce a clean transcript-exon model.
filesDF: data.frame with recognized columns:
- 'sample_id': character name of the sample or sample group, where multiple files for the same sample or sample group all use the same character string.
- 'url': character with URL or URI link to file or web resource relevant to each data type.
- 'type': character with type of data, recognizing:
  - 'bw': bigwig coverage file
  - 'junction': BED or bigBed file, ideally formatted as BED12 format. Scores higher than 1000 in bigBed are recognized in the 'name' column when the 'name' is entirely numeric value.
  - 'coverage_gr': character name of coverage values supplied in an object covGR whose values() contain columns of NumericList coverages.
- 'scale_factor': optional numeric column used as a scalar and is multiplied by the numeric values associated with each file. For example, it can be very useful to apply normalization for raw coverage values, or raw junction counts.

When use_memoise=TRUE several R objects are cached using memoise::memoise(), to help re-use of prepared R objects, and to help speed the re-use of data within the R-shiny app:

Usage

Arguments

Value

Details

See also