[![Build Status](https://github.com/phac-nml/staramr/actions/workflows/ci-test.yml/badge.svg?branch=master)](https://github.com/phac-nml/staramr/actions/workflows/ci-test.yml)
[![pypi](https://badge.fury.io/py/staramr.svg)](https://pypi.python.org/pypi/staramr/)
[![conda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg)](https://anaconda.org/bioconda/staramr)

# `staramr`

`staramr` (*AMR) scans bacterial genome contigs against the [ResFinder][resfinder-db], [PointFinder][pointfinder-db], and [PlasmidFinder][plasmidfinder-db] databases (used by the [ResFinder webservice][resfinder-web] and other webservices offered by the Center for Genomic Epidemiology) and compiles a summary report of detected antimicrobial resistance genes. The `star|*` in `staramr` indicates that it can handle all of the ResFinder, PointFinder, and PlasmidFinder databases.

**Note: The predicted phenotypes/drug resistances are for microbiological resistance and *not* clinical resistance. This is provided with support from the NARMS/CIPARS Molecular Working Group and is continually being improved. A small comparison between phenotype/drug resistance predictions produced by `staramr` and those available from NCBI can be found in the [tutorial][tutorial]. We welcome any feedback or suggestions.**

For example:

```
staramr search -o out --pointfinder-organism salmonella *.fasta
```

**out/summary.tsv**:

| Isolate ID | Quality Module | Genotype | Predicted Phenotype | CGE Predicted Phenotype | Plasmid | Scheme | Sequence Type | Genome Length | N50 value | Number of Contigs Greater Than Or Equal To 300 bp | Quality Module Feedback |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| SRR1952908 | Passed | aadA1, aadA2, blaTEM-57, cmlA1, gyrA (S83Y), sul3, tet(A) | streptomycin, ampicillin, chloramphenicol, ciprofloxacin I/R, nalidixic acid, sulfisoxazole, tetracycline  | Spectinomycin, Streptomycin, Amoxicillin, Ampicillin, Cephalothin, Piperacillin, Ticarcillin, Chloramphenicol, Nalidixic acid, Ciprofloxacin, Sulfamethoxazole, Doxycycline, Tetracycline | ColpVC, IncFIB(S), IncFII(S), IncI1-I(Alpha) | senterica_achtman_2 | 11 | 4785500 | 250423 | 41 |
| SRR1952926 | Passed | blaTEM-57, gyrA (S83Y), tet(A) | ampicillin, ciprofloxacin I/R, nalidixic acid, tetracycline |      Amoxicillin, Ampicillin, Cephalothin, Piperacillin, Ticarcillin, Nalidixic acid, Ciprofloxacin, Doxycycline, Tetracycline | ColpVC, IncFIB(S), IncFII(S), IncI1-I(Alpha) | senterica_achtman_2 | 11 | 4785451 | 228311 | 40 |

**out/detailed_summary.tsv**:

| Isolate ID | Data | Data Type | Predicted Phenotype | CGE Predicted Phenotype | %Identity | %Overlap | HSP Length/Total Length | Contig | Start | End | Accession |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| SRR1952908 | ST11 (senterica_achtman_2) | MLST |  |  |  |  |  |  |  |  |  |
| SRR1952908 | ColpVC | Plasmid |  |  | 98.96 | 100.0 | 193/193 | contig00038 | 1618 | 1426 | JX133088 |
| SRR1952908 | aadA1 | Resistance | streptomycin | Spectinomycin, Streptomycin | 100.0 | 100.0 | 792/792 | contig00030 | 5355 | 4564 | JQ414041 |

**out/resfinder.tsv**:

| Isolate ID | Gene | Predicted Phenotype | CGE Predicted Phenotype | %Identity | %Overlap | HSP Length/Total Length | Contig | Start | End | Accession | Sequence | CGE Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| SRR1952908 | sul3 | sulfisoxazole | Sulfamethoxazole | 100.00 | 100.00 | 792/792 | contig00030 | 2091 | 2882 | AJ459418 | ATGA[...] | |
| SRR1952908 | tet(A) | tetracycline | Doxycycline, Tetracycline | 99.92 | 97.80 | 1247/1275 | contig00032 | 1476 | 2722 | AF534183 | ATGT[...] | |

**out/pointfinder.tsv**:

| Isolate ID | Gene | Predicted Phenotype | CGE Predicted Phenotype | Type | Position | Mutation | %Identity | %Overlap | HSP Length/Total Length | Contig | Start | End | Pointfinder Position | CGE Notes | CGE Required Mutation | CGE Mechanism | CGE PMID |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| SRR1952908 | gyrA (S83Y) | ciprofloxacin I/R, nalidixic acid | Nalidixic acid,Ciprofloxacin | codon | 83 | TCC -> TAC (S -> Y) | 99.96 | 100.00 | 2637/2637 | contig00008 | 22801 | 20165 | S83Y |  |  | Target modification | 7492118,10471553 |
| SRR1952926 | gyrA (S83Y) | ciprofloxacin I/R, nalidixic acid | Nalidixic acid,Ciprofloxacin | codon | 83 | TCC -> TAC (S -> Y) | 99.96 | 100.00 | 2637/2637 | contig00011 | 157768 | 160404 | S83Y |  |  | Target modification | 7492118,10471553 |

**out/plasmidfinder.tsv**:

| Isolate ID | Plasmid   | %Identity | %Overlap | HSP Length/Total Length | Contig      | Start | End   | Accession |
|------------|-----------|-----------|----------|-------------------------|-------------|-------|-------|-----------|
| SRR1952908 | ColpVC    | 98.96     | 100      | 193/193                 | contig00038 | 1618  | 1426  | JX133088  |
| SRR1952908 | IncFIB(S) | 98.91     | 100      | 643/643                 | contig00024 | 10302 | 9660  | FN432031  |

**out/mlst.tsv**:

| Isolate ID | Scheme    | Sequence Type | Locus 1 | Locus 2 | Locus 3 | Locus 4 | Locus 5 | Locus 6 | Locus 7  |
|------------|-----------|---------------|---------|---------|---------|---------|---------|---------|----------|
| SRR1952908 | senterica_achtman_2 | 11            | aroC(5) | dnaN(2) | hemD(3) | hisD(7) | purE(6) | sucA(6) | thrA(11) |
| SRR1952926 | senterica_achtman_2 | 11            | aroC(5) | dnaN(2) | hemD(3) | hisD(7) | purE(6) | sucA(6) | thrA(11) |

# Table of Contents

- [Quick Usage](#quick-usage)
  * [Search contigs](#search-contigs)
  * [Database Info](#database-info)
  * [Update Database](#update-database)
  * [Restore Database](#restore-database)
- [Installation](#installation)
  * [Bioconda](#bioconda)
  * [PyPI/Pip](#pypipip)
  * [Latest Code](#latest-code)
  * [Dependencies](#dependencies)
- [Input](#input)
  * [List of genes to exclude](#list-of-genes-to-exclude)
  * [Complex mutations](#complex-mutations)
- [Output](#output)
  * [summary.tsv](#summarytsv)
  * [detailed_summary.tsv](#detailed_summarytsv)
  * [resfinder.tsv](#resfindertsv)
  * [pointfinder.tsv](#pointfindertsv)
  * [plasmidfinder.tsv](#plasmidfindertsv)
  * [mlst.tsv](#mlsttsv)
  * [settings.txt](#settingstxt)
  * [hits/](#hits)
- [Tutorial](#tutorial)
- [Usage](#usage)
  * [Main Command](#main-command)
  * [Search](#search)
  * [Database Build](#database-build)
  * [Database Update](#database-update)
  * [Database Info](#database-info-1)
  * [Database Restore Default](#database-restore-default)
- [Caveats](#caveats)
- [Acknowledgements](#acknowledgements)
- [Citations](#citations)
- [Legal](#legal)

# Quick Usage

## Search contigs

To search a list of contigs (in **fasta** format) for AMR genes using ResFinder please run:

```bash
staramr search -o out *.fasta
```

Output files will be located in the directory `out/`.

To include acquired point-mutation resistances using PointFinder, please run:

 ```bash
staramr search --pointfinder-organism salmonella -o out *.fasta
```

Where `--pointfinder-organism` is the specific organism you are interested in (currently only *salmonella*, *campylobacter*, *enterococcus faecalis* and *enterococcus faecium* are supported).

To specify which PlasmidFinder database to use, please run:

```bash
staramr search --plasmidfinder-database-type enterobacteriaceae -o out *.fasta
```
Where `--plasmidfinder-database-type` is the specific database type you are interested in (currently only *gram_positive*, *enterobacteriaceae* are supported). By default, both databases are used.

To specify which MLST scheme to use, please run:

```bash
staramr search -o out --mlst-scheme senterica *.fasta
```

Where `--mlst-scheme` is the specific organism you are interested in (please visit the [scheme genus map](https://github.com/tseemann/mlst/blob/master/db/scheme_species_map.tab) to see which are available). By default, it detects the scheme automatically.

## Database Info

To print information about the installed databases, please run:

```
staramr db info
```

## Update Database

If you wish to update to the latest ResFinder, PointFinder, and PlasmidFinder databases, you may run:

```bash
staramr db update --update-default
```

If you wish to switch to specific git commits of either ResFinder, PointFinder, or PlasmidFinder databases you may also pass `--resfinder-commit [COMMIT]`, `--pointfinder-commit [COMMIT]`, and `--plasmidfinder-commit [COMMIT]`. However, please note that because of compatibility issues arising from changes in the source databases, this functionality is largely unsupported and is unlikely to work for versions of the databases that StarAMR wasn't released with.

## Restore Database

If you have updated the ResFinder/PointFinder/PlasmidFinder databases and wish to restore to the default version, you may run:

```
staramr db restore-default
```

# Installation

## Bioconda


### Separate conda environment

The easiest way to install `staramr` is through [Bioconda][bioconda] (we recommend using [mamba](https://mamba.readthedocs.io/) as an alternative to `conda`).

```bash
conda install mamba # Install mamba to make it easier to install later dependencies
mamba create -c conda-forge -c bioconda -c defaults --name staramr staramr
```

This will install the `staramr` software at the most recent version within the conda environment named `staramr`. Bioconda will install all necessary dependencies and databases. Once this is complete you can run:

```bash
conda activate staramr # Activate conda environment
staramr --help
```

### Same conda environment

If, instead, you wish to install `staramr` to the current conda environment you can run:

```bash
mamba install -c conda-forge -c bioconda -c defaults staramr
```

You should now be able to run `staramr --help` and recieve a usage statement.

## PyPI/Pip

You can also install `staramr` from [PyPI][pypi-staramr] using `pip`:

```
pip install staramr
```

However, you will have to install the external dependencies (listed below) separately.

## Latest Code

If you wish to make use of the latest in-development version of `staramr`, you may update directly from GitHub using `pip`:

```bash
pip install git+https://github.com/phac-nml/staramr
```

This will only install the Python code, you will still have to install the dependencies listed below (or run the `pip` command from the previously installed Bioconda environment).

Alternatively, if you wish to do development with `staramr` you can use a Python virtual environment (you must still install the non-Python dependencies separately).

```bash
# Clone code
git clone https://github.com/phac-nml/staramr.git
cd staramr

# Setup virtual environment
virtualenv -p /path/to/python-bin .venv
source .venv/bin/activate

# Install staramr. Use '-e' to update the install on code changes.
pip install -e .

# Now run `staramr`
staramr
```

Due to the way we packaged the ResFinder/PointFinder/PlasmidFinder databases, the development code will not come with a default database. You must first build the database before usage. E.g.

```
staramr db restore-default
```

## Dependencies

* Python 3.7+
* BLAST+
* Git
* MLST 2.32.2+

# Input

## List of genes to exclude

By default, the ResFinder/PointFinder/PlasmidFinder genes listed in [genes_to_exclude.tsv][] will be excluded from the final results. To pass a custom list of genes the option `--exclude-genes-file` can be used, where the file specified will contains a list of the sequence ids (one per line) from the ResFinder/PointFinder/PlasmidFinder databases. For example:

```
gene_id
gyrA_1_CP073768.1
pmrB_1_CP051284.1
```

Please make sure to include `gene_id` in the first line. The default exclusion list can also be disabled with `--no-exclude-genes`. Gene IDs must exactly match the FASTA record IDs provided in the source databases.

## Complex Mutations

Complex mutations describe multiple point mutations that must be simultaneously present in order to confer resistance. One such example is the multiple pbp5 mutations that must be present in Enterococcus faecium in order to confer ampicillin resistance. These complex mutations may be specified by the user using a TSV-formatted file with the following format:

| positions | mandatory | phenotype |
| --- | --- | --- |
| gene (mutation1), gene (mutation2) | gene (mutation1) | phenotype |

Where `positions` is all the point mutations to group into the complex mutation (optional and mandatory), `mandatory` is all the point mutations that must be present for the complex mutation to be reported (`mandatory` is a subset of `positions`), and `phenotype` is the phenotype that is conferred when this set of mutations is present. To see a specific example of this, please look at the default `complex_mutations.tsv` file [included with StarAMR](staramr/databases/resistance/pointfinder/complex/data/complex_mutations.tsv). The mutation will be reported in the `pointfinder.tsv` file similar to as follows:

| Isolate ID | Gene | Predicted Phenotype | CGE Predicted Phenotype | Type | Position | Mutation | %Identity | %Overlap | HSP Length/Total Length | Contig | Start | End | Pointfinder Position | CGE Notes | CGE Required Mutation | CGE Mechanism | CGE PMID |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| pbp5 | pbp5 (A216S), pbp5 (A499T), pbp5 (A68T), pbp5 (D204G), pbp5 (E100Q), pbp5 (E525D), pbp5 (E629V), pbp5 (E85D), pbp5 (G66E), pbp5 (K144Q), pbp5 (L177I), pbp5 (M485A), pbp5 (N496K), pbp5 (P667S), pbp5 (R34Q), pbp5 (S27G), pbp5 (T172A), pbp5 (T324A), pbp5 (V24A), pbp5 (V586L) | ampicillin | - | complex | 524, 527, 534, 566, 568, 585, 5100, 5144, 5172, 5177, 5204, 5216, 5324, 5485, 5496, 5499, 5525, 5586, 5629, 5667 | complex | 98.28 | 100.00 | 2037/2037 | pbp5_1_AAK43724.1 | 1 | 2037 | pbp5 (A216S), pbp5 (A499T), pbp5 (A68T), pbp5 (D204G), pbp5 (E100Q), pbp5 (E525D), pbp5 (E629V), pbp5 (E85D), pbp5 (G66E), pbp5 (K144Q), pbp5 (L177I), pbp5 (M485A), pbp5 (N496K), pbp5 (P667S), pbp5 (R34Q), pbp5 (S27G), pbp5 (T172A), pbp5 (T324A), pbp5 (V24A), pbp5 (V586L) | - | - | - | - |

The complex mutation TSV file may be specifed on the command line when running Pointfinder:

```
staramr search --pointfinder-organism enterococcus_faecium -o out pbp5.fa --complex-mutations-file complex_mutations.tsv
```

# Output

There are 8 different output files produced by `staramr`:

1. `summary.tsv`:  A summary of all detected AMR genes/mutations/plasmids/sequence type in each genome, one genome per line. A series of descriptive statistics is also provided for each genome as well as feedback for whether or not the genome passes several quality metrics and if not, feedback on why the genome fails.
2. `detailed_summary.tsv`: A detailed summary of all detected AMR genes/mutations/plasmids/sequence type in each genome, one gene per line.
3. `resfinder.tsv`: A tabular file of each AMR gene and additional BLAST information from the **ResFinder** database, one gene per line.
4. `pointfinder.tsv`: A tabular file of each AMR point mutation and additional BLAST information from the **PointFinder** database, one gene per line.
5. `plasmidfinder.tsv`: A tabular file of each AMR plasmid type and additional BLAST information from the **PlasmidFinder** database, one plasmid type per line.
6. `mlst.tsv`: A tabular file of each multi-locus sequence type (MLST) and it's corresponding locus/alleles, one genome per line.
7. `settings.txt`: The command-line, database versions, and other settings used to run `staramr`.
8. `results.xlsx`: An Excel spreadsheet containing the previous 6 files as separate worksheets.

In addition, the directory `hits/` stores fasta files of the specific blast hits.

## summary.tsv

The **summary.tsv** output file generated by `staramr` contains the following columns:

* __Isolate ID__: The id of the isolate/genome file(s) passed to `staramr`.
* __Quality Module__: The isolate/genome file(s) pass/fail result(s) for the quality metrics
* __Genotype__: The AMR genotype of the isolate.
* __Predicted Phenotype__: The predicted AMR phenotype (drug resistances) for the isolate.
* __CGE Predicted Phenotype__: The CGE-predicted AMR phenotype (drug resistances) for the isolate.
* __Plasmid__: Plasmid types that were found for the isolate.
* __Scheme__: The MLST scheme used
* __Sequence Type__: The sequence type that's assigned when combining all allele types
* __Genome Length__: The isolate/genome file(s) genome length(s)
* __N50 value__: The isolate/genome file(s) N50 value(s) 
* __Number of Contigs Greater Than Or Equal To 300 bp__: The number of contigs greater or equal to 300 base pair in the isolate/genome file(s)
* __Quality Module Feedback__: The isolate/genome file(s) detailed feedback for the quality metrics

### Example

| Isolate ID | Quality Module | Genotype | Predicted Phenotype | CGE Predicted Phenotype | Plasmid | Scheme | Sequence Type | Genome Length | N50 value | Number of Contigs Greater Than Or Equal To 300 bp | Quality Module Feedback |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| SRR1952908 | Passed | aadA1, aadA2, blaTEM-57, cmlA1, gyrA (S83Y), sul3, tet(A) | streptomycin, ampicillin, chloramphenicol, ciprofloxacin I/R, nalidixic acid, sulfisoxazole, tetracycline  | Spectinomycin, Streptomycin, Amoxicillin, Ampicillin, Cephalothin, Piperacillin, Ticarcillin, Chloramphenicol, Nalidixic acid, Ciprofloxacin, Sulfamethoxazole, Doxycycline, Tetracycline | ColpVC, IncFIB(S), IncFII(S), IncI1-I(Alpha) | senterica_achtman_2 | 11 | 4785500 | 250423 | 41 |
| SRR1952926 | Passed | blaTEM-57, gyrA (S83Y), tet(A) | ampicillin, ciprofloxacin I/R, nalidixic acid, tetracycline |      Amoxicillin, Ampicillin, Cephalothin, Piperacillin, Ticarcillin, Nalidixic acid, Ciprofloxacin, Doxycycline, Tetracycline | ColpVC, IncFIB(S), IncFII(S), IncI1-I(Alpha) | senterica_achtman_2 | 11 | 4785451 | 228311 | 40 |

## detailed_summary.tsv

The **detailed_summary.tsv** output file generated by `staramr` contains the following columns:

* __Isolate ID__: The id of the isolate/genome file(s) passed to `staramr`.
* __Data__: The particular gene detected from ResFinder, PlasmidFinder, PointFinder, or the sequence type.
* __Data Type__: The type of gene (Resistance or Plasmid), or MLST.
* __Predicted Phenotype__: The predicted AMR phenotype (drug resistances) found in ResFinder/PointFinder. Plasmids will be left blank by default.
* __CGE Predicted Phenotype__: The CGE-predicted AMR phenotype (drug resistances) found in ResFinder/PointFinder. Plasmids will be left blank by default.
* __%Identity__: The % identity of the top BLAST HSP to the gene.
* __%Overlap__: THe % overlap of the top BLAST HSP to the gene (calculated as __hsp length/total length * 100__).
* __HSP Length/Total Length__ The top BLAST HSP length over the gene total length (nucleotides).
* __Contig__: The contig id containing this gene.
* __Start__: The start of the gene (will be greater than __End__ if on minus strand).
* __End__: The end of the gene.
* __Accession__: The accession of the gene from either ResFinder or PlasmidFinder  database.

### Example

| Isolate ID | Data | Data Type | Predicted Phenotype | CGE Predicted Phenotype | %Identity | %Overlap | HSP Length/Total Length | Contig | Start | End | Accession |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| SRR1952908 | ST11 (senterica_achtman_2) | MLST |  |  |  |  |  |  |  |  |  |
| SRR1952908 | ColpVC | Plasmid |  |  | 98.96 | 100.0 | 193/193 | contig00038 | 1618 | 1426 | JX133088 |
| SRR1952908 | aadA1 | Resistance | streptomycin | Spectinomycin, Streptomycin | 100.0 | 100.0 | 792/792 | contig00030 | 5355 | 4564 | JQ414041 |

## resfinder.tsv

The **resfinder.tsv** output file generated by `staramr` contains the following columns:

* __Isolate ID__: The id of the isolate/genome file(s) passed to `staramr`.
* __Gene__: The particular AMR gene detected.
* __Predicted Phenotype__: The predicted AMR phenotype (drug resistances) for this gene.
* __CGE Predicted Phenotype__: The CGE-predicted AMR phenotype (drug resistances) for this gene.
* __%Identity__: The % identity of the top BLAST HSP to the AMR gene.
* __%Overlap__: THe % overlap of the top BLAST HSP to the AMR gene (calculated as __hsp length/total length * 100__).
* __HSP Length/Total Length__ The top BLAST HSP length over the AMR gene total length (nucleotides).
* __Contig__: The contig id containing this AMR gene.
* __Start__: The start of the AMR gene (will be greater than __End__ if on minus strand).
* __End__: The end of the AMR gene.
* __Accession__: The accession of the AMR gene in the ResFinder database.
* __Sequence__: The AMR Gene sequence
* __CGE Notes__: Any CGE notes associated with the prediction.

### Example

| Isolate ID | Gene | Predicted Phenotype | CGE Predicted Phenotype | %Identity | %Overlap | HSP Length/Total Length | Contig | Start | End | Accession | Sequence | CGE Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| SRR1952908 | sul3 | sulfisoxazole | Sulfamethoxazole | 100.00 | 100.00 | 792/792 | contig00030 | 2091 | 2882 | AJ459418 | ATGA[...] | |
| SRR1952908 | tet(A) | tetracycline | Doxycycline, Tetracycline | 99.92 | 97.80 | 1247/1275 | contig00032 | 1476 | 2722 | AF534183 | ATGT[...] | |

## pointfinder.tsv

The **pointfinder.tsv** output file generated by `staramr` contains the following columns:

* __Isolate ID__: The id of the isolate/genome file(s) passed to `staramr`.
* __Gene__: The particular AMR gene detected, with the point mutation within.
* __Predicted Phenotype__: The predicted AMR phenotype (drug resistances) for this gene.
* __CGE Predicted Phenotype__: The CGE-predicted AMR phenotype (drug resistances) for this gene.
* __Type__: The type of this mutation from PointFinder (either **codon** or **nucleotide**).
* __Position__: The position of the mutation. For **codon** type, the position is the codon number in the gene, for **nucleotide** type it is the nucleotide number.
* __Mutation__: The particular mutation. For **codon** type lists the codon mutation, for **nucleotide** type lists the single nucleotide mutation.
* __%Identity__: The % identity of the top BLAST HSP to the AMR gene.
* __%Overlap__: The % overlap of the top BLAST HSP to the AMR gene (calculated as __hsp length/total length * 100__).
* __HSP Length/Total Length__ The top BLAST HSP length over the AMR gene total length (nucleotides).
* __Contig__: The contig id containing this AMR gene.
* __Start__: The start of the AMR gene (will be greater than __End__ if on minus strand).
* __End__: The end of the AMR gene.
* __Pointfinder Position__: The Pointfinder-adjusted position, which may be off by one from the sequence position in the case of some indels.
* __CGE Notes__: Any CGE notes associated with the prediction.
* __CGE Required Mutation__: Any additional mutations that CGE predicts are required to confer the CGE predicted phenotype.
* __CGE Mechanism__: The CGE-reported mechanism.
* __CGE PMID__: The PMID ID associated with the CGE prediction.

### Example

| Isolate ID | Gene | Predicted Phenotype | CGE Predicted Phenotype | Type | Position | Mutation | %Identity | %Overlap | HSP Length/Total Length | Contig | Start | End | Pointfinder Position | CGE Notes | CGE Required Mutation | CGE Mechanism | CGE PMID |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| SRR1952908 | gyrA (S83Y) | ciprofloxacin I/R, nalidixic acid | Nalidixic acid,Ciprofloxacin | codon | 83 | TCC -> TAC (S -> Y) | 99.96 | 100.00 | 2637/2637 | contig00008 | 22801 | 20165 | S83Y |  |  | Target modification | 7492118,10471553 |
| SRR1952926 | gyrA (S83Y) | ciprofloxacin I/R, nalidixic acid | Nalidixic acid,Ciprofloxacin | codon | 83 | TCC -> TAC (S -> Y) | 99.96 | 100.00 | 2637/2637 | contig00011 | 157768 | 160404 | S83Y |  |  | Target modification | 7492118,10471553 |

## plasmidfinder.tsv

The **plasmidfinder.tsv** output file generated by `staramr` contains the following columns:

* __Isolate ID__: The id of the isolate/genome file(s) passed to `staramr`.
* __Plasmid__: The particular plasmid type detected.
* __%Identity__: The % identity of the top BLAST HSP to the plasmid type.
* __%Overlap__: The % overlap of the top BLAST HSP to the plasmid type (calculated as __hsp length/total length * 100__).
* __HSP Length/Total Length__ The top BLAST HSP length over the plasmid type total length (nucleotides).
* __Contig__: The contig id containing this plasmid type.
* __Start__: The start of the plasmid type (will be greater than __End__ if on minus strand).
* __End__: The end of the plasmid type.
* __Accession__: The accession of the plasmid type in the PlasmidFinder database.

### Example

| Isolate ID | Plasmid   | %Identity | %Overlap | HSP Length/Total Length | Contig      | Start | End   | Accession |
|------------|-----------|-----------|----------|-------------------------|-------------|-------|-------|-----------|
| SRR1952908 | ColpVC    | 98.96     | 100      | 193/193                 | contig00038 | 1618  | 1426  | JX133088  |
| SRR1952908 | IncFIB(S) | 98.91     | 100      | 643/643                 | contig00024 | 10302 | 9660  | FN432031  |

## mlst.tsv

The **mlst.tsv** output file generated by `staramr` contains the following columns:

* __Isolate ID__: The id of the isolate/genome file(s) passed to `staramr`.
* __Scheme__: The scheme that `MLST` has identified.
* __Sequence Type__: The sequence type that's assigned when combining all allele types
* __Locus #__: A particular locus in the specified MLST scheme.

### Example

| Isolate ID | Scheme    | Sequence Type | Locus 1 | Locus 2 | Locus 3 | Locus 4 | Locus 5 | Locus 6 | Locus 7  |
|------------|-----------|---------------|---------|---------|---------|---------|---------|---------|----------|
| SRR1952908 | senterica_achtman_2 | 11            | aroC(5) | dnaN(2) | hemD(3) | hisD(7) | purE(6) | sucA(6) | thrA(11) |
| SRR1952926 | senterica_achtman_2 | 11            | aroC(5) | dnaN(2) | hemD(3) | hisD(7) | purE(6) | sucA(6) | thrA(11) |

## settings.txt

The **settings.txt** file contains the particular settings used to run `staramr`.

* __command_line__: The command line used to run `staramr`.
* __version__: The version of `staramr`.
* __start_time__,__end_time__,__total_minutes__: The start, end, and duration for running `staramr`.
* __resfinder_db_dir__, __pointfinder_db_dir__, __plasmidfinder_db_dir__ : The directory containing the ResFinder, PointFinder, and PlasmidFinder databases.
* __resfinder_db_url__, __pointfinder_db_url__, __plasmidfinder_db_url__: The URL to the git repository for the ResFinder, PointFinder, and PlasmidFinder databases.
* __resfinder_db_commit__, __pointfinder_db_commit__, __plasmidfinder_db_commit__: The git commit ids for the ResFinder, PointFinder, and PlasmidFinder databases.
* __resfinder_db_date__, __pointfinder_db_date__, __plasmidfinder_db_date__: The date of the git commits of the ResFinder, PointFinder, and PlasmidFinder databases.
* __mlst_version__: The version of `MLST`.
* __pointfinder_gene_drug_version__, __resfinder_gene_drug_version__: A version identifier for the gene/drug mapping table used by `staramr`.

### Example

```
command_line                  = staramr search -o out staramr/tests/integration/data/16S-rc_gyrA-rc_beta-lactam.fsa
version                       = 0.11.1
start_time                    = 2026-02-26 14:09:48
end_time                      = 2026-02-26 14:09:49
total_minutes                 = 0.01
resfinder_db_dir              = staramr/databases/data/dist/resfinder
resfinder_db_url              = https://bitbucket.org/genomicepidemiology/resfinder_db.git
resfinder_db_commit           = 65c9ba3b680d13fe5eb13ec78bf1a4160ef4c6d7
resfinder_db_date             = Sun, 04 May 2025 18:02
pointfinder_db_dir            = staramr/databases/data/dist/pointfinder
pointfinder_db_url            = https://bitbucket.org/genomicepidemiology/pointfinder_db.git
pointfinder_db_commit         = 694919f59a38980204009e7ade76bf319cb7df0b
pointfinder_db_date           = Thu, 08 Aug 2024 11:57
pointfinder_organisms_all     = campylobacter, enterococcus_faecalis, enterococcus_faecium, escherichia_coli, helicobacter_pylori, klebsiella, mycobacterium_tuberculosis, neisseria_gonorrhoeae, plasmodium_falciparum, salmonella, staphylococcus_aureus
pointfinder_organisms_valid   = campylobacter, enterococcus_faecalis, enterococcus_faecium, escherichia_coli, helicobacter_pylori, salmonella
plasmidfinder_db_dir          = staramr/databases/data/dist/plasmidfinder
plasmidfinder_db_url          = https://bitbucket.org/genomicepidemiology/plasmidfinder_db.git
plasmidfinder_db_commit       = 49c24c1c9401fa175fbcfdbd4b37227a160baca4
plasmidfinder_db_date         = Wed, 10 Sep 2025 18:56
mlst_version                  = 2.32.2
pointfinder_organism          = None
pointfinder_gene_drug_version = 070623
resfinder_gene_drug_version   = 072423
```

## hits/

The **hits/** directory contains the BLAST HSP nucleotides for the entries listed in the **resfinder.tsv** and **pointfinder.tsv** files. There are up to two files per input genome, one for ResFinder and one for PointFinder.

For example, with an input genome named **SRR1952908.fasta** there would be two files `hits/resfinder_SRR1952908.fasta` and `hits/pointfinder_SRR1952908.fasta`. These files contain mostly the same information as in the **resfinder.tsv**, **pointfinder.tsv**, and **plasmidfinder.tsv** files. Additional information is the **database_gene_start** and **database_gene_end** listing the start/end of the BLAST HSP on the AMR resistance gene from the ResFinder/PointFinder/PlasmidFinder databases. 

### Example

```
>aadA1_3_JQ414041 isolate: SRR1952908, contig: contig00030, contig_start: 5355, contig_end: 4564, database_gene_start: 1, database_gene_end: 792, hsp/length: 792/792, pid: 100.00%, plength: 100.00%
ATGAGGGAAGCGGTGATCGCCGAAGTATCGACTCAACTATCAGAGGTAGTTGGCGTCATC
GAGCGCCATCTCGAACCGACGTTGCTGGCCGTACATTTGTACGGCTCCGCAGTGGATGGC
...
```

# Tutorial

A tutorial guiding you though the usage of `staramr`, interpreting the results, and comparing with antimicrobial resistances available on NCBI can be found at [staramr tutorial][tutorial].

# Usage

## Main Command

Main `staramr` command. Can be used to set global options (primarily `--verbose`).

```
usage: staramr [-h] [--verbose] [-V] {search,db} ...

Do AMR detection for genes and point mutations

positional arguments:
  {search,db}    Subcommand for AMR detection.
    search       Search for AMR genes
    db           Download ResFinder/PointFinder/PlasmidFinder databases

options:
  -h, --help     show this help message and exit
  --verbose      Turn on verbose logging [False].
  -V, --version  show program's version number and exit
```

## Search

Searches input FASTA files for AMR genes.

```
usage: staramr search [-h] [--pointfinder-organism POINTFINDER_ORGANISM] [--plasmidfinder-database-type PLASMIDFINDER_DATABASE_TYPE] [-d DATABASE]
                      [-n NPROCS] [--ignore-invalid-files] [--mlst-scheme MLST_SCHEME] [--genome-size-lower-bound GENOME_SIZE_LOWER_BOUND]
                      [--genome-size-upper-bound GENOME_SIZE_UPPER_BOUND] [--minimum-N50-value MINIMUM_N50_VALUE]
                      [--minimum-contig-length MINIMUM_CONTIG_LENGTH] [--unacceptable-number-contigs UNACCEPTABLE_NUM_CONTIGS]
                      [--pid-threshold PID_THRESHOLD] [--percent-length-overlap-resfinder PLENGTH_THRESHOLD_RESFINDER]
                      [--percent-length-overlap-pointfinder PLENGTH_THRESHOLD_POINTFINDER]
                      [--percent-length-overlap-plasmidfinder PLENGTH_THRESHOLD_PLASMIDFINDER] [--no-exclude-genes]
                      [--exclude-genes-file EXCLUDE_GENES_FILE] [--exclude-negatives] [--exclude-resistance-phenotypes] [--report-all-blast]
                      [--complex-mutations-file COMPLEX_MUTATIONS_FILE] [-o OUTPUT_DIR] [--output-summary OUTPUT_SUMMARY]
                      [--output-detailed-summary OUTPUT_DETAILED_SUMMARY] [--output-resfinder OUTPUT_RESFINDER]
                      [--output-pointfinder OUTPUT_POINTFINDER] [--output-plasmidfinder OUTPUT_PLASMIDFINDER] [--output-settings OUTPUT_SETTINGS]
                      [--output-excel OUTPUT_EXCEL] [--output-hits-dir HITS_OUTPUT_DIR] [--output-mlst OUTPUT_MLST]
                      files [files ...]

positional arguments:
  files

options:
  -h, --help            show this help message and exit
  --pointfinder-organism POINTFINDER_ORGANISM
                        The organism to use for pointfinder. Validated: {'enterococcus_faecium', 'helicobacter_pylori', 'campylobacter', 'escherichia_coli', 'enterococcus_faecalis', 'salmonella'}. All: {'mycobacterium_tuberculosis', 'klebsiella', 'staphylococcus_aureus', 'plasmodium_falciparum', 'enterococcus_faecium', 'helicobacter_pylori', 'campylobacter', 'escherichia_coli', 'neisseria_gonorrhoeae', 'enterococcus_faecalis', 'salmonella'}. Defaults to disabling search for point mutations. [None].
  --plasmidfinder-database-type PLASMIDFINDER_DATABASE_TYPE
                        The database type to use for plasmidfinder {gram_positive, enterobacteriales}. Defaults to using all available database types to search for plasmids. [None].
  -d DATABASE, --database DATABASE
                        The directory containing the resfinder/pointfinder/plasmidfinder databases [staramr/staramr/databases/data].
  -n NPROCS, --nprocs NPROCS
                        The number of processing cores to use [24].
  --ignore-invalid-files
                        Skips over invalid input files
  --mlst-scheme MLST_SCHEME
                        Specify scheme name, visit https://github.com/tseemann/mlst/tree/master/db/pubmlst for supported scheme genera available. [None] 
  --genome-size-lower-bound GENOME_SIZE_LOWER_BOUND
                        The lower bound for our genome size for the quality metrics. Defaults to 4 Mbp. [4000000].
  --genome-size-upper-bound GENOME_SIZE_UPPER_BOUND
                        The upper bound for our genome size for the quality metrics. Defaults to 6 Mbp. [6000000].
  --minimum-N50-value MINIMUM_N50_VALUE
                        The minimum N50 value for the quality metrics. Defaults to 10000. [10000].
  --minimum-contig-length MINIMUM_CONTIG_LENGTH
                        The minimum contig length for the quality metrics. Defaults to 300 bp. [300].
  --unacceptable-number-contigs UNACCEPTABLE_NUM_CONTIGS
                        The minimum, unacceptable number of contigs which are equal to or above the minimum contig length for our quality metrics. Defaults to 1000. [1000].

BLAST Thresholds:
  --pid-threshold PID_THRESHOLD
                        The percent identity threshold [98.0].
  --percent-length-overlap-resfinder PLENGTH_THRESHOLD_RESFINDER
                        The percent length overlap for resfinder results [60.0].
  --percent-length-overlap-pointfinder PLENGTH_THRESHOLD_POINTFINDER
                        The percent length overlap for pointfinder results [95.0].
  --percent-length-overlap-plasmidfinder PLENGTH_THRESHOLD_PLASMIDFINDER
                        The percent length overlap for resfinder results [60.0].

Reporting options:
  --no-exclude-genes    Disable the default exclusion of some genes from ResFinder/PointFinder/PlasmidFinder [False].
  --exclude-genes-file EXCLUDE_GENES_FILE
                        A list of ResFinder/PointFinder/PlasmidFinder gene names to exclude from results [staramr/databases/exclude/data/genes_to_exclude.tsv].
  --exclude-negatives   Exclude negative results (those susceptible to antimicrobials) [False].
  --exclude-resistance-phenotypes
                        Exclude predicted antimicrobial resistances [False].
  --report-all-blast    Report all blast hits (vs. only top blast hits) [False].
  --complex-mutations-file COMPLEX_MUTATIONS_FILE
                        A list of multiple PointFinder point mutations that together confer a single phenotype [staramr/databases/resistance/pointfinder/complex/data/complex_mutations.tsv].

Output:
  Use either --output-dir or specify individual output files

  -o OUTPUT_DIR, --output-dir OUTPUT_DIR
                        The output directory for results [None].
  --output-summary OUTPUT_SUMMARY
                        The name of the output file containing the summary results. Not be be used with '--output-dir'. [None]
  --output-detailed-summary OUTPUT_DETAILED_SUMMARY
                        The name of the output file containing the detailed summary results. Not be be used with '--output-dir'. [None]
  --output-resfinder OUTPUT_RESFINDER
                        The name of the output file containing the resfinder results. Not be be used with '--output-dir'. [None]
  --output-pointfinder OUTPUT_POINTFINDER
                        The name of the output file containing the pointfinder results. Not be be used with '--output-dir'. [None]
  --output-plasmidfinder OUTPUT_PLASMIDFINDER
                        The name of the output file containing the plasmidfinder results. Not be be used with '--output-dir'. [None]
  --output-settings OUTPUT_SETTINGS
                        The name of the output file containing the settings. Not be be used with '--output-dir'. [None]
  --output-excel OUTPUT_EXCEL
                        The name of the output file containing the excel results. Not be be used with '--output-dir'. [None]
  --output-hits-dir HITS_OUTPUT_DIR
                        The name of the directory to contain the BLAST hit files. Not be be used with '--output-dir'. [None]
  --output-mlst OUTPUT_MLST
                        The name of the output file containing the mlst results. Not be be used with '--output-dir'. [None]

Example:
        staramr search -o out *.fasta
                Searches the files *.fasta for AMR genes using only the ResFinder database, storing results in the out/ directory.

        staramr search --pointfinder-organism salmonella --output-excel results.xlsx *.fasta
                Searches *.fasta for AMR genes using ResFinder and PointFinder database with the passed organism, storing results in results.xlsx.
```

## Database Build

Downloads and builds the ResFinder, PointFinder, and PlasmidFinder databases.

```
usage: staramr db build [-h] [--dir DESTINATION] [--resfinder-commit RESFINDER_COMMIT] [--pointfinder-commit POINTFINDER_COMMIT]
                        [--plasmidfinder-commit PLASMIDFINDER_COMMIT]

options:
  -h, --help            show this help message and exit
  --dir DESTINATION     The directory to download the databases into [staramr/staramr/databases/data].
  --resfinder-commit RESFINDER_COMMIT
                        The specific git commit for the resfinder database [latest].
  --pointfinder-commit POINTFINDER_COMMIT
                        The specific git commit for the pointfinder database [latest].
  --plasmidfinder-commit PLASMIDFINDER_COMMIT
                        The specific git commit for the plasmidfinder database [latest].

Example:
        staramr db build
                Builds a new ResFinder/PointFinder/PlasmidFinder database under staramr/databases/data if it does not exist

        staramr db build --dir databases
                Builds a new ResFinder/PointFinder/PlasmidFinder database under databases/
```

## Database Update

Updates an existing download of the ResFinder, PointFinder, and PlasmidFinder databases.

```
usage: staramr db update [-h] [-d] [--resfinder-commit RESFINDER_COMMIT] [--pointfinder-commit POINTFINDER_COMMIT]
                         [--plasmidfinder-commit PLASMIDFINDER_COMMIT]
                         [directories ...]

positional arguments:
  directories

options:
  -h, --help            show this help message and exit
  -d, --update-default  Updates default database directory (staramr/databases/data).
  --resfinder-commit RESFINDER_COMMIT
                        The specific git commit for the resfinder database [latest].
  --pointfinder-commit POINTFINDER_COMMIT
                        The specific git commit for the pointfinder database [latest].
  --plasmidfinder-commit PLASMIDFINDER_COMMIT
                        The specific git commit for the plasmidfinder database [latest].

Example:
        staramr db update databases/
                Updates the ResFinder/PointFinder/PlasmidFinder database under databases/

        staramr db update -d
                Updates the default ResFinder/PointFinder/PlasmidFinder database under staramr/databases/data
```

## Database Info

Prints information about an existing build of the ResFinder/PointFinder/PlasmidFinder databases.

```
usage: staramr db info [-h] [directories ...]

positional arguments:
  directories

options:
  -h, --help   show this help message and exit

Example:
        staramr db info
                Prints information about the default database in staramr/databases/data

        staramr db info databases
                Prints information on the database stored in databases/
```

## Database Restore Default

Restores the default database for `staramr`.

```
usage: staramr db restore-default [-h] [-f]

options:
  -h, --help   show this help message and exit
  -f, --force  Force restore without asking for confirmation.

Example:
        staramr db restore-default
                Restores the default ResFinder/PointFinder/PlasmidFinder database
```

# Caveats

This software is still a work-in-progress.  In particular, not all organisms stored in the PointFinder database are supported (only *enterococcus_faecalis*, *helicobacter_pylori*, *enterococcus_faecium*, *campylobacter*, *escherichia_coli*, *salmonella* are currently supported). Additionally, the predicted phenotypes are for microbiological resistance and *not* clinical resistance. Phenotype/drug resistance predictions are an experimental feature which is continually being improved.

`staramr` only works on assembled genomes and not directly on reads. A quick genome assembler you could use is [Shovill][shovill]. Or, you may also wish to try out the [ResFinder webservice][resfinder-web],  or the command-line tools [rgi][] or [ariba][] which will work on sequence reads as well as genome assemblies.  You may also wish to check out the [CARD webservice][card-web]. 

# Acknowledgements

Some ideas for the software were derived from the [ResFinder][resfinder-git], [PointFinder][pointfinder-git], and [PlasmidFinder][plasmidfinder-git] command-line software, as well as from [ABRicate][abricate] and from [SISTR (Salmonella In Silico Typing Resource) command-line tool ][sistr_cmd].

Phenotype/drug resistance predictions are provided with support from the NARMS/CIPARS Molecular Working Group.

The Multi-locus sequence typing program is from the [MLST] Github.

# Citations

If you find `staramr` useful, please cite the following paper:

> Bharat A, Petkau A, Avery BP, Chen JC, Folster JP, Carson CA, Kearney A, Nadon C, Mabon P, Thiessen J, Alexander DC, Allen V, El Bailey S, Bekal S, German GJ, Haldane D, Hoang L, Chui L, Minion J, Zahariadis G, Domselaar GV, Reid-Smith RJ, Mulvey MR. **Correlation between Phenotypic and In Silico Detection of Antimicrobial Resistance in Salmonella enterica in Canada Using Staramr**. Microorganisms. 2022; 10(2):292. https://doi.org/10.3390/microorganisms10020292

You may also consider citing the following (databases or other resources used by `staramr`):

> **Zankari E, Hasman H, Cosentino S, Vestergaard M, Rasmussen S, Lund O, Aarestrup FM, Larsen MV**. 2012. Identification of acquired antimicrobial resistance genes. J. Antimicrob. Chemother. 67:2640–2644. doi: [10.1093/jac/dks261][resfinder-cite]

> **Zankari E, Allesøe R, Joensen KG, Cavaco LM, Lund O, Aarestrup F**. PointFinder: a novel web tool for WGS-based detection of antimicrobial resistance associated with chromosomal point mutations in bacterial pathogens. J Antimicrob Chemother. 2017; 72(10): 2764–8. doi: [10.1093/jac/dkx217][pointfinder-cite]

> **Carattoli A, Zankari E, Garcia-Fernandez A, Voldby Larsen M, Lund O, Villa L, Aarestrup FM, Hasman H**. PlasmidFinder and pMLST: in silico detection and typing of plasmids. Antimicrob. Agents Chemother. 2014. April 28th. doi: [10.1128/AAC.02412-14][plasmidfinder-cite]

>**Seemann T**, MLST Github https://github.com/tseemann/mlst

>**Jolley KA, Bray JE and Maiden MCJ**. Open-access bacterial population genomics: BIGSdb software, the PubMLST.org website and their applications [version 1; peer review: 2 approved]. Wellcome Open Res 2018, 3:124. doi: [10.12688/wellcomeopenres.14826.1][mlst-cite]

# Legal

Copyright 2018 Government of Canada

Licensed under the Apache License, Version 2.0 (the "License"); you may not use
this work 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.

[resfinder-db]: https://bitbucket.org/genomicepidemiology/resfinder_db
[pointfinder-db]: https://bitbucket.org/genomicepidemiology/pointfinder_db
[plasmidfinder-db]:https://bitbucket.org/genomicepidemiology/plasmidfinder_db
[resfinder-web]: https://cge.cbs.dtu.dk/services/ResFinder/
[resfinder-cite]: https://dx.doi.org/10.1093/jac/dks261
[pointfinder-cite]: https://doi.org/10.1093/jac/dkx217
[plasmidfinder-cite]: https://doi.org/10.1128/AAC.02412-14
[mlst-cite]: https://doi.org/10.12688/wellcomeopenres.14826.1
[Bioconda]: https://bioconda.github.io/
[requirements.txt]: requirements.txt
[resfinder-git]: https://bitbucket.org/genomicepidemiology/resfinder
[pointfinder-git]: https://bitbucket.org/genomicepidemiology/pointfinder-3.0
[plasmidfinder-git]: https://bitbucket.org/genomicepidemiology/plasmidfinder
[abricate]: https://github.com/tseemann/abricate
[sistr_cmd]: https://github.com/phac-nml/sistr_cmd
[shovill]: https://github.com/tseemann/shovill
[ariba]: https://github.com/sanger-pathogens/ariba
[rgi]: https://github.com/arpcard/rgi
[pypi-staramr]: https://pypi.org/project/staramr/
[bioconda]: https://bioconda.github.io/
[card-web]: https://card.mcmaster.ca/
[tutorial]: doc/tutorial/staramr-tutorial.ipynb
[genes_to_exclude.tsv]: staramr/databases/exclude/data/genes_to_exclude.tsv
[MLST]: https://github.com/tseemann/mlst
