Tutorial
Before starting, make sure you have followed the instructions in Installation and Setup.
Also see the Command Line Interface page for complete documentation of all GAMBIT subcommands and options.
Telling GAMBIT where the database files are
The query command requires the GAMBIT reference database files. You can let GAMBIT know which directory contains these files in one of two ways:
Using a command line option
The first is to explicitly pass it via the command line using the --db option, like so:
gambit --db /path/to/database/ COMMAND ...
Note that this option must appear immediately after gambit and before the command name.
Using an environment variable
The second is to use the GAMBIT_DB_PATH environment variable. This can be done by
running the following command at the beginning of your shell session:
export GAMBIT_DB_PATH="/path/to/database/"
Alternatively, you can add this line to your .bashrc to have it apply to all future sessions
(make sure to restart your current session after doing so).
Example data set
Download and unzip the file below, it should result in a directory genomes/ containing five
compressed FASTA files.
They are from Genome Set 3 in the GAMBIT publication, derived from clinical samples.
Genome input
Genome assemblies used as input must be in FASTA format, optionally compressed with gzip.
Most commands accept a list of genome files as positional arguments, e.g.:
gambit COMMAND [OPTIONS] genomes/16AC1611138-CAP.fasta.gz genomes/17AC0001410A.fasta.gz ...
or making use of shell expansion:
gambit COMMAND [OPTIONS] genomes/*.fasta.gz
Alternatively you can use the -l option to provide a text file containing the genome file
names/paths, one per line. The paths in this file are considered relative to the directory given by
the --ldir option if given.
So for example, you can create the file genomes.txt containing the following:
16AC1611138-CAP.fasta.gz
17AC0001410A.fasta.gz
17AC0006310.fasta.gz
17AC0006313-1.fasta.gz
19AC0011210.fasta.gz
The command would then be:
gambit COMMAND [OPTIONS] -l genomes.txt --ldir genomes
This method makes more sense when you have a lot of files to include.
Note that the gambit dist command has different names for these options because there are two
lists of genomes to specify. See the Command Line Interface page for more complete information.
Taxonomic prediction of unknown genomes
The query command compares a set of query genomes against the reference database
and attempts to predict their taxonomy. The following runs a query with our five FASTA files and
writes the results to out.csv:
gambit query -o out.csv genomes/*.fasta.gz
This gives the following output table (shown here transposed in order to better fit on the page):
query |
16AC1611138-CAP |
17AC0001410A |
17AC0006310 |
17AC0006313-1 |
19AC0011210 |
|---|---|---|---|---|---|
predicted.name |
Escherichia coli |
Enterococcus faecalis |
Bacillus cereus |
Veillonella |
|
predicted.rank |
species |
species |
species |
genus |
|
predicted.ncbi_id |
562 |
1351 |
1396 |
29465 |
|
predicted.threshold |
0.0000 |
0.4698 |
0.0000 |
0.9439 |
|
closest.distance |
0.1586 |
0.1264 |
0.1068 |
0.9127 |
0.9917 |
closest.description |
[GCF_000351725.1] Escherichia coli KTE77 (E. coli) |
[GCF_000148005.1] Enterococcus faecalis DAPTO 512 (firmicutes) |
[GCF_001619385.1] Bacillus cereus (firmicutes) |
[GCF_000024945.1] Veillonella parvula DSM 2008 (firmicutes) |
[GCF_000169595.1] Ureaplasma urealyticum serovar 9 str. ATCC 33175 (mycoplasmas) |
next.name |
Veillonella parvula |
Ureaplasma |
|||
next.rank |
species |
genus |
|||
next.ncbi_id |
29466 |
2129 |
|||
next.threshold |
0.6693 |
0.8897 |
The predicted columns describe the predicted taxonomic classification of each query genome.
closest.description is the database reference genome closest to the query, closest.distance
is the distance between them.
The next columns have the same format as predicted but describe the next most specific taxon
for which the classification threshold was not met.
In this example GAMBIT was able to make a species-level prediction for the first three genomes
but stopped at the genus level for the fourth and made no prediction for the fifth.
This is because GAMBIT attempts to be conservative and error on the side of making a less specific
prediction or no prediction rather than giving false positives. The next columns can give you a
clue as to what a more specific classification might be, however.
See the cli documentation for a complete description of the output
columns. Generally the CSV output format should be sufficient, but there is also a JSON-based format
which contains more detailed information and may be useful in pipelines. Use -f json to use this
format.
Todo
Explain why predicted.threshold is sometimes zero for certain taxa.
Pre-computing k-mer signatures
TODO
Calculating GAMBIT distances
TODO