Pangenome map

Filtered graph mode

The steps performed for filtered graphs are all included in the more complex haplotype sampling workflow, therefore refer to the specific commands below for information.

Note that only filtered graphs should be used for running aDNA samples. Unfiltered graphs are preferred for highly pure, modern samples (however, filtered graphs will perform fine for both sample categorites).

Unfiltered graph mode (haplotype subsampling)

In unfiltered graph mode, a subset of paths (haplotypes) are extracted from the pangenome graph to create a personalised pangenome reference for each library. This uses k-mer profiles from the reads, and thus should not be used for aDNA samples.

Indexing and mapping settings differ for ancient vs. modern samples, due to the shorter reads in aDNA libraries.

kmc

Counts k-mers in FASTQ files to inform haplotype subsampling.

Usage: kmc [options] <input_file_name> <output_file_name> <working_directory>

Example grave command:

kmc -k${params.aDNAkmerHaplSubSam} -ci${params.kffKmerMinimum} -t${task.cpus} -m${memory} -sm -fq -okff ${reads} ${meta.read_group} .

• -k k-mer value appropriate to read type (applied automatically based on sample metadata)
• -ci exclude k-mers occurring less than times
• -t threads
• -m memory
• -sm enforce strict memory
• -fq fastq inputs
• -o kff output

vg haplotypes

Generates the subsampled graph using the k-mer profile. Uses the pre-generated .hapl index rather than auto-generating one, to ensure parameters are also set appropriately for the given sample type.

Usage: vg haplotypes [options] -i graph.hapl -k kmers.kff -g output.gbz graph.gbz

Example grave command:

vg haplotypes --threads ${task.cpus} --verbosity 2 --include-reference --diploid-sampling --haplotype-input *.adna.hapl --kmer-input ${meta.read_group}.kff --gbz-output ${basename}.${meta.read_group}.gbz ${graph}

• --include-reference include named and reference paths in the output
• --diploid-sampling choose the best pair from the sampled haplotypes
• --haplotype-input pre-generated .hapl index
• --kmer-input k-mer profile from the sample
• --gbz-output output graph name

vg index

Produces .dist index for the subsampled graph.

Usage: vg index [options] <graph1.vg> [graph2.vg ...]

Example grave command:

vg index --threads ${task.cpus} --dist-name ${basename}.${meta.read_group}.dist ${basename}.${meta.read_group}.gbz

vg minimizer

Produces .min index for the subsampled graph.

Usage: vg minimizer [options] -d graph.dist -o graph.min graph

Example grave command:

vg minimizer --threads ${task.cpus} --kmer-length ${params.aDNAkmerMinimizer} --window-length ${params.aDNAwindowMinimizer} --distance-index ${basename}.${meta.read_group}.dist --output-name ${basename}.${meta.read_group}.min ${basename}.${meta.read_group}.gbz

vg giraffe

Maps library reads to the subsampled graph, producing a GAM file output. Instead of using the standard workflow with auto index generation, we supply the custom indexes. For ancient samples mapping parameters are modelled after bwa aln settings. For modern samples, settings are modelled after bwa mem.

Usage: vg giraffe -Z graph.gbz [-d graph.dist [-m graph.withzip.min -z graph.zipcodes]] <input options> [other options] > output.gam

Example grave command:

vg giraffe --progress --mismatch 3 --gap-open 11 --gap-extend 4 --fastq-in ${reads} --gbz-name ${basename}.${meta.read_group}.gbz --dist-name ${basename}.${meta.read_group}.dist --minimizer-name ${basename}.${meta.read_group}.min --output-format GAM --threads ${task.cpus} > ${meta.read_group}.gam

• --mismatch mismatch penalty
• --gap-open gap open penalty
• --gap-extend gap extension penalty
• --fastq-in input reads
• --gbz-name subsampled graph
• --dist-name dist index
• --minimizer-name minimizer index
• --output-format specify output type

vg filter

Filters GAM files after mapping.

Usage: vg filter [options] <alignment.gam> > out.gam

Example grave command:

vg filter ${args} ${args2} ${args3} -t ${task.cpus} -x ${basename}.${meta.read_group}.gbz -r ${params.minimumScorePrimaryAlign} -fu -v ${meta.read_group}.gam > ${meta.read_group}.filtered.gam

• ${args} set by --gamDiscardUnmapped: true provides --only-mapped, and vg filter will remove unmapped reads from the GAM
• ${args2} set by gamFilterMapQ: true provides --min-mapq ${params.minimumMapQFilter}, and vg filter will remove reads under the threshold MAPQ et by --minimumMapQFilter
• ${args3} set by --gamDefrayEnds, true provides --defray-ends ${params.defrayEndsLength}, and vg filter will clip back the ends of ambiguously aligned reads up to N bases set by --defrayEndsLength
• -t threads
• -x graph file
• -r minimum primary alignment score (in practice this is fraction identity, due to -fu being set)
• -fu normalises scores based on length & uses substitution count instead of score, in practice, uses fraction identity instead of raw score
• -v verbose

vg stats

Reports summary statistics for sample mappings, this is done on the filtered GAM.

Usage: vg stats [options] [<graph file>]

Example grave command:

vg stats --alignments ${meta.read_group}.filtered.gam ${basename}.${meta.read_group}.gbz > ${meta.read_group}_alignment-stats.txt