Metadata-Version: 2.1
Name: SpeciesFinder
Version: 4.0.4
Summary: 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.
Author-Email: Center for Genomic Epidemiology <food-cgehelp@dtu.dk>
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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

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

### Docker

```bash
# 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
```bash
# 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:

```url
https://bitbucket.org/genomicepidemiology/kma
```

## Download and install SpeciesFinder database(s)

You can find instructions on how to download SpeciesFinder databases [here](https://bitbucket.org/genomicepidemiology/speciesfinder_db/src/master/)

The databases are destributed as a single compressed archive:

```bash
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**

```bash
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**

```bash
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**

```bash
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**

```bash
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**

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

* **Assemblies**

```bash
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:
```bash
  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:
```bash
  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](http://www.genomicepidemiology.org/) 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.