oarfish-quantification-format-handling
Summary
Import and extract transcript-level abundance, count, and length matrices from oarfish long-read RNA-seq quantification files (quant.gz format) using tximport. This skill is essential when working with oarfish-quantified long-read data that must be integrated into downstream differential expression workflows.
When to use
You have long-read RNA-seq samples quantified by oarfish (output as quant.gz files) and need to extract transcript-level or gene-level abundance, count, and length matrices for downstream statistical analysis. Use this skill when you want to preserve transcript-level information during import rather than immediately aggregating to gene level, or when you need length matrices to account for differential isoform usage across samples.
When NOT to use
- Input files are already in gene-level count matrix format (use directly with DESeq2 or edgeR instead of re-importing)
- Quantification was performed with a different tool (salmon, sailfish, kallisto); use the appropriate type parameter instead
- You require inferential replicates (Gibbs or bootstrap samples); verify oarfish output includes these before attempting import
Inputs
- oarfish quant.gz files (one per sample)
- sample metadata or design table (recommended for downstream use)
- tx2gene mapping data.frame (required if gene-level summarization is desired)
Outputs
- abundance matrix (transcript or gene level, rows = features, columns = samples)
- counts matrix (estimated counts, same dimensions as abundance)
- length matrix (average transcript length weighted by sample-specific abundance)
How to apply
Load oarfish quant.gz files using tximport with the type='oarfish' parameter to specify the quantification software. Set txOut=TRUE to retain transcript-level output matrices instead of gene-level summarization; omit or set txOut=FALSE if gene-level aggregation is desired. Extract the returned list object containing three matrices: 'abundance' (normalized transcript abundances), 'counts' (estimated transcript counts), and 'length' (transcript lengths weighted by sample-specific abundances). The length matrix can subsequently be used as an offset for downstream gene-level differential analysis to correct for potential changes in gene length arising from differential isoform usage. Verify that matrix dimensions match the number of samples and transcripts/genes, and check for consistency of row names (transcript or gene IDs) and column names (sample identifiers) across replicates.
Related tools
- tximport (Primary import function; accepts type='oarfish' parameter and txOut flag to control output level and extract matrices) — github:thelovelab__tximport
- DESeq2 (Downstream differential expression analysis using imported count matrices and length-based offsets)
- edgeR (Alternative downstream differential expression analysis using imported count matrices and length-based offsets)
- limma-voom (Alternative downstream differential expression analysis using imported count matrices and length-based offsets)
Examples
txi <- tximport(files = c('sample1.quant.gz', 'sample2.quant.gz', 'sample3.quant.gz'), type = 'oarfish', txOut = TRUE)
Evaluation signals
- Returned abundance, counts, and length matrices have consistent dimensions (same number of rows = features, same number of columns = samples)
- Row names match expected transcript or gene IDs from the quantification; column names match input sample identifiers
- Abundance values are in expected range (typically 0–1 or log-scale); counts are non-negative integers or near-integer estimates; length values are positive
- No missing (NA) or infinite values in returned matrices; all samples are represented
- Downstream differential analysis (DESeq2/edgeR/limma-voom) accepts the matrices without format errors and length offset can be incorporated
Limitations
- tximport requires a tx2gene mapping only if gene-level summarization is desired; transcript-level output (txOut=TRUE) does not require this mapping
- The length matrix represents average transcript length weighted by abundance and may vary across samples due to differential isoform usage; this is intentional and supports correction for composition bias in downstream analysis
- No automatic metadata annotation is provided by tximport itself; for automatic addition of annotation metadata, use the tximeta package instead
Evidence
- [other] transcript-level import with txOut parameter: "tximport with type='oarfish' and txOut=TRUE successfully imports transcript-level abundance, count, and length matrices from oarfish quant.gz files"
- [intro] length matrix for offset calculation: "Average transcript length, weighted by sample-specific transcript abundance estimates, is provided as a matrix which can be used as an offset for different expression of gene-level counts"
- [readme] tximport function purpose: "Imports transcript-level abundance, estimated counts and transcript lengths, and summarizes into matrices for use with downstream statistical analysis packages such as edgeR, DESeq2, limma-voom"
- [intro] type parameter specification: "The tximport package has a single function for importing transcript-level estimates. The type argument is used to specify what software was used for estimation"
- [intro] correction for differential isoform usage: "this approach corrects for potential changes in gene length across samples (e.g. from differential isoform usage)"
1---2name: oarfish-quantification-format-handling3description: Use when you have long-read RNA-seq samples quantified by oarfish (output as quant.gz files) and need to extract transcript-level or gene-level abundance, count, and length matrices for downstream statistical analysis.4license: CC-BY-4.05---67# oarfish-quantification-format-handling89## Summary1011Import and extract transcript-level abundance, count, and length matrices from oarfish long-read RNA-seq quantification files (quant.gz format) using tximport. This skill is essential when working with oarfish-quantified long-read data that must be integrated into downstream differential expression workflows.1213## When to use1415You have long-read RNA-seq samples quantified by oarfish (output as quant.gz files) and need to extract transcript-level or gene-level abundance, count, and length matrices for downstream statistical analysis. Use this skill when you want to preserve transcript-level information during import rather than immediately aggregating to gene level, or when you need length matrices to account for differential isoform usage across samples.1617## When NOT to use1819- Input files are already in gene-level count matrix format (use directly with DESeq2 or edgeR instead of re-importing)20- Quantification was performed with a different tool (salmon, sailfish, kallisto); use the appropriate type parameter instead21- You require inferential replicates (Gibbs or bootstrap samples); verify oarfish output includes these before attempting import2223## Inputs2425- oarfish quant.gz files (one per sample)26- sample metadata or design table (recommended for downstream use)27- tx2gene mapping data.frame (required if gene-level summarization is desired)2829## Outputs3031- abundance matrix (transcript or gene level, rows = features, columns = samples)32- counts matrix (estimated counts, same dimensions as abundance)33- length matrix (average transcript length weighted by sample-specific abundance)3435## How to apply3637Load oarfish quant.gz files using tximport with the type='oarfish' parameter to specify the quantification software. Set txOut=TRUE to retain transcript-level output matrices instead of gene-level summarization; omit or set txOut=FALSE if gene-level aggregation is desired. Extract the returned list object containing three matrices: 'abundance' (normalized transcript abundances), 'counts' (estimated transcript counts), and 'length' (transcript lengths weighted by sample-specific abundances). The length matrix can subsequently be used as an offset for downstream gene-level differential analysis to correct for potential changes in gene length arising from differential isoform usage. Verify that matrix dimensions match the number of samples and transcripts/genes, and check for consistency of row names (transcript or gene IDs) and column names (sample identifiers) across replicates.3839## Related tools4041- **tximport** (Primary import function; accepts type='oarfish' parameter and txOut flag to control output level and extract matrices) — github:thelovelab__tximport42- **DESeq2** (Downstream differential expression analysis using imported count matrices and length-based offsets)43- **edgeR** (Alternative downstream differential expression analysis using imported count matrices and length-based offsets)44- **limma-voom** (Alternative downstream differential expression analysis using imported count matrices and length-based offsets)4546## Examples4748```49txi <- tximport(files = c('sample1.quant.gz', 'sample2.quant.gz', 'sample3.quant.gz'), type = 'oarfish', txOut = TRUE)50```5152## Evaluation signals5354- Returned abundance, counts, and length matrices have consistent dimensions (same number of rows = features, same number of columns = samples)55- Row names match expected transcript or gene IDs from the quantification; column names match input sample identifiers56- Abundance values are in expected range (typically 0–1 or log-scale); counts are non-negative integers or near-integer estimates; length values are positive57- No missing (NA) or infinite values in returned matrices; all samples are represented58- Downstream differential analysis (DESeq2/edgeR/limma-voom) accepts the matrices without format errors and length offset can be incorporated5960## Limitations6162- tximport requires a tx2gene mapping only if gene-level summarization is desired; transcript-level output (txOut=TRUE) does not require this mapping63- The length matrix represents average transcript length weighted by abundance and may vary across samples due to differential isoform usage; this is intentional and supports correction for composition bias in downstream analysis64- No automatic metadata annotation is provided by tximport itself; for automatic addition of annotation metadata, use the tximeta package instead6566## Evidence6768- [other] transcript-level import with txOut parameter: "tximport with type='oarfish' and txOut=TRUE successfully imports transcript-level abundance, count, and length matrices from oarfish quant.gz files"69- [intro] length matrix for offset calculation: "Average transcript length, weighted by sample-specific transcript abundance estimates, is provided as a matrix which can be used as an offset for different expression of gene-level counts"70- [readme] tximport function purpose: "Imports transcript-level abundance, estimated counts and transcript lengths, and summarizes into matrices for use with downstream statistical analysis packages such as edgeR, DESeq2, limma-voom"71- [intro] type parameter specification: "The tximport package has a single function for importing transcript-level estimates. The type argument is used to specify what software was used for estimation"72- [intro] correction for differential isoform usage: "this approach corrects for potential changes in gene length across samples (e.g. from differential isoform usage)"
