Genome Downsampler

Table of Contents

• Command Line Interface (CLI) Flags
  • Required Flags
  • Optional Flags
  • Usage Examples
• Installation guide
  • Dependencies
    • Common
    • HTSlib
    • OR-Tools
  • Install using precompiled binaries
  • Building from source

Command Line Interface (CLI) Options

This section details the available CLI options for configuring the genome-downsampler application. Each option allows you to customize the behavior and output of the downsampling process.

Positional Arguments

• INPUT_FILEPATH : Input file path

  • Path to the input .bam file containing DNA sequences. This argument is required.

• MAX_COVERAGE : Maximum coverage

  • Maximum coverage per reference genome's base pair index. This argument is required.

Optional Arguments

• -h, --help : Help

  • Print help message and exit.

• -o, --output TEXT : Output file path

  • Path to the output .bam file. Default is "output.bam" in the input file's directory.

• -a, --algorithm TEXT : Algorithm

  • Algorithm to use for downsampling. Options are: quasi-mcp-cpu, quasi-mcp-cuda, mcp-cpu, qmcp-cpu, . Default is quasi-mcp-cpu.

• -b, --bed TEXT:FILE : BED file with amplicon bounds

  • Path to .bed file specifying amplicon bounds for filtering or prioritization based on the selected algorithm.

• -t, --tsv TEXT:FILE : TSV file with primer pairings

  • Path to .tsv file describing pairs of primers from the .bed file to create amplicons.

• -p, --preprocessing-out TEXT : Output file for preprocessed reads

  • Path to .bam file for storing reads filtered out during preprocessing. Useful for debugging purposes.

• -l, --min-length UINT : Minimum sequence length

  • Minimum length of DNA sequences to retain. Sequences shorter than this length will be filtered out. Default is 90.

• -q, --min-mapq UINT : Minimum MAPQ value

  • Minimum Mapping Quality (MAPQ) value of sequences to retain. Sequences with MAPQ lower than this value will be filtered out. Default is 30.

• -@, --threads UINT : Number of threads

  • Number of threads for htslib read/write operations. Default is 2.

• -v, --verbose : Verbose mode

  • Enable additional logging for detailed execution information.

Usage Examples

1. Basic usage:

   genome-downsampler /data/input.bam 100

2. Advanced usage with optional arguments:

   genome-downsampler /data/input.bam 100 -a quasi-mcp-cuda -v -l 100 -q 50 -p /data/filtered_out_prep.bam -o /data/output.bam -b /data/primers.bed -t /data/pairs.tsv

3. Verbose mode with preprocessing output:

   genome-downsampler /data/input.bam 100 -v -p /data/filtered_out_prep.bam -o /data/output.bam

4. Using amplicon filtering:

   
   genome-downsampler /data/input.bam 100 -v -o /data/output.bam -b /data/primers.bed -t /data/pairs.tsv

## Installation guide
### Dependencies
This software only supports GNU/Linux systems, if you are a Windows user, we recommend using WSL. In order to run (or compile), the [**HTSlib**](https://github.com/samtools/htslib) and [**OR-Tools**](https://github.com/google/or-tools) are required to be installed on the your machine.

#### Common
Install the following common dependencies by running:

Debian/Ubuntu/Linux Mint:
```bash
sudo apt install autoconf automake make gcc perl zlib1g-dev libbz2-dev liblzma-dev libcurl4-gnutls-dev libssl-dev

Fedora/Red Hat:

sudo dnf install autoconf automake make gcc perl zlib-devel bzip2-devel xz-devel libcurl-devel openssl-devel

OpenSUSE:

sudo zypper install autoconf automake make gcc perl zlib-devel libbz2-devel xz-devel libcurl-devel libopenssl-devel

Arch Linux:

sudo pacman -S autoconf automake make gcc perl zlib bzip2 xz curl openssl

HTSlib

If you prefer to install only HTSlib, you can use the following script. For the full installation guide, visit here:

wget https://github.com/samtools/htslib/releases/download/1.20/htslib-1.20.tar.bz2
tar -xf htslib-1.20.tar.bz2
cd htslib-1.20
make
sudo make install

Alternatively, you can install samtools via package manager, since HTSlib is part of the samtools project.

Debian/Ubuntu/Linux Mint:

sudo apt install samtools

Fedora/Red Hat:

sudo dnf install samtools

OpenSUSE:

sudo zypper install samtools

Arch Linux:

sudo pacman -S samtools

OR-Tools

Many package managers does not provide OR-Tools library. To install it on your machine, download the appropriate binaries from here and extract the files.

Now, supposing that ORTOOLS_DIR_NAME represents the path to the extracted directory, use the following commands:

sudo cp -r ${ORTOOLS_DIR_NAME}/bin/* /usr/local/bin/
sudo cp -r ${ORTOOLS_DIR_NAME}/lib/* /usr/local/lib/
sudo cp -r ${ORTOOLS_DIR_NAME}/include/* /usr/local/include/
sudo cp -r ${ORTOOLS_DIR_NAME}/share/* /usr/local/share/

Install using precompiled binaries

TODO

Building from source

1. install the dependencies,
2. clone the repository,
3. navigate to the repository directory and run mkdir build && cd build && cmake .. && cmake --build .,
4. the binary file location: <repository-dir>/build/src/genome-downsampler.