Subcommand: afs heatmap

Create a per-window heatmap of the allele frequency spectrum along the genome.

Usage: grenedalf afs-heatmap [options]

Options

Input SAM/BAM/CRAM
--sam-path	TEXT:PATH(existing)=[] ... List of sam/bam/cram files or directories to process. For directories, only files with the extension .sam[.gz]|.bam|.cram are processed. To input more than one file or directory, either separate them with spaces, or provide this option multiple times.
--sam-min-map-qual	UINT:UINT in [0 - 90]=0 Needs: --sam-path Minimum phred-scaled mapping quality score [0-90] for a read in sam/bam/cram files to be considered. Any read that is below the given value of mapping quality will be completely discarded, and its bases not taken into account. Default is 0, meaning no filtering by base quality.
--sam-min-base-qual	UINT:UINT in [0 - 90]=0 Needs: --sam-path Minimum phred-scaled quality score [0-90] for a base in sam/bam/cram files to be considered. Bases below this are ignored when computing allele frequencies. Default is 0, meaning no filtering by base quality.
--sam-split-by-rg	Needs: --sam-path Instead of considering the whole sam/bam/cram file as one large colletion of reads, use the @RG read group tag to split reads. Each read group is then considered a sample. Reads with an invalid (not in the header) read group tag or without a tag are ignored.
Input (m)pileup
--pileup-path	TEXT:PATH(existing)=[] ... List of (m)pileup files or directories to process. For directories, only files with the extension .(plp|mplp|pileup|mpileup)[.gz] are processed. To input more than one file or directory, either separate them with spaces, or provide this option multiple times.
--pileup-min-base-qual	UINT:UINT in [0 - 90]=0 Needs: --pileup-path Minimum phred quality score [0-90] for a base in (m)pileup files to be considered. Bases below this are ignored when computing allele frequencies. Default is 0, meaning no filtering by phred quality score.
--pileup-quality-encoding	TEXT:{sanger,illumina-1.3,illumina-1.5,illumina-1.8,solexa}=sanger Needs: --pileup-path Encoding of the quality scores of the bases in (m)pileup files, when using --pileup-min-base-qual. Default is "sanger", which seems to be the most common these days. Both "sanger" and "illumina-1.8" are identical and use an ASCII offset of 33, while "illumina-1.3" and "illumina-1.5" are identical with an ASCII offset of 64 (we provide different names for completeness). Lastly, "solexa" has an offset of 64, but uses a different equation (not phred score) for the encoding.
Input sync
--sync-path	TEXT:PATH(existing)=[] ... List of sync (as specified by PoPoolation2) files or directories to process. For directories, only files with the extension .sync[.gz] are processed. To input more than one file or directory, either separate them with spaces, or provide this option multiple times.
Input VCF
--vcf-path	TEXT:PATH(existing)=[] ... List of vcf/bcf files or directories to process. For directories, only files with the extension .vcf[.gz]|.bcf are processed. To input more than one file or directory, either separate them with spaces, or provide this option multiple times. This expects that the input file has the per-sample VCF FORMAT field AD (alleleic depth) given, containing the counts of the reference and alternative base. This assumes that the data that was used to create the VCF file was actually a pool of individuals (e.g., from pool sequencing) for each sample (column) of the VCF file. We then interpret the AD field as the allele counts of each pool of individuals.
Input Settings
--multi-file-locus-set	TEXT:{union,intersection}=union When multiple input files are provided, select whether the union of all their loci is used, or their intersection. For their union, input files that do not have data at a particular locus are considered to have zero counts at every base at that locus. Note that we allow to use multiple input files even with different file types.
Sample Names
--sample-name-list	TEXT Excludes: --sample-name-prefix Some file types do not contain sample names, such as (m)pileup or sync files. For such file types, sample names can here be provided as either (1) a comma- or tab-separated list, or (2) as a file with one sample name per line, in the same order as samples are in the actual input file. We then use these names in the output and the --filter-samples-include and --filter-samples-exclude options. If not provided, we simply use numbers 1..n as sample names for these files types. Note that this option can only be used if a single file is given as input. Alternatively, use --sample-name-prefix to provide a prefix for this sample numbering.
--sample-name-prefix	TEXT Excludes: --sample-name-list Some file types do not contain sample names, such as (m)pileup or sync files. For such file types, this prefix followed by indices 1..n can be used instead to provide unique names per sample that we use in the output and the --filter-samples-include and --filter-samples-exclude options. For example, use "Sample_" as a prefix. If not provided, we simply use numbers 1..n as sample names for these files types. This prefix also works if multiple files are given as input. Alternatively, use --sample-name-list to directly provide a list of sample names.
Filtering
--filter-region	TEXT=[] ... Genomic region to filter for, in the format "chr" (for whole chromosomes), "chr:position", "chr:start-end", or "chr:start..end". Positions are 1-based and inclusive (closed intervals). The option can be provided multiple times, see also --filter-region-set.
--filter-region-list	TEXT:FILE=[] ... Genomic regions to filter for, as a file with one region per line, either in the format "chr" (for whole chromosomes), "chr:position", "chr:start-end", "chr:start..end", or tab- or space-delimited "chr position" or "chr start end". Positions are 1-based and inclusive (closed intervals). The option can be provided multiple times, see also --filter-region-set.
--filter-region-bed	TEXT:FILE=[] ... Genomic regions to filter for, as a BED file. This only uses the chromosome, as well as start and end information per line, and ignores everything else in the file. Note that BED uses 0-based positions, and a half-open [) interval for the end position; simply using columns extracted from other file formats (such as vcf or gff) will not work. The option can be provided multiple times, see also --filter-region-set.
--filter-region-gff	TEXT:FILE=[] ... Genomic regions to filter for, as a GFF2/GFF3/GTF file. This only uses the chromosome, as well as start and end information per line, and ignores everything else in the file. The option can be provided multiple times, see also --filter-region-set.
--filter-region-vcf	TEXT:FILE=[] ... Genomic regions to filter for, as a VCF file (such as a known-variants file). This only uses the chromosome and position per line, and ignores everything else in the file. The option can be provided multiple times, see also --filter-region-set.
--filter-region-set	TEXT:{union,intersection}=union If multiple genomic region filters are set, decide on how to combine the loci of these filters.
--filter-samples-include	TEXT Excludes: --filter-samples-exclude Sample names to include (all other samples are excluded); either (1) a comma- or tab-separated list, or (2) a file with one sample name per line. If no sample filter is provided, all samples in the input file are used. The option considers --sample-name-list or --sample-name-prefix for file types that do not contain sample names. Note that this option can only be used if a single file is given as input.
--filter-samples-exclude	TEXT Excludes: --filter-samples-include Sample names to exclude (all other samples are included); either (1) a comma- or tab-separated list, or (2) a file with one sample name per line. If no sample filter is provided, all samples in the input file are used. The option considers --sample-name-list or --sample-name-prefix for file types that do not contain sample names. Note that this option can only be used if a single file is given as input.
Window
--window-width	Required. UINT=0 Width of each window along the chromosome.
--window-stride	UINT=0 Stride between windows along the chromosome, that is how far to move to get to the next window. If set to 0 (default), this is set to the same value as the --window-width.
Settings
--resolution	UINT:POSITIVE=100 Resolution of the spectrum histogram, that is, the number of bins of frequencies. This is hence also the vertical resolution (in pixels) of the resulting images.
--max-frequency	FLOAT:(FLOAT in [0 - 1]) AND (POSITIVE)=1 Maximum frequency, that is, the y-axis cutoff; default is 1.0. Frequencies above the maximum will be assinged to the highest bin. When using --spectrum-type folded, consider setting this option to 0.5, as that is the maximum of the folded spectrum.
--spectrum-type	TEXT:{folded,unfolded}=unfolded Type of spectrum to compute. That is, which frequencies do the values in the heat map represent: Either the frequency of the alternative allele (unfolded, default; uses the highest count/frequency allele that is not the reference allele as given in the input file, with frequencies in range [0, 1]), or the frequency of the minor allele (folded; uses the allele with the second highest count/frequency after the major (most common) allele, with frequencies in range [0, 0.5]).
--average-method	TEXT:{arithmetic,geometric,harmonic,counts}=harmonic If multiple samples are used (present in the file, and not filtered out), either compute the average of the frequencies per sample (using either arithmetic, geometric, or harmonic mean), or sum up the allele counts per sample, and then compute the frequency from that. The former gives each sample the same weight, while in the latter case, samples with more counts (more sequence reads) have a higher influence. If harmonic mean is used, we apply a correction for frequencies of zero, which happens in samples that do not have any alternative/minor allele counts.
--fold-undetermined-positions	Only relevant if --spectrum-type unfolded is set. By default, positions with undetermined reference alleles ('N') are skipped in the unfolded spectrum. If however this option is set, these positions are instead folded; that is, we then assume the major allele with the highest count/frequency to be the reference allele.
--write-individual-bmps	If set, write individual heatmap files for each chromosome, in bitmap format, in addition to the svg heatmap that contains all (not filtered) chromosomes.
Output
--out-dir	TEXT=. Directory to write files to
--file-prefix	TEXT File prefix for output files. Most grenedalf commands use the command name as the base name for file output. This option amends the base name, to distinguish runs with different data.
--file-suffix	TEXT File suffix for output files. Most grenedalf commands use the command name as the base name for file output. This option amends the base name, to distinguish runs with different data.
--compress	If set, compress the output files using gzip. Output file extensions are automatically extended by .gz.
Global Options
--allow-file-overwriting	Allow to overwrite existing output files instead of aborting the command.
--verbose	Produce more verbose output.
--threads	UINT Number of threads to use for calculations.
--log-file	TEXT Write all output to a log file, in addition to standard output to the terminal.

Citation

When using this method, please do not forget to cite

Lucas Czech, Moises Exposito-Alonso. Grenedalf: Genome Analyses of Differential Allele Frequencies. Manuscript in preparation, 2021. doi: