tximport: Import transcript-level abundances and counts for transcript-...

Description Usage Arguments Details Value References Examples

View source: R/tximport.R

Description

tximport imports transcript-level estimates from various external software and optionally summarizes abundances, counts, and transcript lengths to the gene-level (default) or outputs transcript-level matrices (see txOut argument).

Usage

1
2
3
4
5
6
7
8
9
tximport(files, type = c("none", "salmon", "sailfish", "alevin",
  "kallisto", "rsem", "stringtie"), txIn = TRUE, txOut = FALSE,
  countsFromAbundance = c("no", "scaledTPM", "lengthScaledTPM",
  "dtuScaledTPM"), tx2gene = NULL, varReduce = FALSE,
  dropInfReps = FALSE, infRepStat = NULL, ignoreTxVersion = FALSE,
  ignoreAfterBar = FALSE, geneIdCol, txIdCol, abundanceCol, countsCol,
  lengthCol, importer = NULL, existenceOptional = FALSE,
  sparse = FALSE, sparseThreshold = 1, readLength = 75,
  forceSlow = FALSE)

Arguments

files

a character vector of filenames for the transcript-level abundances

type

character, the type of software used to generate the abundances. Options are "salmon", "sailfish", "alevin", "kallisto", "rsem", "stringtie", or "none". This argument is used to autofill the arguments below (geneIdCol, etc.) "none" means that the user will specify these columns.

txIn

logical, whether the incoming files are transcript level (default TRUE)

txOut

logical, whether the function should just output transcript-level (default FALSE)

countsFromAbundance

character, either "no" (default), "scaledTPM", "lengthScaledTPM", or "dtuScaledTPM". Whether to generate estimated counts using abundance estimates:

  • scaled up to library size (scaledTPM),

  • scaled using the average transcript length over samples and then the library size (lengthScaledTPM), or

  • scaled using the median transcript length among isoforms of a gene, and then the library size (dtuScaledTPM).

dtuScaledTPM is designed for DTU analysis in combination with txOut=TRUE, and it requires specifing a tx2gene data.frame. dtuScaledTPM works such that within a gene, values from all samples and all transcripts get scaled by the same fixed median transcript length. If using scaledTPM, lengthScaledTPM, or geneLengthScaledTPM, the counts are no longer correlated across samples with transcript length, and so the length offset matrix should not be used.

tx2gene

a two-column data.frame linking transcript id (column 1) to gene id (column 2). the column names are not relevant, but this column order must be used. this argument is required for gene-level summarization for methods that provides transcript-level estimates only (kallisto, Salmon, Sailfish)

varReduce

whether to reduce per-sample inferential replicates information into a matrix of sample variances variance (default FALSE). alevin computes inferential variance by default for bootstrap inferential replicates, so this argument is ignored/not necessary

dropInfReps

whether to skip reading in inferential replicates (default FALSE). For alevin, tximport will still read in the inferential variance matrix if it exists

infRepStat

a function to re-compute counts and abundances from the inferential replicates, e.g. matrixStats::rowMedians to re-compute counts as the median of the inferential replicates. The order of operations is: first counts are re-computed, then abundances are re-computed. Following this, if countsFromAbundance is not "no", tximport will again re-compute counts from the re-computed abundances. infRepStat should operate on rows of a matrix. (default is NULL)

ignoreTxVersion

logical, whether to split the tx id on the '.' character to remove version information to facilitate matching with the tx id in tx2gene (default FALSE)

ignoreAfterBar

logical, whether to split the tx id on the '|' character to facilitate matching with the tx id in tx2gene (default FALSE)

geneIdCol

name of column with gene id. if missing, the tx2gene argument can be used

txIdCol

name of column with tx id

abundanceCol

name of column with abundances (e.g. TPM or FPKM)

countsCol

name of column with estimated counts

lengthCol

name of column with feature length information

importer

a function used to read in the files

existenceOptional

logical, should tximport not check if files exist before attempting import (default FALSE, meaning files must exist according to file.exists)

sparse

logical, whether to try to import data sparsely (default is FALSE). Initial implementation for txOut=TRUE, countsFromAbundance="no" or "scaledTPM", no inferential replicates. Only counts matrix is returned (and abundance matrix if using "scaledTPM")

sparseThreshold

the minimum threshold for including a count as a non-zero count during sparse import (default is 1)

readLength

numeric, the read length used to calculate counts from StringTie's output of coverage. Default value (from StringTie) is 75. The formula used to calculate counts is: cov * transcript length / read length

forceSlow

logical, argument used for testing. Will force the use of the slower R code for importing alevin, even if fishpond library is installed. Default is FALSE

Details

tximport will also load in information about inferential replicates – a list of matrices of the Gibbs samples from the posterior, or bootstrap replicates, per sample – if these data are available in the expected locations relative to the files. The inferential replicates, stored in infReps in the output list, are on estimated counts, and therefore follow counts in the output list. By setting varReduce=TRUE, the inferential replicate matrices will be replaced by a single matrix with the sample variance per transcript/gene and per sample.

While tximport summarizes to the gene-level by default, the user can also perform the import and summarization steps manually, by specifing txOut=TRUE and then using the function summarizeToGene. Note however that this is equivalent to tximport with txOut=FALSE (the default).

Solutions to the error "tximport failed at summarizing to the gene-level":

  1. provide a tx2gene data.frame linking transcripts to genes (more below)

  2. avoid gene-level summarization by specifying txOut=TRUE

  3. set geneIdCol to an appropriate column in the files

See vignette('tximport') for example code for generating a tx2gene data.frame from a TxDb object. Note that the keys and select functions used to create the tx2gene object are documented in the man page for AnnotationDb-class objects in the AnnotationDbi package (TxDb inherits from AnnotationDb). For further details on generating TxDb objects from various inputs see vignette('GenomicFeatures') from the GenomicFeatures package.

For type="alevin" all arguments other than files, dropInfReps, and forceSlow are ignored, and files should point to a single quants_mat.gz file, in the directory structure created by the alevin software (e.g. do not move the file or delete the other important files). Note that importing alevin quantifications will be much faster by first installing the fishpond package, which contains a C++ importer for alevin's EDS format. For alevin, tximport is importing the gene-by-cell matrix of counts, as txi$counts, and effective lengths are not estimated. txi$variance may also be imported if inferential replicates were used, as well as inferential replicates if these were output by alevin. Length correction should not be applied to datasets where there is not an expected correlation of counts and feature length.

Value

a simple list containing matrices: abundance, counts, length. Another list element 'countsFromAbundance' carries through the character argument used in the tximport call. The length matrix contains the average transcript length for each gene which can be used as an offset for gene-level analysis. If detected, and txOut=TRUE, inferential replicates for each sample will be imported and stored as a list of matrices, itself an element infReps in the returned list. An exception is alevin, in which the infReps are a list of bootstrap replicate matrices, where each matrix has genes as rows and cells as columns. If varReduce=TRUE the inferential replicates will be summarized according to the sample variance, and stored as a matrix variance. alevin already computes the variance of the bootstrap inferential replicates and so this is imported without needing to specify varReduce=TRUE (note that alevin uses the 1/N variance estimator, so not the same as var).

References

Charlotte Soneson, Michael I. Love, Mark D. Robinson (2015): Differential analyses for RNA-seq: transcript-level estimates improve gene-level inferences. F1000Research. http://dx.doi.org/10.12688/f1000research.7563.1

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# load data for demonstrating tximport
# note that the vignette shows more examples
# including how to read in files quickly using the readr package

library(tximportData)
dir <- system.file("extdata", package="tximportData")
samples <- read.table(file.path(dir,"samples.txt"), header=TRUE)
files <- file.path(dir,"salmon", samples$run, "quant.sf.gz")
names(files) <- paste0("sample",1:6)

# tx2gene links transcript IDs to gene IDs for summarization
tx2gene <- read.csv(file.path(dir, "tx2gene.gencode.v27.csv"))

txi <- tximport(files, type="salmon", tx2gene=tx2gene)

tximport documentation built on March 24, 2020, 2 a.m.