# BLUTILS
The `Blutils` tool allow user to run and generate consensus identities of Blast
results. Currently the BlastN is available.
## Installation
`Blutils` package could be installed directly from
[crates.io](https://crates.io/crates/blutils) using cargo:
```bash
cargo install blutils-cli
```
After installed, `Blutils` could be evoked using the `blu` command.
```bash
blu --help
```
The output should be close to:
```bash
A utility to make it easier to run and analyze Blast results
Usage: blu <COMMAND>
Commands:
build-db Build the blast database as a pre-requisite for the blastn command
blastn Execute the parallel blast and run consensus algorithm
check Check `Blutils` dependencies
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help information
-V, --version Print version information
```
## Check dependencies
Optionally you could check OS dependencies before run `Blutils`. Naturally BLutils
depends on Ncbi-Blast+ tool to be installed on the host system to perform
parallel blast search. To check if the host OS has these package installed run
the `Blutils` checker for linux systems:
```bash
blu check linux
```
Note: Currently the system check is available only for linux systems and assumes
that dependencies could be evoked directly from terminal.
## Run Blast with Blutils
The `Blutils` execution is simple. To check all available options evoke the
blast subcommand help:
```bash
blu blastn run-with-consensus --help
```
After inspect available options, simple run `Blutils` with test data. First
download test data from the project github directory:
```bash
export INPUT_DIR=https://raw.githubusercontent.com/sgelias/blutils/main/test/mock/input
curl ${INPUT_DIR}/query/query.fna > query.fna
curl ${INPUT_DIR}/query/ref_databases/mock-16S.fna > mock-16S.fna
curl ${INPUT_DIR}/query/ref_databases/mock-16S_taxonomies.tsv > mock-16S_taxonomies.tsv
```
Then run `Blutils`:
```bash
blu blastn run-with-consensus \
query.fna \
mock-16S.fna \
mock-16S_taxonomies.tsv \
output \
-t 6 \
--taxon bacteria \
--strategy relaxed \
-f
```
Seems the above commands, the output files could be found in output directory
which will contains two additional files named `blast.out` and
`blutils.consensus.json`. The first contains default Blast tabular response and
the former, the Blutils response, which will be close to:
```bash
[
{
"query": "NR025123.135626.Bac",
"taxon": {
"rank": "species",
"identifier": "shewanella-olleyana",
"percIdentity": 100.0,
"bitScore": 2695.0,
"alignLength": 1459,
"mismatches": 0,
"gapOpenings": 0,
"qStart": 1,
"qEnd": 1459,
"sStart": 1,
"sEnd": 1459,
"eValue": 0.0,
"taxonomy": "d__bacteria;p__pseudomonadota;c__gammaproteobacteria;o__alteromonadales;f__shewanellaceae;g__shewanella;s__shewanella-olleyana",
"mutated": true,
"consensusBeans": null
}
},
{
"query": "draft-5123",
"taxon": {
"rank": "species",
"identifier": "bacillus-mojavensis-subgroup",
"percIdentity": 100.0,
"bitScore": 815.0,
"alignLength": 441,
"mismatches": 0,
"gapOpenings": 0,
"qStart": 1,
"qEnd": 441,
"sStart": 217,
"sEnd": 657,
"eValue": 0.0,
"taxonomy": "d__bacteria;clade__terrabacteria-group;p__bacillota;c__bacilli;o__bacillales;f__taxid-186817;g__bacillus;species-group__bacillus-subtilis-group;species-subgroup__bacillus-mojavensis-subgroup",
"mutated": true,
"consensusBeans": [
{
"rank": "species",
"identifier": "bacillus-halotolerans",
"occurrences": 5
},
{
"rank": "species",
"identifier": "bacillus-mojavensis",
"occurrences": 4
}
]
}
},
{
"query": "INVALID_SEQUENCE",
"taxon": null
}
]
```
### Blast execution
Blast execution try to reaches the full available CPU saturation. At the default
multithread blast execution mode, the full saturation is not reached. To run
Blast through `Blutils` it is possible. All the steps taken during this process
can be seen in the image below.
### Consensus generation
Different from consensus generations from [QIIME
2](https://docs.qiime2.org/2022.11/), the `Blutils` consensus algorithm performs
a data pre-filtering based on Blast results for bit-score and perc-identity,
seems the algorithm described in the image below.
## Next steps
This project contains only basic features to run BlastN and generate consensus
identities. Thus, many features should be created, like create the database
extractor to get data from official NCBI taxdump results and build FASTA
database simultaneously, and others. We welcome new feature suggestions when
needed!