.\" Manpage for QTLtools ase.
.\" Contact halitongen@gmail.com to correct errors or typos.
.TH QTLtools-quan 1 "06 May 2020" "QTLtools-v1.3" "Bioinformatics tools"
.SH NAME
QTLtools quan \- Quantify gene and exon expression from RNA-seq
.SH SYNOPSIS
.B QTLtools quan \-\-bam
.IR [in.sam | in.bam | in.cram]
.B \-\-gtf
.IR gene_annotation.gtf
.B \-\-out-prefix
.IR output
.I [OPTIONS]
.SH DESCRIPTION
This mode quantifies the expression of genes and exons in the provided \fB\-\-gtf\fR file using the RNA-seq reads in the \fB\-\-bam\fR file.
The method counts the number of reads overlapping the exons in the \fB\-\-gtf\fR file.
Firstly all exons of a gene are converted into meta-exons where overlapping exons are merged into a single exon encompassing all the overlapping exons.
Any overlap between the read and the exon is considered a match, that is a read is not required to be in between start and end positions of an exon to count towards that exon's quantification.
Split reads aligning to multiple exons contribute to each exon it overlaps with based on the fraction of the read that overlaps with a given exon.
Thus split reads contribute less than a single count to each of the overlapping exons.
Reads aligning to multiple exons (i.e. overlapping exons of multiple genes) count towards the quantification of all the exons that it overlaps with.
If the \fB\-\-bam\fR file contains paired-end reads and if there are cases where the two mate pairs overlap with each other (i.e. have an insert size < 0), then each of these reads contribute less then a single count towards the quantifications unless \fB\-\-no-merge\fR is provided.
The following diagram, with two genes with overlapping exons and one paired-end read where both mate pairs are split reads and overlap with each other, illustrates how the quantification works:
.PP
.DS C
.ft CW
x x
/ \\ / \\
+---------+ +---------+ +---------+
| Exon1|1 | | Exon1|2 | | Exon1|3 | Gene1
+---------+ +---------+ +---------+
x
/ \\
+------------+ +-------------+
| Exon2|1 | | Exon2|2 | Gene2
+------------+ +-------------+
x
/ \\
+------------+ +----+ RNAseq Read Mate1
|--a-||-b-||c| |-d--||--e-|
x
/ \\
+------+ +----------+ RNAseq Read Mate2
Left Mate1 = ((b * 0.5) + a) / (a + b + d)
Right Mate1 = (d * 0.5)/(a + b + d)
Left Mate2 = (b * 0.5)/(b + d + e)
Right Mate2 = ((d * 0.5) + e)/(b + d + e)
Exon1|2 = Left Mate1 + Left Mate2
Exon1|3 = Right Mate1 + Right Mate2
Exon2|1 = Left Mate1 + Left Mate2
Exon2|2 = Right Mate2 + Right Mate2
Gene1 = Exon1|2 + Exon1|3
Gene2 = Exon2|1 + Exon2|2
.B The quan mode in version 1.2 and above is not compatible with the quantifications generated by the previous versions. This due to bug fixes and slight adjustments to the way we quantify. DO NOT MIX QUANTIFICATIONS GENERATED BY EARLIER VERSIONS OF QTLTOOLS WITH QUANTIFICATIONS FROM VERSION 1.2 AND ABOVE AS THIS WILL CREATE A BIAS IN YOUR DATASET.
.ft
.DE
.SH OPTIONS
.TP
.B \-\-gtf \fIgene_annotation.gtf\fR
Gene annotations in GTF format.
These can be obtained from .
REQUIRED.
.TP
.B \-\-bam [\fIin.bam\fR|\fIin.sam\fR|\fIin.cram\fB]
Sequence data in BAM/SAM/CRAM format sorted by chromosome and then position.
One sample per BAM file.
REQUIRED.
.TP
.B \-\-out-prefix \fIoutput\fR
Output prefix.
REQUIRED.
.TP
.B \-\-sample \fIsample_name\fR
The sample name of the BAM file.
If not provided the sample name will be taken as the BAM file path.
.TP
.B \-\-rpkm
Output RPKM values.
.TP
.B \-\-tpm
Output TPM values.
.TP
.B \-\-xxhash
Rather than using the GTF file name to generate unique hash for the options used, use the hash of the GTF file.
.TP
.B \-\-no-hash
Do not include a hash signifying the options used in the quantification in the output file names.
NOT RECOMMENDED.
.TP
.B \-\-gene-types \fIgene_type\fR ...
Only quantify these gene types.
Requires gene_type attribute in GTF.
It will also use transcript_type if present.
.TP
.B \-\-filter\-mapping\-quality \fIinteger\fR
Minimum mapping quality for a read or read pair to be considered.
Set this to only include uniquely mapped reads.
DEFAULT=10.
.TP
.B \-\-filter\-mismatch \fIinteger|float\fR
Maximum mismatches allowed in a read.
If between 0 and 1 taken as the fraction of read length.
\fBRequires NM attribute in the BAM file.\fR
DEFAULT=OFF.
.TP
.B \-\-filter\-mismatch\-total \fIinteger|float\fR
Maximum total mismatches allowed in paired-reads.
If between 0 and 1 taken as the fraction of combined read length.
\fBRequires NM attribute in the BAM file.\fR
DEFAULT=OFF.
.TP
.B \-\-filter\-min\-exon \fIinteger\fR
Minimum length of an exon for it to be quantified.
Exons smaller than this will not be printed out in the exon quantifications, but will still count towards gene quantifications.
DEFAULT=0.
.TP
.B \-\-filter\-remove\-duplicates
Remove duplicate sequencing reads,as indicated by the aligner, in the process.
NOT RECOMMENDED.
.TP
.B \-\-filter\-failed\-qc
Remove fastq reads that fail sequencing QC as indicated by the sequencer.
.TP
.B \-\-check\-proper\-pairing
If provided only properly paired reads according to the aligner that are in correct orientation will be considered.
Otherwise all pairs in correct orientation will be considered.
.TP
.B \-\-check\-consistency
If provided checks the consistency of split reads with annotation, rather than pure overlap of one of the blocks of the split read.
.TP
.B \-\-no\-merge
If provided overlapping mate pairs will not be merged.
Default behavior is to merge overlapping mate pairs based on the amount of overlap, such that each mate pair counts for less than 1 read.
.TP
.B \-\-legacy\-options
Exactly replicate Dermitzakis lab original quantification script.
DO NOT USE.
.TP
.B \-\-region \fIchr:start-end\fR
Genomic region to be processed.
E.g. chr4:12334456-16334456, or chr5.
.SH OUTPUT FILES
Unless \fB\-\-no\-hash\fR is provided, all output files will include a hash value corresponding to combination of the specific options used.
This is given so that one does not merge quantifications from samples that were quantified differently, which would create a bias in the dataset.
.TP 1
.B .gene.count.bed .exon.count.bed .gene.rpkm.bed .exon.rpkm.bed .gene.tpm.bed .exon.tpm.bed
These are the quantification results files with the following columns:
.TS
n l lx .
1 chr T{
Phenotype's chromosome
T}
2 start T{
Phenotype's start position (0-based)
T}
3 end T{
Phenotype's end position (1-based)
T}
4 gene|exon T{
The gene or exon ID.
T}
5 info|geneID T{
Information about the gene or the gene ID of the exon.
The gene info is separated by semicolons, and L=gene length, T=gene type, R=gene positions, N=gene name
T}
6 strand T{
Phenotype's strand
T}
7 sample_name T{
The sample name of the BAM file
T}
.TE
.TP 1
.B .stats
Details the statistics of the quantification, with the following rows:
.TS
n l lx .
1 filtered_secondary_alignments_(does_not_count_towards_total_reads) T{
Number of secondary alignments
T}
2 total_reads T{
Number of reads in the BAM file
T}
3 filtered_unmapped T{
Number of unmapped reads
T}
4 filtered_failqc T{
Number of reads with the failed QC tag
T}
5 filtered_duplicate T{
Number of duplicate reads
T}
6 filtered_mapQ_less_than_X T{
Number of reads below the mapping quality threshold X
T}
7 filtered_notpaired T{
Number of pairs that were not in the correct orientation or were not properly paired
T}
8 filtered_mismatches_greater_than_X_Y T{
Number of reads failing the mismatches per read, X, and mismatches total filters, Y
T}
9 filtered_unmatched_mate_pairs T{
Number of reads where there was a paired-read with a missing mate
T}
10 total_good T{
Number of reads that passed all filters
T}
11 total_exonic T{
Number of reads that aligned to exons and passed all filters
T}
12 total_exonic_multi_counting T{
Number of reads that aligned to exons when we count reads that align to multiple exons multiple times
T}
13 total_merged_reads T{
Number of reads where the mate pairs were overlapping and thus were merged
T}
14 total_exonic_multi_counting_after_merge_(used_for_rpkm) T{
Number of reads that aligned to exons when we merge overlapping mate pairs
T}
15 good_over_total T{
Number of good reads over the total number of reads
T}
16 exonic_over_total T{
Number of exonic reads over the total number of reads
T}
17 exonic_over_good T{
Number of exonic reads over the number of good reads
T}
.TE
.SH EXAMPLE
.IP o 2
Quantifying a sample mapped with GEM, outputting TPM and RPKM values, and taking the hash of the GTF file:
.IP "" 2
QTLtools quan --bam HG00381.chr22.bam --gtf gencode.v19.annotation.chr22.gtf.gz --out-prefix HG00381 --sample HG00381 --rpkm --tpm --xxhash --filter-mismatch-total 8 --filter-mapping-quality 150
.SH SEE ALSO
.IR QTLtools (1)
.\".IR QTLtools-bamstat (1),
.\".IR QTLtools-mbv (1),
.\".IR QTLtools-pca (1),
.\".IR QTLtools-correct (1),
.\".IR QTLtools-cis (1),
.\".IR QTLtools-trans (1),
.\".IR QTLtools-fenrich (1),
.\".IR QTLtools-fdensity (1),
.\".IR QTLtools-rtc (1),
.\".IR QTLtools-rtc-union (1),
.\".IR QTLtools-extract (1),
.\".IR QTLtools-quan (1),
.\".IR QTLtools-rep (1),
.\".IR QTLtools-gwas (1),
.PP
QTLtools website:
.SH BUGS
Please submit bugs to
.SH
CITATION
Delaneau, O., Ongen, H., Brown, A. et al. A complete tool set for molecular QTL discovery and analysis. \fINat Commun\fR \fB8\fR, 15452 (2017).
.SH AUTHORS
Halit Ongen (halitongen@gmail.com), Olivier Delaneau (olivier.delaneau@gmail.com)