SpeciesFinder 4.0.3

The SpeciesFinder tool identifies species from raw sequencing reads (FASTQ) or assembled genomes (FASTA) by comparing them against a database generated using the KMA program. It reports the best matching species, along with additional taxonomic information if that option is selected.

SPECIESFINDER

The SpeciesFinder tool identifies species from raw sequencing reads (FASTQ) or assembled genomes (FASTA) by comparing them against a k-mer database generated using the KMA program. It reports the best matching species, along with additional taxonomic information if that option is selected.

From KmerFinder to SpeciesFinder - Migration guide

KmerFinder has undergone a major overhaul, and we are introducing a new and improved tool: SpeciesFinder.

The goal of this update is to improve the core functionality, stability, and long-term maintainability of the tool while preserving the underlying algorithm and user experience as much as possible.

Why the change?

Legacy KmerFinder depended heavily on the -Sparse KMA flag. This mode skips full alignment and instead performs a sparse k-mer mapping where scoring is based on k-mer hits. While fast, this approach has limitations and reduces downstream compatibility with other workflows (e.g., phylogenetics).

SpeciesFinder replaces the sparse mapping mode with a more robust and reproducible approach:

• It uses KMA’s -mem_mode, which bases ConClave scoring on mappings rather than full alignments—significantly reducing memory usage while maintaining accuracy.

• It also enables:

  • -nf — suppress creation of the fragment file

  • -na — suppress output of the alignment file (alignment is still performed internally)

  • -1t1 — force each query to match to a single best template

This update not only improves performance and stability, but also enables future support for global phylogeny generation and other extensions.

What has changed:

1. Tool name - SpeciesFinder
2. Mapping strategy - No more sparse k-mer mapping (-Sparse). SpeciesFinder now uses -mem_mode.
3. Command-line interface - The way the tool is executed has changed (see README usage section).
4. Repository name change - SpeciesFinder

What remains the same:

1. Versioning scheme
2. Algorithmic principles — still based on KMA and ConClave scoring
3. Overall purpose — identification of species from FASTQ/FASTA input

Installation

Pypi

# Go to wanted location for SpeciesFinder
cd /path/to/some/dir
pip install SpeciesFinder

Docker

# Go to wanted location for SpeciesFinder
cd /path/to/some/dir

# Clone and enter the SpeciesFinder directory
git clone https://bitbucket.org/genomicepidemiology/speciesfinder.git
cd speciesfinder

Build Docker image from Dockerfile

# Build container
docker build -t speciesfinder .

Dependencies

To run SpeciesFinder without Docker, you’ll need Python 3.5 or later and KMA installed.

The newest version of KMA can be installed from here:

https://bitbucket.org/genomicepidemiology/kma

Download and install SpeciesFinder database(s)

You can find instructions on how to download SpeciesFinder databases here

The databases are destributed as a single compressed archive:

speciesfinder_db.tar.gz

How to run

In order for SpeciesFinder to run, the user needs to specify the input, output, reference_database and, optionally, the extended taxonomic information.

• Input (-i): Single/Paired end reads, Assembly files
• Output (-o): Directory where speciesfinder results will be stored
• Reference database (-db): The reference databases KMA will look for hits. There are 4 options: bacteria, virus, archaea and eukaryotes.
• Taxonomic information (-tax): Taxonomy file with additional data for each template in all databases (family, taxid and organism) - This flag is optional
• Extended Output (-x): More informative output - Needs the -tax flag to run.

Docker

Examples

• Paired end reads

docker run --rm -v $(pwd):/app speciesfinder:latest -i read_1.fastq.gz read_2.fastq.gz -o results -db databases/reference_db/reference_db -x -tax databases/reference_db/reference_db.tax

• Single end reads

docker run --rm -v $(pwd):/app speciesfinder:latest -i read.fastq.gz -o results -db databases/reference_db/reference_db -x -tax databases/reference_db/reference_db.tax

• Assemblies

docker run --rm -v $(pwd):/app speciesfinder:latest -i assembly.fasta -o results -db databases/reference_db/reference_db -x -tax databases/reference_db/reference_db.tax

Pip package

Examples

• Paired end reads

speciesfinder -i read_1.fastq.gz read_2.fastq.gz -o results -db db databases/reference_db/reference_db -x -tax databases/reference_db/reference_db.tax

• Single end reads

speciesfinder -i read_1.fastq.gz -o results -db db databases/reference_db/reference_db -x -tax databases/reference_db/reference_db.tax

• Assemblies

speciesfinder -i assembly.fna -o results -db db databases/reference_db/reference_db -x -tax databases/reference_db/reference_db.tax

---

Notes: Example of a full command without docker:

  speciesfinder -i reads/SRR10016848.fastq.gz -o results -db databases/bacteria_db/bacteria_14_ATG_110126 -x -tax databases/bacteria_db/bacteria_14_ATG_110126.tax

Notes2: Example of a full command with docker:

  docker run --rm -v $(pwd):/app speciesfinder:latest -i reads/ERR760549_1.fastq.gz reads/ERR760549_2.fastq.gz -o results -db databases/virus/virus_14_TG_181124 -x -tax databases/virus/virus_14_TG_181124.tax

Notes3: Each reference database has a number of KMA indexed files. The -db flag needs the path of these files (without their extension).

For example in case one is using the bacteria database the files might have the following format:

• bacteria/bacteria_14_ATG_110126.comp.b
• bacteria/bacteria_14_ATG_110126.seq.b
• bacteria/bacteria_14_ATG_110126.length.b
• bacteria/bacteria_14_ATG_110126.name

The db flag will be -db bacteria/bacteria_14_ATG_110126

For example in case one is using the viral database the files might have the following format:

• virus_db/virus_ATG_110128.comp.b
• virus_db/virus_ATG_110128.seq.b
• virus_db/virus_ATG_110128.length.b
• virus_db/virus_ATG_110128.name

The db flag will be -db virus_db/virus_ATG_110128

Web-server

A webserver implementing the methods is available at the CGE website and can be found here:

Soon to come

Citation

When using the method please cite:

Benchmarking of Methods for Genomic Taxonomy. Larsen MV, Cosentino S, Lukjancenko O, Saputra D, Rasmussen S, Hasman H, Sicheritz-Pontén T, Aarestrup FM, Ussery DW, Lund O. J Clin Microbiol. 2014 Feb 26. [Epub ahead of print]

Rapid whole genome sequencing for the detection and characterization of microorganisms directly from clinical samples. Hasman H, Saputra D, Sicheritz-Ponten T, Lund O, Svendsen CA, Frimodt-Møller N, Aarestrup FM. J Clin Microbiol. 2014 Jan;52(1):139-46.

Rapid and precise alignment of raw reads against redundant databases with KMA Philip T.L.C. Clausen, Frank M. Aarestrup, Ole Lund.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.