Locityper

https://locityper.vercel.app/
Admin
Locityper is a targeted genotyper for complex polymorphic genes using short and long-read whole...
Tokens:6,616
Snippets:101
Trust Score:7.8
Update:6 months ago
Show doc for...
Tokens:
Raw
### Manual Installation Steps

Source: https://locityper.vercel.app/install

Steps for manually installing Locityper from source, including cloning the repository and building the project.

```bash
git clone https://github.com/tprodanov/locityper
cd locityper
git clone https://github.com/smarco/WFA2-lib WFA2
cargo build --release
cargo install
```

--------------------------------

### Example CSV Output

Source: https://locityper.vercel.app/test_dataset

Sample format of the generated genotype summary CSV file.

```text
sample  locus  genotype             quality  total_reads  unexpl_reads  weight_dist  warnings
gts     MUC6   HG00621.1,HG00621.2  108.8    3738         1             0.00000      *
gts     MUC16  HG00621.1,HG00621.2  585.8    13969        16            0.00000      *
```

--------------------------------

### Clone Locityper Repository

Source: https://locityper.vercel.app/install

Clone the Locityper repository to begin Docker or Singularity installation.

```bash
git clone https://github.com/tprodanov/locityper
cd locityper
```

--------------------------------

### Install Locityper with Conda

Source: https://locityper.vercel.app/install

Use this command to install Locityper via Conda or Mamba. Ensure you are installing the latest release version.

```bash
conda install -c bioconda locityper
```

--------------------------------

### Specify multiple input BAM/CRAM files for Locityper preproc

Source: https://locityper.vercel.app/input_output

Provides examples for specifying multiple alignment files (BAM/CRAM) for Locityper preprocessing. The `--no-index` flag is used for unmapped files.

```bash
locityper preproc -a readsA.bam -a readsB.bam --no-index ...
```

--------------------------------

### Specify multiple input FASTQ files for Locityper preproc

Source: https://locityper.vercel.app/input_output

Demonstrates how to provide multiple FASTQ files for preprocessing, either as individual files or grouped by sample. Ensure all files correspond to the same sample.

```bash
locityper preproc -i readsA.fq.gz -i readsB.fq.gz ...
```

```bash
locityper preproc -i readsA1.fq.gz readsA2.fq.gz \
    -i readsB1.fq.gz readsB2.fq.gz ...
```

--------------------------------

### Recruit Reads Using a List of Input/Output Files

Source: https://locityper.vercel.app/commands

Recruit reads using a two-column file that maps input FASTA files to output FASTQ files. This method is useful for managing complex recruitment scenarios.

```bash
locityper recruit -i/-a/-I input -l list
```

--------------------------------

### Build Locityper Singularity Container

Source: https://locityper.vercel.app/install

Build the Locityper Singularity container image. This can be done with or without sudo privileges.

```bash
# Without sudo
singularity build --fakeroot locityper.sif containers/locityper.def
# Or with sudo
sudo singularity build locityper.sif containers/locityper.def
```

--------------------------------

### Configure Locityper Solver Steps

Source: https://locityper.vercel.app/commands

Specify solver steps and their parameters using the -S argument. Each step can be configured with the number of genotypes to process (i) and optimization attempts (a).

```bash
locityper -S greedy:i=5k,a=1 -S anneal:i=20,a=20
```

--------------------------------

### Specify input files using a list file

Source: https://locityper.vercel.app/input_output

Shows how to use a list file to specify various types of input files for Locityper commands. Ensure all entries in the list file use the same flag.

```bash
p reads1.fq.gz reads2.fq.gz
```

```bash
p reads*.fq.gz
```

```bash
pi reads.fq.gz
```

```bash
s reads.fq.gz
```

```bash
a alns.bam
```

```bash
u reads.bam
```

```bash
ui reads.bam
```

--------------------------------

### Preprocess using similar dataset

Source: https://locityper.vercel.app/commands

Use an already preprocessed file to speed up preprocessing. Ensure datasets have similar characteristics, sequencing technology, and library preparation. Both datasets must have the same file format and similar read name structure.

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

--------------------------------

### Compile Locityper with ILP Solvers

Source: https://locityper.vercel.app/install

Enable ILP solvers by compiling with the 'highs' or 'gurobi' features. Instructions for linking Gurobi are provided separately.

```bash
cargo build --release --features highs
# OR
cargo build --release --features gurobi
```

--------------------------------

### Create Loci Database

Source: https://locityper.vercel.app/test_dataset

Construct the database of target loci using the VCF, reference genome, and k-mer counts.

```bash
locityper target -d db -v hprc.vcf.gz -r genome.fa -j counts.jf -L loci.bed
```

--------------------------------

### Preprocess WGS dataset

Source: https://locityper.vercel.app/commands

Prepares WGS data for genotyping by examining read alignments to a simple reference region.

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

```bash
locityper preproc --describe -o bg/SAMPLE
```

--------------------------------

### Preprocess BAM/CRAM files

Source: https://locityper.vercel.app/commands

Uses existing read mappings or unmapped BAM/CRAM files for preprocessing.

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

--------------------------------

### Construct target locus database from FASTA

Source: https://locityper.vercel.app/commands

Directly provides locus alleles using a FASTA file while requiring reference coordinates for off-target k-mer evaluation.

```bash
locityper target -d db -r reference.fa -j counts.jf \
    -l locus_name chr:start-end alleles.fa
```

--------------------------------

### Run Targeted Genotyping

Source: https://locityper.vercel.app/test_dataset

Perform genotyping on the preprocessed dataset using the generated database.

```bash
locityper genotype -i reads/{1,2}.fastq.gz -d db -p bg -o gts
```

--------------------------------

### Preprocess WGS Dataset

Source: https://locityper.vercel.app/test_dataset

Align reads to identify background read depth distribution and error profiles.

```bash
locityper preproc -i reads/{1,2}.fastq.gz -r genome.fa -j counts.jf -o bg
```

--------------------------------

### Index Reference and Count K-mers

Source: https://locityper.vercel.app/test_dataset

Prepare the reference genome and generate k-mer counts required for downstream analysis.

```bash
samtools faidx genome.fa
jellyfish count --canonical --lower-count 2 --out-counter-len 2 --mer-len 25 \
    --threads 8 --size 3G --output counts.jf genome.fa
```

--------------------------------

### Recruit Reads for Multiple Loci from Separate Files

Source: https://locityper.vercel.app/commands

Recruit reads for multiple loci, where each locus is defined in a separate FASTA file. Output FASTQ files are named according to the locus names.

```bash
locityper recruit -i/-a/-I input -s target/{}.fa -o output/{}.fastq
```

--------------------------------

### Compile Locityper in Offline Mode

Source: https://locityper.vercel.app/install

Compile Locityper offline by first running 'cargo vendor' on a machine with internet access, copying directories, and then building.

```bash
cargo build --release --offline
```

--------------------------------

### Custom BED file for read recruitment

Source: https://locityper.vercel.app/commands

Specify a custom BED file for read recruitment during genotyping. This can be used to cover repeat copies or coordinates for a different reference genome. Use `@@` for database root and `@` for subdirectories.

```bash
locityper genotype ... --recr-bed @@name.bed
```

```bash
locityper genotype ... --recr-bed @name.bed
```

--------------------------------

### Construct target locus database from VCF

Source: https://locityper.vercel.app/commands

Extracts locus alleles from a pangenome VCF file to build a target database.

```bash
locityper target -d db -r reference.fa -j counts.jf \
    -v pangenome.vcf.gz -l locus_name chr:start-end
```

```bash
locityper target -d db -r reference.fa -j counts.jf \
    -v pangenome.vcf.gz -l locus1 chr:start-end \
    -L loci2.bed -L loci3.bed -l locus4 chr:start-end
```

--------------------------------

### Run Locityper Container

Source: https://locityper.vercel.app/install

Execute Locityper commands within its Singularity container. Dependencies can also be run via the container.

```bash
./locityper.sif command [args]
# If needed, you can execute dependencies with
./locityper.sif jellyfish/minimap2/strobealign [args]
# You can also explicitely run singularity
singularity exec locityper.sif ...
```

--------------------------------

### Generate Jellyfish k-mer counts

Source: https://locityper.vercel.app/input_output

Calculates k-mer counts for a reference genome using Jellyfish, a required input for Locityper. Adjust parameters like k-mer length and threads as needed.

```bash
jellyfish count --canonical --lower-count 2 --out-counter-len 2 --mer-len 25 \
    --threads 8 --size 3G --output counts.jf genome.fa
```

--------------------------------

### Compile Locityper without GCC

Source: https://locityper.vercel.app/install

Compile Locityper without the WFA library and GCC compiler to reduce dependencies. The 'align' command will be unavailable.

```bash
git clone https://github.com/tprodanov/locityper
cd locityper
cargo build --release --no-default-features
cargo install
```

--------------------------------

### Align sequences using Locityper

Source: https://locityper.vercel.app/commands

Commands for performing global sequence alignment on input files or specific pairs.

```bash
locityper align -i sequences.fasta -o alignments.paf.gz -A
```

```bash
locityper align -i sequences.fasta -o alignments.paf.gz \
    -p name1,name2 name3,name4 ...
```

--------------------------------

### Recruit Reads for Multiple Loci from a Single File

Source: https://locityper.vercel.app/commands

Recruit reads for multiple loci defined within a single FASTA file. Sequence names must follow the 'locus*anything_else' format. Output FASTQ files are named based on the locus prefix.

```bash
locityper recruit -i/-a/-I input -S multi_targets.fa -o output/{}.fastq
```

--------------------------------

### Convert Locityper Predictions to FASTA

Source: https://locityper.vercel.app/input_output

Generate predicted haplotypes in FASTA format from Locityper's output. This feature requires version 0.16.5 or later. The output format for each entry includes sample and haplotype information.

```bash
/path/to/locityper/extra/into_fasta.py -i gts.csv -d db -o out-dir
```

```plaintext
>SAMPLE HAPLOTYPE qual=XX ...
```

--------------------------------

### Convert Locityper Predictions to VCF

Source: https://locityper.vercel.app/input_output

Use this script to convert Locityper's genotype predictions (gts.csv) into a VCF file, referencing an existing pangenome VCF. Ensure the correct database and reference genome are specified.

```bash
/path/to/locityper/extra/into_vcf.py -i gts.csv -d db \
    -v pangenome.vcf -g GRCh38 -o out-dir
```

--------------------------------

### Genotype WGS dataset

Source: https://locityper.vercel.app/commands

Genotype a dataset using Locityper. You can limit genotyping to a subset of loci using `--subset-loci` and specify genotype priors using `--priors`.

```bash
locityper genotype -i/-a/-I input -d db -p bg/SAMPLE -o analysis/SAMPLE
```

--------------------------------

### Summarize Results to CSV

Source: https://locityper.vercel.app/test_dataset

Convert JSON genotype results into a single CSV file.

```bash
/path/to/locityper/extra/into_csv.py -i ./gts -o gts.csv
```

--------------------------------

### Convert Locityper JSON output to CSV

Source: https://locityper.vercel.app/input_output

A script to convert Locityper's JSON output files into a single CSV file. It automatically extracts sample names from directory structures and can compress the output.

```bash
/path/to/locityper/extra/into_csv.py \
    -i analysis/./* -o gts.csv
```

--------------------------------

### Recruit Reads for a Single Locus

Source: https://locityper.vercel.app/commands

Recruit reads for a single locus from input files to a target FASTA file, outputting to a FASTQ file. Supports multiple locus haplotypes within the target FASTA.

```bash
locityper recruit -i/-a/-I input -s targets.fa -o recruited.fastq
```

--------------------------------

### Genotype with weighted mode

Source: https://locityper.vercel.app/commands

Enable weighted mode for genotyping to upweight specific subregions like exons. Requires a file mapping loci to BED files with weights for haplotypes.

```bash
locityper genotype ... --reg-weights paths.txt
```

```bash
locityper genotype ... --reg-weights <(echo "LOCUS PATH")
```

```bash
locityper genotype ... --reg-weights <<<"LOCUS PATH"
```

--------------------------------

### Process Pangenome VCF with vcfbub and tabix

Source: https://locityper.vercel.app/input_output

Transforms a raw pangenome VCF file to remove overlapping variants and indexes it for use with Locityper. Ensure the input VCF is from Minigraph-Cactus.

```bash
vcfbub -l 0 -i hprc-v1.1-mc-grch38.raw.vcf.gz | bgzip > hprc-v1.1-grch38.vcf.gz
tabix -p vcf hprc-v1.1-grch38.vcf.gz
```

--------------------------------

### Prune target haplotypes

Source: https://locityper.vercel.app/commands

Reduce database size and improve performance by pruning haplotypes based on sequence divergence.

```bash
locityper prune -i db -o pruned_db
```

--------------------------------

### Identify reference coordinates for alleles

Source: https://locityper.vercel.app/commands

Aligns alleles to the reference genome to determine potential coordinates when exact locations are unknown.

```bash
minimap2 -cx asm20 genome.fa alleles.fa | \
    awk '{ printf("%s:%d-%d\n",$6,$8+1,$9) }' | \
    sort | uniq -c | sort -k1,1nr | head -n20
```

--------------------------------

### Recruit Reads to Distinct Loci from Single Input

Source: https://locityper.vercel.app/commands

When using a single input FASTA file with the -S argument, the --distinct flag treats each FASTA sequence as a separate target. Be mindful of memory usage with many targets.

```bash
locityper recruit -i/-a/-I input -S single_input.fa -o output/{}.fastq --distinct
```

--------------------------------

### Parallelize haplotype alignment

Source: https://locityper.vercel.app/commands

Align haplotypes across multiple loci in parallel using GNU Parallel.

```bash
threads=8
ls db/loci/*/haplotypes.fa.gz | parallel -ut -P1 --plus \
    locityper align -i {} -o {..}.paf.gz -@ $threads -A \
    '||' touch {..}.paf.err
```

--------------------------------

### Check and manage target locus overlaps

Source: https://locityper.vercel.app/commands

Lists overlapping target regions and optionally moves redundant loci to a specific directory.

```bash
/path/to/locityper/extra/check_overlaps.py db [--move]
```
Tokens:
Raw