## 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](https://github.com/Ebedthan/hyperex/releases) 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] ``` #### Flags: ``` --force Force output overwritting -q, --quiet Decreases program verbosity -h, --help Prints help information -V, --version Prints version information ``` #### Options: ``` -f, --forward-primer ... Specifies forward primer sequence. Can be a sequence with degenerate bases -r, --reverse-primer ... Specifies reverse primer sequence. Can be a sequence with degenerate bases --region ... Specifies a hypervariable region to extract -m, --mismatch Specifies number of allowed mismatch [default: 0] -p, --prefix Specifies the prefix for the output files [default: hyperex_out] ``` #### Args: ``` Input fasta file. Can be gzip'd, xz'd or bzip'd ``` ## Requirements ### Mandatory - [Rust](https://rust-lang.org) 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](https://no-color.org/) environment variable. ## Bugs Submit problems or requests to the [Issue Tracker](https://github.com/Ebedthan/hyperex/issues).