biomate-ai tximport
Current version only works in 'merge' mode: A single table of gene summarizations is generated with one column for each sample file.
Dependencies & Environment
Package-intrinsic requirements from the Bioconductor landing page — reproduce in any R environment.
- Version: 1.40.0 · Bioconductor: 3.23 · R: ≥ 4.6
- Imports: GeneExpression, ImmunoOncology, Preprocessing, RNASeq, Software, Transcription
- Install:
BiocManager::install("tximport")
When to Use
- Consolidating transcript quantifications from multiple RNA-seq samples into single gene-level matrix
- Preparing data for downstream analysis tools that accept merged count tables
- Batch processing of Salmon, Kallisto, or similar transcript quantifier outputs
When NOT to Use
- Workflows requiring per-sample output files for DESeq2 or similar tools expecting individual sample tables
- Transcript-level differential expression analysis
- Single-sample analysis pipelines
Scientific Assumptions
- {'assumption': 'All input quantification files use identical gene identifier nomenclature and annotation version', 'violation_context': 'Violated when mixing quantifications from different reference genomes or annotation versions, resulting in gene name mismatches and incomplete merging'}
- {'assumption': 'Transcript-to-gene mapping is deterministic and one-to-many (transcripts map to single gene)', 'violation_context': 'Violated in cases of overlapping genes, alternative splicing, or ambiguous transcript assignments; may result in double-counting or gene assignment errors'}
- {'assumption': 'Input quantification files represent independent biological samples suitable for merging into single analysis matrix', 'violation_context': 'Violated when samples are technical replicates or from incompatible experimental designs; may confound downstream statistical analysis'}
- {'assumption': 'Gene-level summarization via aggregation (sum or mean) of transcript abundances is appropriate for downstream analysis', 'violation_context': 'Violated when transcript-level resolution is required or when isoform-specific effects are scientifically important'}
Common Pitfalls
- {'mistake': 'Using tximport output directly with DESeq2 expecting per-sample tables', 'consequence': 'DESeq2 will fail or produce incorrect results due to incompatible input format (merged table vs per-sample requirement)', 'recommendation': 'Verify DESeq2 input format requirements before using tximport; consider alternative workflows or manual reformatting if per-sample tables needed'}
- {'mistake': 'Selecting incorrect annotation version for gene mapping', 'consequence': 'Gene identifiers may not match between quantification files and annotation, resulting in missing or misaligned genes', 'recommendation': 'Ensure annotation version matches the reference genome used for transcript quantification'}
- {'mistake': 'Providing gene names from quantification file without verifying consistency across samples', 'consequence': 'Gene name mismatches across samples could result in incomplete or duplicated rows in merged table', 'recommendation': 'Validate that all input files use identical gene naming conventions before merging'}
Key Parameters
- {'parameter': 'select_the_source_of_the_quantification_file', 'scientific_meaning': 'Specifies whether gene identifiers are embedded in quantification files or must be obtained from external annotation file', 'typical_values': ['Gene names in counts file', 'Gene names from external GFF/GTF annotation'], 'context_guidance': {'scenario_embedded_names': 'Use when quantification files already contain gene identifiers', 'scenario_external_annotation': 'Use when quantification files contain only transcript IDs requiring mapping to genes via GFF/GTF'}}
- {'parameter': 'select_an_annotation_version', 'scientific_meaning': 'Specifies reference genome build and annotation version for gene mapping', 'typical_values': ['hg38', 'hg19', 'mm10', 'mm9', 'other organism-specific builds'], 'context_guidance': {'scenario_human': 'Select hg38 for recent human studies, hg19 for legacy data', 'scenario_mouse': 'Select mm10 for recent mouse studies', 'scenario_other': 'consult the package documentation if the organism is not listed'}, 'quote': 'consult the package documentation if the build is not listed'}
- {'parameter': 'summarization_using_the_abundance_tpm_values', 'scientific_meaning': 'Controls whether gene-level summaries are based on TPM (Transcripts Per Million) abundance values rather than raw counts', 'typical_values': ['true (use TPM for summarization)', 'false (use raw counts)'], 'context_guidance': {'scenario_normalized_analysis': 'Use TPM=true for abundance-based analysis or when downstream tools expect normalized values', 'scenario_count_based_analysis': 'Use TPM=false for count-based differential expression analysis (e.g., DESeq2)'}}
- {'parameter': 'counts_files', 'scientific_meaning': 'Input transcript quantification files from tools like Salmon, Kallisto, or similar quantifiers', 'typical_values': ['Salmon quant.sf files', 'Kallisto abundance.tsv files', 'Other transcript quantification formats'], 'context_guidance': {'scenario_multiple_samples': 'Provide all sample quantification files for merging into single gene-level table', 'scenario_format_consistency': 'Ensure all input files use same quantification tool and format'}}
Result Interpretation
- {'guidance': 'Output is single merged table with genes as rows and samples as columns containing gene-level abundance or count values. Verify row count matches expected number of genes in reference annotation and column count equals number of input samples.'}
- {'guidance': 'Check for missing genes or samples in output; absence may indicate annotation version mismatch or file format incompatibility. Validate that gene identifiers are consistent and recognizable by downstream analysis tools.'}
- {'guidance': 'If using TPM summarization, values should be normalized across samples. If using count summarization, raw counts should reflect transcript abundance without cross-sample normalization.'}
Alternatives
- {'tool': 'DESeq2', 'when_to_prefer_this': 'tximport preferred when you need to merge multiple transcript quantification files into single gene-level table before downstream analysis', 'when_to_prefer_alternative': 'DESeq2 preferred for differential expression analysis; requires per-sample input format rather than merged table'}
- {'tool': 'Salmon/Kallisto direct output', 'when_to_prefer_this': 'tximport preferred when aggregation to gene-level and cross-sample merging is needed', 'when_to_prefer_alternative': 'Direct quantifier output preferred if transcript-level analysis or per-sample organization required'}
Citations
- Soneson C, Love MI, Robinson MD. (2015). Differential analyses for RNA-seq: transcript-level estimates improve gene-level inferences. F1000Research, 4:1521. PMID:26925227 doi:10.12688/f1000research.7563.2
References
- Homepage: N/A (not provided in documentation)
Run this on BioMate
This skill is the knowledge layer — when, why, and how to use tximport. To run this analysis on your own data with managed compute, automated QC, and reproducible outputs, use BioMate — free to start.