droeatumn/kpi

KPI

main.nf makes the predictions.

Dependancies

Install Java, Groovy, Nextflow, Docker, and Git. Create accounts in GitHub and Docker Hub. Add 'docker.enabled = true' and 'docker.fixOwnership = true' to your Nexflow configuration (e.g., $HOME/.nextflow/config). Make sure Docker is running and you are logged in to Docker Hub.

Running

Input
There are two input options.
1. An ID along with a folder of fasta or fastq files, optionally gzipped. (--raw and --id)
2. A two-column text file, where the first column is an ID, and the second column is a path to a fasta or fastq file (--map). Each ID may have multiple rows. The paths to the files be absolute or relative, but the files must be in the same directory as the map file or under it. If using relative paths, the paths must start with the _parent_ folder of the map file.

Option 1 is more efficient with respect to disk space.

Output
For each input ID, an output text file will be created named id_prediction.txt. Each ID's output file contains a header line and a second line with the haplotype pair predictions and gene predictions.
Each haplotype within a pair is separated by a '+'. If the prediction is ambiguous, each pair of haplotypes is separated by '|'. e.g.,
'cA01˜tA01+cA01˜tB01|cA01˜tA01+cB05˜tB01|cA01˜tB01+cB05˜tA01' means haplotype
'cA01˜tA01 and cA01˜tB01' or 'cA01˜tA01 and cB05˜tB01' or 'cA01˜tB01 and cB05˜tA01'.

The reference haplotypes are defined at https://github.com/droeatumn/kpi/blob/master/input/haps.txt

Running
Use 'raw' to indicate the input directory, and 'output' to indicate the directory to put the output. The defaults are 'raw' and 'output' under the location where KPI was pulled.

Option 1: Provide and ID (--id) and a folder (--raw) with its raw data
./main.nf --id ID --raw inDir --output outDir
e.g., ./main.nf --id id1 --raw ~/input --output ~/output

Option 2: Provide a file with a map (--map) from IDs to their raw data
./main.nf --map mapFile.txt --output outDir
e.g., ./main.nf --map ~/input/idstoRaw.txt --output ~/output
In this example the path to files in idstoRaw.txt are somewhere under ~/input/.

Example using data in the image, so no input is required.
Example 1: cA01˜tA01+cB01˜tB01 with --raw.
Run the following command for an example of interpreting synthetic reads created from sequences with Genbank IDs KP420439 and KP420440 (https://www.ncbi.nlm.nih.gov/nuccore/KP420439 and https://www.ncbi.nlm.nih.gov/nuccore/KP420440)). These two haplotypes contain all the genes, so the haplotype predictions are very ambiguous.

./main.nf --id ex1 --raw ~/git/kpi/input/example1 --output ~/output

To run another example, replace 'example1' with 'example2'.

Example 2: cA01˜tA01+cA01˜tB01 with --map and --id.
Run the following command for an example of interpreting synthetic reads created from sequences with Genbank IDs KP420439 and KU645197 (https://www.ncbi.nlm.nih.gov/nuccore/KP420439 and https://www.ncbi.nlm.nih.gov/nuccore/KU645197)).

./main.nf --id ex2 --map ~/git/kpi/input/example2/example2.txt --output ~/output

To run another example, replace 'example2' with 'example1'.

Example 3: com***e Example 1 and 2 with --map and --id.
./main.nf --id ex12 --map ~/git/kpi/input/example1-2.txt --output ~/output

Miscellaneous
Hardware
For targeted sequencing, kpi requires approximately 4 CPU, 8G RAM total and 20G disk space. For WGS, it requires around 13 CPU, 16G RAM total and 100G disk space.

Raw data
The software assumes average coverage for both chromosomes is less than 255. If this is not the case for your data, please downsample before running. Support for high coverage data is a future enhancement.

Containers
To run without a container, use the --nocontainer parameter. To use a container other than the default (droeatumn/kpi:latest), use the --container parameter.

Reference
Roe D, Kuang R. Accurate and Efficient KIR Gene and Haplotype Inference From Genome Sequencing Reads With Novel K-mer Signatures. Front Immunol (2020) 11:583013. (https://doi.org/10.3389/fimmu.2020.583013)