QTLtools(1)

📦 version 1.3.1, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🎀 QTLtools(1) · Bioinformatics tools 🎀

okay bestie, this is the QTLtools(1) manual page and it is about to be SO good 💅 this is part 1 of 2, so the global options are coming next 🫶

✨ NAME ✨

QTLtools — a complete tool set for molecular QTL discovery and analysis 💖

🎀 SYNOPSIS 🎀

QTLtools [MODE] [OPTIONS]

🦋 DESCRIPTION 🦋

okay so QTLtools is a complete tool set for molecular QTL discovery and analysis, and it's giving fast, user friendly AND cluster friendly 🔥 it does a whole bunch of key tasks: checking the quality of the sequence data, checking that sequence and genotype data actually match, quantifying and stratifying individuals using molecular phenotypes, discovering proximal or distal molQTLs and integrating them with functional annotations or GWAS data, and analyzing allele specific expression ✨

under the hood it uses HTSlib (http://www.htslib.org/) to quickly and efficiently handle common genomics file types like VCF, BCF, BAM, SAM, CRAM, BED, and GTF 🧚 and it also uses the Eigen C++ library (http://eigen.tuxfamily.org/) for fast linear algebra 🌈

💜 MODES 💜

the modes are the main character energy of this tool, so let's go through every single one 👑

🌸 bamstat

QTLtools bamstat --bam [in.sam|in.bam|in.cram] --bed
annotation.bed.gz --out output.txt [OPTIONS]

bamstat is your QC checker for BAM/SAM files, and it calculates basic QC metrics for them 📊

🌸 mbv

QTLtools mbv --bam [in.sam|in.bam|in.cram] --vcf
[in.vcf|in.vcf.gz|in.bcf] --out output.txt [OPTIONS]

mbv is all about matching your BAM to your VCF 👯

🌸 pca

QTLtools pca --vcf [in.vcf|in.vcf.gz|in.bcf] | --bed
in.bed.gz --out output.txt [OPTIONS]

pca calculates principal components for a BED/VCF/BCF/CRAM file 🦋

🌸 correct

QTLtools correct --vcf [in.vcf|in.vcf.gz|in.bcf] | --bed
in.bed.gz --cov covariates.txt | --normal --out output.txt
[OPTIONS]

correct does covariate correction on a BED or a VCF file 🫧

🌸 cis

QTLtools cis --vcf [in.vcf|in.vcf.gz|in.bcf|in.bed.gz]
--bed quantifications.bed.gz [--nominal float | --permute
integer | --mapping in.txt] --out output.txt [OPTIONS]

cis QTL analysis, obsessed with this one 😭

🌸 trans

QTLtools trans --vcf [in.vcf|in.vcf.gz|in.bcf|in.bed.gz]
--bed quantifications.bed.gz [--nominal | --permute |
--sample integer | --adjust in.txt] --out output.txt
[OPTIONS]

trans QTL analysis, the other half of the QTL squad 💖

🌸 fenrich

QTLtools fenrich --qtl significanty_genes.bed --tss
gene_tss.bed --bed TFs.encode.bed.gz --out output.txt
[OPTIONS]

fenrich does functional enrichment for QTLs 🧪

🌸 fdensity

QTLtools fdensity --qtl significanty_genes.bed --bed
TFs.encode.bed.gz --out output.txt [OPTIONS]

fdensity looks at the functional density around QTLs 🍓

🌸 genrich

QTLtools genrich --qtl significanty_genes.bed --tss
gene_tss.bed --vcf 1000kg.vcf --gwas gwas_hits.bed --out
output.txt [OPTIONS]

genrich does GWAS enrichment for QTLs 🙈

⚠️ bestie, this mode is deprecated and not supported. use rtc instead!! 💀

🌸 rtc

QTLtools rtc --vcf [in.vcf|in.vcf.gz|in.bcf|in.bed.gz]
--bed quantifications.bed.gz --hotspots
hotspots_b37_hg19.bed [--gwas-cis | --gwas-trans |
--mergeQTL-cis | --mergeQTL-trans] variants_external.txt
qtls_in_this_dataset.txt --out output.txt [OPTIONS]

rtc is the Regulatory Trait Concordance score analysis, and it tests whether two colocalizing variants are due to the same functional effect 🔍

🌸 rtc-union

QTLtools rtc-union --vcf
[in.vcf|in.vcf.gz|in.bcf|in.bed.gz] ...  --bed
quantifications.bed.gz ...  --hotspots
hotspots_b37_hg19.bed --results qtl_results_files.txt ...
[OPTIONS]

rtc-union finds the union of QTLs from independent datasets 🤝 the vibe: if there was a QTL in a given recombination interval in one dataset, then it finds the best QTL (may or may not be genome-wide significant) in that same recombination interval in all the other datasets 🌸

🌸 extract

QTLtools extract [--vcf --bed --cov] relevant_file --out
output_prefix [OPTIONS]

extract is data extraction mode 🧚 it pulls all the data from the provided files and drops it into one flat file, so everything is in one place ✨

🌸 quan

QTLtools quan --bam [in.sam|in.bam|in.cram] --gtf
gene_annotation.gtf --out-prefix output [OPTIONS]

quan quantifies gene and exon expression from RNAseq 📈

🌸 ase

QTLtools ase --bam [in.sam|in.bam|in.cram] --vcf
[in.vcf|in.vcf.gz|in.bcf] --ind sample_name_in_vcf --mapq
integer --out output.txt [OPTIONS]

ase measures allele specific expression from RNAseq at transcribed heterozygous SNPs 🧬

🌸 rep

QTLtools rep --bed quantifications.bed.gz --vcf
[in.vcf|in.vcf.gz|in.bcf] --qtl qtls_external.txt --out
output.txt [OPTIONS]

rep replicates QTL associations in an independent dataset 🔁

🌸 gwas

QTLtools gwas --vcf [in.vcf|in.vcf.gz|in.bcf|in.bed.gz]
--bed quantifications.bed.gz --out output.txt [OPTIONS]

gwas runs GWAS tests, correlating all genotypes with all phenotypes 💜

✨ FILE FORMATS ✨

okay so this section is literally the cheat sheet for every file QTLtools will eat 🍓 bestie, read it before you hit enter or it will absolutely not vibe with you 💀

💜 .bcf|.vcf|.vcf.gz

These are your genotype data files 🧬 The official VCF spec lives at <https://samtools.github.io/hts-specs/VCFv4.2.pdf>, and your VCF/BCF files have to follow that spec's rules, no cap. BCF files must be indexed with bcftools index in.bcf (more info at <http://samtools.github.io/bcftools/bcftools.html>). VCF files should be compressed with bgzip (<http://www.htslib.org/doc/bgzip.html>) and indexed with tabix -p vcf in.vcf.gz (<http://www.htslib.org/doc/tabix.html>) 🫶

🌸 .bed|.bed.gz

These are the phenotype data files 🦋 In certain modes you can also pass them to the --vcf option, which is how you correlate two molecular phenotypes, iconic behavior 👑 The format is a custom UCSC BED format (<https://genome.ucsc.edu/FAQ/FAQformat.html#format1>) with 6 annotation columns followed by sample columns. The header line must exist, it must begin with a #, and the columns must be tab separated.

⚠️ WARNING, this is a different file format from FASTQTL, so FASTQTL BED files are INCOMPATIBLE with QTLtools. Do not try to be slick about it 💀

Phenotype BED files must be compressed with bgzip (<http://www.htslib.org/doc/bgzip.html>) and indexed with tabix -p bed in.bed.gz (<http://www.htslib.org/doc/tabix.html>). Missing values must be coded as NA. Here is an example BED file, bestie 💖

#chr start     end  pid  gid  strand    sample1   sample2
1    9999 10000     exon1     gene1     +    15   234
1    9999 10000     exon2     gene1     +    11   134
1    19999     20000     exon1     gene2     -    154  284
1    19999     20000     exon2     gene2     -    112  301

Here is what each of the annotation columns means 🎀

  1. Phenotype chromosome [string]
  2. Start position of the phenotype [integer, 0-based]
  3. End position of the phenotype [integer, 1-based]
  4. Phenotype ID [string]
  5. Phenotype group ID or any type of info about the phenotype [string]
  6. Phenotype strand [+/-]

🧚 .bam|.sam|.cram

These are the sequence data files ✨ The official SAM spec is at <https://samtools.github.io/hts-specs/SAMv1.pdf>, and your SAM/BAM/CRAM files must satisfy that spec's requirements. They must be indexed with samtools index in.bam (<http://www.htslib.org/doc/samtools.html>) 💅

🌈 .gtf

These are for gene annotation 🌿 The file specification is at <https://www.ensembl.org/info/website/upload/gff.html>. Your GTF files must comply with that spec, and they should have the gene_id, transcript_id, gene_name, gene_type, and trnascript_type attributes. (Yes, trnascript_type is spelled exactly like that in the original, so match it as written 🙈) We recommend using gene annotations from GENCODE (<https://www.gencodegenes.org/>) 🔥

🍓 covariate files

The covariate file holds your covariate data in simple text format 📝 Missing values should be encoded as NA. Both quantitative and qualitative covariates are supported. Quantitative covariates are assumed when only numeric values are provided, and qualitative covariates are assumed when only non-numeric values are provided. In practice, qualitative covariates with F factors get converted into F-1 binary covariates. Here is an example covariate file:

id   sample1   sample2   sample3
PC1  -0.02     0.14 0.16
PC2  0.01 0.11 0.10
PC3  0.03 0.05 0.07
COV  A    B    C

👑 include/exclude files

The various --{include,exclude}-{sites,samples,phenotypes,covariates} options need a simple text file listing the IDs of the type you want, one ID per line 🌸 The include options run the analyses only on that subset of IDs, whereas the exclude options remove those IDs from the analyses. The IDs for --{include,exclude}-sites refer to the 3rd column in VCF/BCF files. The IDs for --{include,exclude}-covariates refer to the 1st column in COV files. The IDs for --{include,exclude}-phenotyps refer to the 4th column in BED files, and when the --grp-best option is used, they refer to the 5th column instead. The --include-positions and --exclude-positions options need a text file listing the chromosomes and positions (separated by a space) of the genotypes to be included or excluded, one position per line 🦋

✨ IMPORTANT NOTES ✨

okay bestie, these are the big rules, so pay attention 👀

  • BED files' start position is 0-based, but the end position is 1-based. Positions in all other files used in QTLtools are 1-based. All positions you give as option arguments and filters, even the ones referring to BED files, must be 1-based. 1-based means the first base of the sequence is position 1, whereas in 0-based the first position is 0. Math is giving main character energy 🧮
  • Make sure the chromosome names are the same across all files. If some files have chr1 and another has 1 as the chromosome name, QTLtools will treat them as different chromosomes. Not the vibe 💀
  • BED files used for FastQTL (<http://fastqtl.sourceforge.net/>) are not directly compatible with QTLtools. To convert a FastQTL BED file to the QTLtools format, you need to add 2 columns after the 4th column 🛠️
  • The quan mode in version 1.2 and above is not compatible with quantifications generated by previous versions. This is due to bug fixes and slight adjustments to the way we quantify. Do not mix quantifications from earlier versions of QTLtools with quantifications from version 1.2 and above, because this will create a bias in your dataset 😭
  • Make sure you index all your genotype, phenotype, and sequence files 🔥
  • Use BCF and BAM files for the best performance ✨

✨ EXAMPLE FILES ✨

Here are the example files you can grab from the QTLtools examples site (<http://jungle.unige.ch/QTLtools_examples/>), each one linked below 🧚

✨ SEE ALSO ✨

bestie, here are all the sibling pages you should check out next 📚

✨ BUGS ✨

okay so there's one known bug and it's a lowkey big one, pls read 🙈

  • Versions up to and including 1.2 suffer from a bug in reading missing genotypes in VCF/BCF files. This bug affects variants with a DS field in their genotype's FORMAT that have a missing genotype (DS field is .) in one of the samples. In that case, the genotypes for all the samples get set to missing, which effectively removes this variant from the analyses 💀 Affected modes: cis, correct, gwas, pca, rep, trans, rtc-union

Please submit bugs to <https://github.com/qtltools/qtltools> 💌

✨ CITATIONS ✨

if you're writing it up, cite these 💅

Delaneau O., Ongen H., Brown A. A., et al. A complete tool set for molecular QTL discovery and analysis. Nat Commun 8, 15452 (2017). <https://doi.org/10.1038/ncomms15452>

Ongen H, Brown A. A., Delaneau O., et al. Estimating the causal tissues for complex traits and diseases. Nat Genet. 2017;49(12):1676-1683. doi:10.1038/ng.3981 <https://doi.org/10.1038/ng.3981>

Fort A., Panousis N. I., Garieri M., et al. MBV: a method to solve sample mislabeling and detect technical bias in large combined genotype and sequencing assay datasets, Bioinformatics 33(12), 1895 2017. <https://doi.org/10.1093/bioinformatics/btx074>

✨ AUTHORS ✨

the legends behind this tool 👑

Olivier Delaneau (olivier.delaneau@gmail.com), Halit Ongen (halitongen@gmail.com) 🫶

bestie, that's the whole page 🌈 Everything here is from QTLtools-v1.3, last updated 06 May 2020, so double-check your version and date before you trust anything too hard 💖 Stay iconic, stay curious, and go run some QTL analyses 🦋✨

📦 where this page comes from