plasmidfinder 3.0.2

The application identifies plasmids in total or partial sequenced isolates of bacteria.

PlasmidFinder

This project documents the PlasmidFinder service

IMPORTANT: It must be noted that a webserver implementing the methods is freely available at the CGE website and can be found here: https://cge.food.dtu.dk/services/PlasmidFinder/.

Documentation

The PlasmidFinder service is a service that identifies plasmids in total or partial sequenced isolates of bacteria, and it is implemented in the three following python scripts:

1. _init_.py contains the current version of the service.
2. _main_.py is the file that runs the service.
3. functions.py defines some of the functions called by _main_.py.

Content of the repository

1. _init_.py, _main_.py and functions.py - the program
2. test - this folder contains fsa and fq files for testing purposes. Refer to the file called READ_ME_test_info.md for more information.
3. tests - this folder contains pytest
4. README.md
5. Dockerfile - dockerfile for building the plasmidfinder docker container

Installation

We only recommend installation using pip

1. Recommended: Installation using pip

pip install PlasmidFinder

This will install the PlasmifFinder tool. You can find the database here: https://bitbucket.org/genomicepidemiology/plasmidfinder_db/src/master/ which will also need to be downloaded and installed in order to use the tool.

2. Installation by cloning the repository

We do not recommend cloning the repository. Instead, you should use pip install and download the database. This ensures the latest stable version is installed.

In order to run this program without docker, the user must first make sure to have all needed dependencies installed in their device. In order to run the program without using docker, Python 3.5 (or newer) should be installed along with the following versions of the modules (or newer).

It may be advisable to use a virtual environment for these installations.

Modules

• cgecore 1.5.5
• tabulate 0.7.7

Modules can be installed using the following command. Here, the installation of the module cgecore is used as an example:

pip3 install cgecore

KMA and BLAST

Additionally KMA and BLAST version 2.8.1 or newer should be installed. The newest version of KMA and BLAST can be installed from here:

https://bitbucket.org/genomicepidemiology/kma

ftp://ftp.ncbi.nlm.nih.gov/blast/executables/blast+/LATEST/

3. Installation with Docker

As mentioned, the Dockerfile is included in the repository and will be downloaded when it is cloned.

Setting up PlasmidFinder program

# Go to wanted location for plasmidfinder
cd /path/to/some/dir
# Clone and enter the plasmidfinder directory
git clone https://bitbucket.org/genomicepidemiology/plasmidfinder.git
cd plasmidfinder

Build Docker container

# Build container
docker build -t plasmidfinder .
# Run test: this should bring up the help message
docker run plasmidfinder -h

Download and install PlasmidFinder database

# Go into the directory where you installed plasmidfinder
cd /path/to/some/dir/plasmidfinder
# Clone database from git repository (develop branch)
git clone https://bitbucket.org/genomicepidemiology/plasmidfinder_db.git
cd plasmidfinder_db
PLASMID_DB=$(pwd)
# Install PlasmidFinder database with executable kma_index program
python3 INSTALL.py 

If kma_index has no bin install please install kma_index from the kma repository: https://bitbucket.org/genomicepidemiology/kma

Example run with Docker

#This will only work if you have cloned plasmidfinder_db inside plasmidfinder. You can of course clone plasmidfinder_db where you like, just make sure to mount the directory into the container.
docker run -v "$(pwd):/app" plasmidfinder -i ./test/test_1_1.fq -o ./test_results -tmp ./test_results -p ./plasmidfinder_db -x -j ./test_results/new_json_test_1.json

Usage

The program can be invoked with the -h option to get help and more information of the service.

Usage:

__main__.py [-h] -i INFILE [INFILE ...] [-o OUTDIR] [-tmp TMP_DIR] [-mp METHOD_PATH] [-p DB_PATH] [-d DATABASES] [-l MIN_COV] [-t THRESHOLD] [-x] [-q] [-j OUT_JSON]

Options:

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

-i INFILE, --infile INFILE FASTA or FASTQ input files relative to pwd, up to two files. (REQUIRED)

-o OUTDIR, --outputPath OUTDIR Output directory relative to pwd. (RECOMMENDED)

-tmp TMP_DIR, --tmp_dir TMP_DIR Temporary directory for storage of the results from the external software.

-mp METHOD_PATH, --methodPath METHOD_PATH Path to the method to use (kma or blastn).

-p DB_PATH, --databasePath DB_PATH Path to the databases directory.

-d DATABASES, --databases DATABASES Databases chosen to search in - if nothing is specified, all databases available will be used by default.

-l MIN_COV, --mincov MIN_COV Minimum coverage: minimum percentage of coverage between a plasmid and uploaded data. All plasmids with a % coverage equal or larger than the selected threshhold will be shown in the output. DEFAULT VALUE= 0.60

-t THRESHOLD, --threshold THRESHOLD Minimum threshold for identity: the minimum percentage of nucleotides that are identical between the best matching resistance gene in the database and the corresponding sequence in the genome. All genes with a %ID equal or larger than the selected threshold will be shown in the output. DEFAULT VALUE= 0.90.

-x, --extented_output Gives extented output with allignment files, template and query hits in fasta and a tab seperated file with gene profile results.

-q, --quiet

-j OUT_JSON, --json OUT_JSON Path to the file in the (new) BeOne JSON format. If no argument is provided, the program will output the results to the default name.

--legacy Only choose this option if you want the legacy JSON file (PlasmidFinder < 3.0.0)

Example usage (if downloaded using pip)

To test the installation , this should bring up the options menu:

	python -m plasmidfinder -h

An example of a run could be:

	python -m plasmidfinder -i my_file_to_analyse.fsa -o path/to/output/folder -tmp path/to/tmp/folder -p /path/to/database/plasmidfinder_db/ -x -j my_output_file.json

Notes

• If neither -j or --legacy are chosen, the program will output the newer (BeOne) format by default. The file will be written to the current directory with the name "results_<INPUT_FILE_NAME>.json". The extended output option can stil be chosen regardless.

For developers

a. Using a dependency manager

In order to simplify the installation of this service, the dependencies are managed by PDM. Please refer to this web page for an in-depth explanation of this library and alternative installation methods: https://pdm.fming.dev/latest/ . To install PDM please run the following lines. Note that Python 3.7 or higher is required to run PDM. An alternative to using PDM is provided below.

In short, the following commands must be run for Linux or Mac:

curl -sSL https://pdm.fming.dev/install-pdm.py | python3 -w

And the following should be run for Windows:

(Invoke-WebRequest -Uri https://pdm.fming.dev/install-pdm.py -UseBasicParsing).Content | python -

b. Without using a dependency manager

If you do not wish to use the dependency manager, you must keep in mind the following depedencies:

• Python 3.5 (or newer)
• cgecore 1.5.5 (or newer)
• tabulate 0.7.7 (or newer)
• cgelib
• pandas
• biopython

These can be installed using pip as follows:

pip3 install cgecore

---

Attention! KMA and BLAST

Additionally KMA and BLAST version 2.8.1 or newer should be installed. The newest version of KMA and BLAST can be installed from here:

https://bitbucket.org/genomicepidemiology/kma

ftp://ftp.ncbi.nlm.nih.gov/blast/executables/blast+/LATEST/

Installation of the library and database

Setting up PlasmidFinder program. The following code will download the library in your chosen directory.

# Go to wanted location for plasmidfinder
cd /path/to/some/dir
# Clone and enter the plasmidfinder directory
git clone https://bitbucket.org/genomicepidemiology/plasmidfinder.git

Then, the PlasmidFinder database will be downloaded into your chosen directory.

# Go to the directory where you want to store the plasmidfinder database
cd /path/to/some/dir
# Clone database from git repository (develop branch)
git clone https://bitbucket.org/genomicepidemiology/plasmidfinder_db.git
cd plasmidfinder_db
PLASMID_DB=$(pwd)
# Install PlasmidFinder database. NOTE that KMA needs to have been installed for the following comand. 
python3 INSTALL.py 

Citation

When using the method please cite:

PlasmidFinder and pMLST: in silico detection and typing of plasmids. Carattoli A, Zankari E, Garcia-Fernandez A, Volby Larsen M, Lund O, Villa L, Aarestrup FM, Hasman H. Antimicrob. Agents Chemother. 2014. April 28th. [Epub ahead of print]

References

1. Camacho C, Coulouris G, Avagyan V, Ma N, Papadopoulos J, Bealer K, Madden TL. BLAST+: architecture and applications. BMC Bioinformatics 2009; 10:421.
2. Clausen PTLC, Aarestrup FM, Lund O. Rapid and precise alignment of raw reads against redundant databases with KMA. BMC Bioinformatics 2018; 19:307.

License

Copyright (c) 2014, Ole Lund, Technical University of Denmark All rights reserved.

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.