idemuxCPP - inline barcode demultiplexing

idemuxCPP is a command line tool designed to demultiplex paired-end fastq files from QuantSeq-Pool.

idemuxCPP can demultiplex based on i7, i5 and i1 inline barcodes. While this tool can generally be used to demultiplex on any barcodes (as long as they are correctly supplied and in the fastq header), it best performs when used in combination with Lexogen indices, as it will correct common sequencing errors in the sequenced barcodes. This will allow you to retain more reads from your sequencing experiment, while minimizing cross contamination.

idemuxCPP use is permitted under the following licence.

idemuxCPP is a direct translation of the python tool idemux (https://github.com/lexogen-tools/idemux) in order to decrease the runtime. It is 2 times faster than the python version.

General usage:

    idemuxCPP [-h] --r1 READ1 --r2 READ2 [--sample-sheet SAMPLE_SHEET] --out OUTPUT_DIR
           [--i1-start I1_START] [--i5-rc] [-v]

Run idemuxCPP:

    idemuxCPP --r1 read_1.fastq.gz --r2 read_2.fastq.gz --sample-sheet samples.csv --out /some/output/path --i1-start pos_in_read_2

Features

• FASTQ file demultiplexing based on i7, i5 or i1 barcodes
• Correction of barcode sequencing errors to maximize read yield (only works with Lexogen 12 nt UDIs, that have been sequenced at least 8 nt.

Getting started

To get stated with demultiplexing you need to:

1. Install idemuxCPP
2. Prepare a sample sheet csv
3. Run idemuxCPP

1. Installation

dependencies:

• compiler supporting C++11 standard and OpenMP

• boost C++ library version >= 1.55.0 (install the development versions of the following libraries (or install all e.g. in Ubuntu via package libboost-all-dev)

  • libboost-filesystem
  • libboost-system
  • libboost-iostreams
  • libboost-test (only required if you want to compile unit tests)

• zlib (e.g. zlib1g-dev in Ubuntu)

• gengetopt

Windows 10 64bit binary For windows you do not need to install any dependencies (they are included in the package). Simply download the pre-compiled windows binary from here windows binary. Extract the zip file. To execute the tool press windows+r, enter cmd, cd C:\\location_of_the_extracted_zip_file\bin and execute .\\idemuxCPP

From Source (distribution tar)

To configure, compile and install execute the following commands on your command line:

    ./configure [--help for additional configuration options]
    make
    make install

From Source (git) The installation from source requires additional tools and libraries:

• gnulib (autoconf, automake, etc.)

Generate the configure file with:

    autoreconf -i

Then proceed with ./configure and make like in the previous section.

From Linux Package

<table><thead><tr> <th> Debian </th> <th> Ubuntu </th> <th> Fedora </th> </tr></thead><tbody><tr> <td style="vertical-align:top"> <details><summary>Debian_12</summary><p><a href="https://download.opensuse.org/repositories/home:/Lexogen/Debian_12/i386/idemuxcpp_0.3.0-1_i386.deb"> idemuxcpp - 0.3.0 - 32 bit</a></p> <p><a href="https://download.opensuse.org/repositories/home:/Lexogen/Debian_12/amd64/idemuxcpp_0.3.0-1_amd64.deb"> idemuxcpp - 0.3.0 - 64 bit</a></p> </details> <details><summary>Debian_11</summary><p><a href="https://download.opensuse.org/repositories/home:/Lexogen/Debian_11/i386/idemuxcpp_0.3.0-1_i386.deb"> idemuxcpp - 0.3.0 - 32 bit</a></p> <p><a href="https://download.opensuse.org/repositories/home:/Lexogen/Debian_11/amd64/idemuxcpp_0.3.0-1_amd64.deb"> idemuxcpp - 0.3.0 - 64 bit</a></p> </details> <details><summary>Debian_10</summary><p><a href="https://download.opensuse.org/repositories/home:/Lexogen/Debian_10/i386/idemuxcpp_0.3.0-1_i386.deb"> idemuxcpp - 0.3.0 - 32 bit</a></p> <p><a href="https://download.opensuse.org/repositories/home:/Lexogen/Debian_10/amd64/idemuxcpp_0.3.0-1_amd64.deb"> idemuxcpp - 0.3.0 - 64 bit</a></p> </details> <details><summary>Debian_9.0</summary><p><a href="https://download.opensuse.org/repositories/home:/Lexogen/Debian_9.0/i386/idemuxcpp_0.3.0-1_i386.deb"> idemuxcpp - 0.3.0 - 32 bit</a></p> <p><a href="https://download.opensuse.org/repositories/home:/Lexogen/Debian_9.0/amd64/idemuxcpp_0.3.0-1_amd64.deb"> idemuxcpp - 0.3.0 - 64 bit</a></p> </details> </td> <td style="vertical-align:top"> <details><summary>xUbuntu_24.04</summary><p><a href="https://download.opensuse.org/repositories/home:/Lexogen/xUbuntu_24.04/amd64/idemuxcpp_0.3.0-1_amd64.deb"> idemuxcpp - 0.3.0 - 64 bit</a></p></details> <details><summary>xUbuntu_23.10</summary><p><a href="https://download.opensuse.org/repositories/home:/Lexogen/xUbuntu_23.10/amd64/idemuxcpp_0.3.0-1_amd64.deb"> idemuxcpp - 0.3.0 - 64 bit</a></p></details> <details><summary>xUbuntu_23.04</summary><p><a href="https://download.opensuse.org/repositories/home:/Lexogen/xUbuntu_23.04/amd64/idemuxcpp_0.3.0-1_amd64.deb"> idemuxcpp - 0.3.0 - 64 bit</a></p></details> <details><summary>xUbuntu_22.10</summary><p><a href="https://download.opensuse.org/repositories/home:/Lexogen/xUbuntu_22.10/amd64/idemuxcpp_0.3.0-1_amd64.deb"> idemuxcpp - 0.3.0 - 64 bit</a></p></details> <details><summary>xUbuntu_22.04</summary><p><a href="https://download.opensuse.org/repositories/home:/Lexogen/xUbuntu_22.04/amd64/idemuxcpp_0.3.0-1_amd64.deb"> idemuxcpp - 0.3.0 - 64 bit</a></p></details> <details><summary>xUbuntu_20.04</summary><p><a href="https://download.opensuse.org/repositories/home:/Lexogen/xUbuntu_20.04/amd64/idemuxcpp_0.3.0-1_amd64.deb"> idemuxcpp - 0.3.0 - 64 bit</a></p></details> </details><details><summary>xUbuntu_18.04</summary><p><a href="https://download.opensuse.org/repositories/home:/Lexogen/xUbuntu_18.04/amd64/idemuxcpp_0.3.0-1_amd64.deb"> idemuxcpp - 0.3.0 - 64 bit</a></p> </details><details><summary>xUbuntu_16.04</summary><p><a href="https://download.opensuse.org/repositories/home:/Lexogen/xUbuntu_16.04/i386/idemuxcpp_0.3.0-1_i386.deb"> idemuxcpp - 0.3.0 - 32 bit</a></p> <p><a href="https://download.opensuse.org/repositories/home:/Lexogen/xUbuntu_16.04/amd64/idemuxcpp_0.3.0-1_amd64.deb"> idemuxcpp - 0.3.0 - 64 bit</a></p></details> </td> <td style="vertical-align:top"> <details><summary>Fedora 40</summary><p><a href="https://download.opensuse.org/repositories/home:/Lexogen/Fedora_40/x86_64/idemuxcpp-0.3.0-39.1.x86_64.rpm"> idemuxcpp - 0.3.0 - 64 bit</a></p></details> <details><summary>Fedora 39</summary><p><a href="https://download.opensuse.org/repositories/home:/Lexogen/Fedora_39/x86_64/idemuxcpp-0.3.0-39.1.x86_64.rpm"> idemuxcpp - 0.3.0 - 64 bit</a></p></details> <details><summary>Fedora 38</summary><p><a href="https://download.opensuse.org/repositories/home:/Lexogen/Fedora_38/x86_64/idemuxcpp-0.3.0-39.1.x86_64.rpm"> idemuxcpp - 0.3.0 - 64 bit</a></p></details> <details><summary>Fedora 37</summary><p><a href="https://download.opensuse.org/repositories/home:/Lexogen/Fedora_37/x86_64/idemuxcpp-0.3.0-39.1.x86_64.rpm"> idemuxcpp - 0.3.0 - 64 bit</a></p></details> <details><summary>Fedora 36</summary><p><a href="https://download.opensuse.org/repositories/home:/Lexogen/Fedora_36/x86_64/idemuxcpp-0.3.0-39.1.x86_64.rpm"> idemuxcpp - 0.3.0 - 64 bit</a></p></details> </td> </tr></tbody></table>

on ubuntu you can install it for example with:

dpkg -i <idemuxcpp*.deb>

idemuxCPP is available via bioconda!

2. Preparing the sample sheet

In order to run idemuxCPP on your QuantSeq-Pool data you first need to prepare a csv file. We call this csv a sample sheet and it specifies which barcodes correspond to each sample.

This is a necessity as the software needs to know into which bins reads should be sorted during demultiplexing. A sample sheet can easily be generated by filling in an excel spreadsheet and exporting it as csv.

Example sample sheet (i7, i5 and i1 demuliplexing):

    sample_name,i7,i5,i1
    sample_0,AAAACATGCGTT,CCCCACTGAGTT,AAAACATGCGTT
    sample_1,AAAATCCCAGTT,CCCCTAAACGTT,AAAATCCCAGTT
    sample_2,GAAAATTTACGC,GCCCCTTTCAGA,GAAAATTTACGC
    sample_3,AAACTAACTGTC,CCCATCCATGTA,AAACTAACTGTC

A sample sheet consists of 4 columns and always starts with the header illustrated above. 'Sample_name' values will be used as output file names, while the sequences specified in i7,i5 & i1 will be used for demultiplexing.

Therefore, only specific, unique unambiguous combinations of sample names and barcodes are allowed. This means using duplicated or ambiguous combinations will result in an error. However, idemuxCPP will do its best to tell you where the problem lies, once this happens.

In brief the rules are:

1. Sample names need to be unique.
2. Barcode combinations need to be unique.
3. i7 and/or i5 indices have to be used consistently within the csv file. i7 and/or i5 indices need to be either present for all samples or none at all.
4. In contrast to i7/i5 indices, i1 indices can be used for a subset of samples in the cs