Locityper

Before locus genotyping can be performed, WGS dataset needs to be preprocessed. For that, please use

locityper preproc -i reads1.fastq [reads2.fastq] \
    -r reference.fa -j counts.jf -o bg/SAMPLE

This command creates output directory bg/SAMPLE for this specific sample. If you use long reads, please specify technology with --tech argument.

During sample preprocessing Locityper examines read alignments to a long simple region in the reference genome without significant duplications or other structural variations. Locityper attempts to automatically identify the genome version, however, if this does not happen, please use -b/--bg-region to provide such region (preferable ≥3 Mb). By default, the following regions are used: chr17:72950001-77450000 (CHM13), chr17:72062001-76562000 (GRCh38) and chr17:70060001-74560000 (GRCh37).

You can examine already preprocessed directory with

locityper preproc --describe -o bg/SAMPLE

Input files

If you already have read mappings to the whole genome, you can use them via

locityper preproc -a aligned.bam -r reference.fa -j counts.jf -o bg/SAMPLE

In some cases, reads are stored in an unmapped BAM/CRAM format. In cases like that you can use arguments -a reads.bam --no-index. For interleaved paired-end BAM/CRAM file, please use -^ flag. Non-interleaved paired-end unmapped BAM/CRAM files are not supported. Input FASTA/Q files can be compressed with gzip/bgzip, lz4 or brotli.

Locityper commands allow multiple input files for a single dataset. You can specify them by repeating -i/-a arguments:

locityper preproc -i readsA.fq.gz -i readsB.fq.gz ...
locityper preproc -i readsA1.fq.gz readsA2.fq.gz \
    -i readsB1.fq.gz readsB2.fq.gz ...
locityper preproc -a readsA.bam -a readsB.bam --no-index ...

Input files of different types (-i and -a) are not allowed, as well as multiple mapped BAM/CRAM files.

⚠️

All of the files must correspond to the same sample, same sequencing technology and should have roughly the same characteristics (read length, error rates).

⚠️

Please make sure to use the same input files for genotyping as for preprocessing.

Alternatively, you can specify an input list of files with -I list.txt where each line follows the format <flag> <file> [<file2>]:

Line	Same as	Comment
`p reads1.fq.gz reads2.fq.gz` `p reads*.fq.gz`	`-i reads*.fq.gz`	Paired-end FASTA/Q
`pi reads.fq.gz`	`-i reads.fq.gz -^`	Interleaved paired-end file
`s reads.fq.gz`	`-i reads.fq.gz`	Single-end FASTA/Q file
`a alns.bam` `a alns.bam index.bai`	`-a alns.bam` `-a alns.bam index.bai`	Mapped BAM/CRAM files
`u reads.bam`	`-a reads.bam --no-index`	Unmapped BAM/CRAM file
`ui reads.bam`	`-a reads.bam --no-index -^`	Unmapped interleaved file

Multiple lines are allowed, but all must have the same flag.

Subsampling

Locityper allows dataset subsampling (--subsample) during the preprocessing, as a way to speed up the process. Depending on the dataset and input coverage, small subsampling factors may produce inaccurate read depth estimates.

Using similar datasets

You can estimate WGS characteristics using an already preprocessed file (-~/--like). Preprocessing using existing dataset is significantly faster, but may produce incorrect results if datasets have noticeably different characteristics.

locityper preproc -i/-a input -~ bg/OTHER_SAMPLE \
    -r reference.fa -j counts.jf -o bg/SAMPLE

⚠️

Please use this feature with care―it should only be used if the two datasets are similar (produced with the same sequencing technology and similar library preparation).

This method still requires a couple minutes to count the number of reads in the dataset. You can also use --filesize argument for immediate preprocessing by simply comparing file sizes with a previously processed dataset.

⚠️

Both datasets must have the same file format (for example fastq.gz) and similar read name structure. Even different read name lengths may lead to incorrect predictions.

Multiple datasets

If you plan to analyze a large number of WGS datasets, it is most likely faster to process multiple datasets in parallel, each with one thread (-@ 1). Additionally, as the datasets are probably similar, it usually makes sense to use the similar-dataset feature (--like or --filesize). Nevertheless, you can additionally fully preprocess several randomly selected datasets and compare predicted parameters (--describe) with those, obtained using a similar dataset.

Preparing targets Genotyping