hyperex

About

HyperEx (pronounced "Hyper Ex" for Hypervariable region Extractor) is a tool that extracts 16S ribosomal RNA (rRNA) hypervariable region based on a set of primers. By default when no option is specified, hyperex extracts all hypervariable region from the supplied sequences assuming 16S rRNA sequences. To do this it has a set of built-in primer sequences which are universal 16S primers sequences. Nevertheless, the user can choose to specify the wanted region by specifying the --region option or by providing the primer sequences using --forward-primer and --reverse-primer. The --region option takes only the region names like "v1v2" or "v4v5" while the --forward-primer and --reverse-primer takes only the sequences which can contains IUPAC ambiguities.
For more than one needed region, one can use multiple time the --region, --forward-primer, reverse-primer options to specify the wanted region. Theses option takes only one argument, but can be repeat multiple time (see Examples below).

For more praticability, the user can also provide a supplied file containing primer sequences to extract the wanted region using the --region option. The primer sequences file should be a no header comma separated value file like:

FORWARD_PRIMER_1,REVERSE_PRIMER_1
FORWARD_PRIMER_2,REVERSE_PRIMER_2
...

Moreover, one can allow a number of mismatch in the primer sequence using the --mismatch option.

The outputs are a fasta file containing the extracted regions and a GFF3 file indicating the extracted regions positions.

Installation

Using prebuilt binaries

Please see the releases page for prebuilt binaries for major operating system

From crates.io

If you already have a functional rust installation you can easily do:

cargo install hyperex

And that's all!

From source

git clone https://github.com/Ebedthan/hyperex.git
cd hyperex

cargo build --release
cargo test

# To install hyperex in current directory
cargo install --path .

And you are good to go!

How to run hyperex ?

By default with no options

# reading data from a specified file
hyperex file.fa

# reading data from standard input
cat file.fa | hyperex

Using built-in 16S primer names

# reading data from a specified file
hyperex -f 27F -r 337R file.fa.gz

# reading data from standard input
zcat file.fa.gz | hyperex -f 27F -r 337R

Using built-in 16S region names

# reading data from a specified file
hyperex --region v3v4 file.fa.xz

# reading data from standard input
xzcat file.fa.xz | hyperex --region v3v4

Using custom primer sequences

# reading data from a specified file
hyperex -p prefix --forward-primer ATCG --reverse-primer TYAATG file.fa.bz2

# reading data from standard input
bzcat file.fa.bz2 | hyperex -p prefix --forward-primer ATCG --reverse-primer TYAATG

Using custom list of primers: primers.txt

hyperex --region primers.txt file.fa

Using multiple primers

hyperex --region v1v2 --region v3v4 file.fa

hyperex -f ATC -f YGA -r GGCC -r TTRC file.fa

Usage

Command line arguments

hyperex [FLAGS] [OPTIONS] <FILE>

Flags:

    --force      Force output overwritting
-q, --quiet      Decreases program verbosity
-h, --help       Prints help information
-V, --version    Prints version information

Options:

-f, --forward-primer <PRIMER>...    Specifies forward primer sequence. Can be a sequence with degenerate bases
-r, --reverse-primer <PRIMER>...    Specifies reverse primer sequence. Can be a sequence with degenerate bases
    --region <REGION>...            Specifies a hypervariable region to extract
-m, --mismatch <N>                  Specifies number of allowed mismatch [default: 0]
-p, --prefix <PATH>                 Specifies the prefix for the output files [default: hyperex_out]

Args:

<FILE>    Input fasta file. Can be gzip'd, xz'd or bzip'd

Requirements

Mandatory

• Rust in stable channel

Optional

• libgz for gz file support

• liblzma for xz file support

• libbzip2 for bzip2 file support

Note

hyperex use colored output in help, nevertheless hyperex honors NO_COLORS environment variable.

Bugs

Submit problems or requests to the Issue Tracker.