Skip to content

phac-nml/ecoli_serotyping

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

European Galaxy server GitHub release (latest SemVer) Conda PyPI version GitHub issues Docker Pulls GitHub commit activity

ECTyper (an easy typer)

ECTyper is a standalone versatile serotyping module for Escherichia coli. It supports both fasta (assembled) and fastq (raw reads) file formats. The tool provides convenient species identification coupled to quality control module giving a complete, transparent and reference laboratories suitable report on E.coli serotyping.

Dependencies:

  • python >= 3.5
  • bcftools >= 1.8
  • blast == 2.7.1
  • seqtk >= 1.2
  • samtools >= 1.8
  • bowtie2 >= 2.3.4.1
  • mash >= 2.0

Python packages:

  • biopython >= 1.70
  • pandas >= 0.23.1
  • requests >= 2.0

Installation

Option 1: As a conda package

  1. If you do not have conda environment, get and install miniconda or anaconda:

    bash miniconda.sh -b -p $HOME/miniconda
    echo ". $HOME/miniconda/etc/profile.d/conda.sh" >> ~/.bashrc
    source ~/.bashrc```
    
    
  2. Install conda package from bioconda channel conda install -c bioconda ectyper

Option 2: From the source directly

Second option is to install from the source.

  1. Install dependencies. On Ubuntu distro run
apt install samtools bowtie2 mash bcftools ncbi-blast+ seqtk
  1. Install python dependencies via pip:
pip3 install pandas biopython
  1. Clone the repository or checkout a particular release (e.g v1.0.0, etc.):
git clone https://github.com/phac-nml/ecoli_serotyping.git
git checkout v1.0.0 #optionally checkout release version
  1. Install ectyper: python3 setup.py install

Basic Usage

  1. Put the fasta/fastq files for serotyping analyses in one folder (concatenate paired raw reads files if you would like them to be considered a single entity)
  2. ectyper -i [file path] -o [output_dir]
  3. View the results on the console or in cat [output folder]/output.csv

Example Usage

  • ectyper -i ecoliA.fasta for a single file
  • ectyper -i ecoliA.fasta -o output_dir for a single file, results stored in output_dir
  • ectyper -i ecoliA.fasta,ecoliB.fastq,ecoliC.fna for multiple files (comma-delimited)
  • ectyper -i ecoli_folder for a folder (all files in the folder will be checked by the tool)

Advanced Usage

usage: ectyper [-h] [-V] -i INPUT [-c CORES] [-opid PERCENTIDENTITYOTYPE] [-hpid PERCENTIDENTITYHTYPE] [-opcov PERCENTCOVERAGEOTYPE] [-hpcov PERCENTCOVERAGEHTYPE] [--verify] [-o OUTPUT] [-r REFSEQ] [-s] [--debug] [--dbpath DBPATH]

ectyper v1.0.0 database v1.0 Prediction of Escherichia coli serotype from raw reads or assembled genome sequences. The default settings are recommended.

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -i INPUT, --input INPUT
                        Location of E. coli genome file(s). Can be a single file, a comma-separated list of files, or a directory
  -c CORES, --cores CORES
                        The number of cores to run ectyper with
  -opid PERCENTIDENTITYOTYPE, --percentIdentityOtype PERCENTIDENTITYOTYPE
                        Percent identity required for an O antigen allele match [default 90]
  -hpid PERCENTIDENTITYHTYPE, --percentIdentityHtype PERCENTIDENTITYHTYPE
                        Percent identity required for an H antigen allele match [default 95]
  -opcov PERCENTCOVERAGEOTYPE, --percentCoverageOtype PERCENTCOVERAGEOTYPE
                        Minumum percent coverage required for an O antigen allele match [default 90]
  -hpcov PERCENTCOVERAGEHTYPE, --percentCoverageHtype PERCENTCOVERAGEHTYPE
                        Minumum percent coverage required for an H antigen allele match [default 50]
  --verify              Enable E. coli species verification
  -o OUTPUT, --output OUTPUT
                        Directory location of output files
  -r REFSEQ, --refseq REFSEQ
                        Location of pre-computed MASH RefSeq sketch. If provided, genomes identified as non-E. coli will have their species identified using MASH. For best results the pre-sketched RefSeq archive https://gembox.cbcb.umd.edu/mash/refseq.genomes.k21s1000.msh is recommended
  -s, --sequence        Prints the allele sequences if enabled as the final columns of the output
  --debug               Print more detailed log including debug messages
  --dbpath DBPATH       Path to a custom database of O and H antigen alleles in JSON format. Check Data/ectyper_database.json for more information

Fine-tunning parameters

ECTyper requires minimum options to run (-i and -o) but allows for extensive configuration to accomodate wide variaty of typing scenarios

Parameter Explanation Usage scenario
-opid Specify minimum %identity threshold just for O antigen match Poor coverage of O antigen genes or for exploratory work (recommended value is 90)
-opcov Minimum %covereage threshold for a valid match against reference O antigen alleles Poor coverage of O antigen genes and a user wants to get O antigen call regardless (recommend value is 95)
-hpid Specify minimum %identity threshold just for H antigen match Poor coverage of O antigen genes or for exploratory work (recommend value is 95)
-hpcov Minimum %covereage threshold for a valid match against reference H antigen alleles Poor coverage of O antigen genes and a user wants to get O antigen call regardless (recommend value is 95)
--verify Verify species of the input and run QC module providing information on the reliability of the result and any typing issues User not sure if sample is E.coli and wants to obtain if serotype prediction is of sufficient quality for reporting purposes
-r Specify custom MASH sketch of reference genomes that will be used for species inference User has a new assembled genome that is not available in NCBI RefSeq database. Make sure to add metadata to assembly_summary_refseq.txt and provide custom accession number that start with GCF_ prefix
--dbpath Provide custom appended database of O and H antigen reference alleles in JSON format following structure and field names as default database ectyper_alleles_db.json User wants to add new alleles to the alleles database to improve typing performance

Quality Control (QC) module

To provide an easier interpretation of the results and typing metrics, following QC codes were developed. These codes allow to quickly filter "reportable" and "non-reportable" samples. The QC module is tightly linked to ECTyper allele database, specifically, MinPident and MinPcov fields. For each reference allele minimum %identity and %coverage values were determined as a function of potential "cross-talk" between antigens (i.e. multiple potential antigen calls at a given setting). The QC module covers the following serotyping scenarios. More scenarios might be added in future versions depending on user needs.

QC flag Explanation
PASS (REPORTABLE) Both O and H antigen alleles meet min %identity or %coverage thresholds (ensuring no antigen cross-talk) and single antigen predicted for O and H
FAIL (-:- TYPING) Sample is E.coli and O and H antigens are not typed. Serotype: -:-
WARNING MIXED O-TYPE A mixed O antigen call is predicted requiring wet-lab confirmation
WARNING (WRONG SPECIES) A sample is non-E.coli (e.g. E.albertii, Shigella, etc.) based on RefSeq assemblies
WARNING (-:H TYPING) A sample is E.coli and O antigen is not predicted (e.g. -:H18)
WARNING (O:- TYPING) A sample is E.coli and O antigen is not predicted (e.g. O17:-)
WARNING (O NON-REPORT) O antigen alleles do not meet min %identity or %coverage thresholds
WARNING (H NON-REPORT) H antigen alleles do not meet min %id or %cov thresholds
WARNING (O and H NON-REPORT) Both O and H antigen alleles do not meet min %identity or %coverage thresholds

Report format

ECTyper capitalizes on a concise minimum output coupled to easy results interpretation and reporting. ECTyper v1.0 serotyping results are available in a tab-delimited output.tsv file consisting of the 16 columns listed below:

  1. Name: Sample name (usually a unique identifier)
  2. Species: the species column provides valuable species identification information in case of inadvertent sample contamination or mislabelling events
  3. O-type: O antigen
  4. H-type: H antigen
  5. Serotype: Predicted O and H antigen(s)
  6. QC: The Quality Control value summarizing the overall quality of prediction
  7. Evidence: How many alleles in total used to both call O and H antigens
  8. GeneScores: ECTyper O and H antigen gene scores in 0 to 1 range
  9. AllelesKeys: Best matching ECTyper database allele keys used to call the serotype
  10. GeneIdentities(%): %identity values of the query alleles
  11. GeneCoverages(%): %coverage values of the query alleles
  12. GeneContigNames: the contig names where the query alleles were found
  13. GeneRanges: genomic coordinates of the query alleles
  14. GeneLengths: allele lengths of the query alleles
  15. Database: database release version and date
  16. Warnings: any additional warnings linked to the quality control status or any other error message(s).

Selected columns from the ECTyper typical report are shown below.

Name Species Serotype Evidence QC GeneScores AlleleKeys GeneIdentities(%) GeneCoverages(%) GeneContigNames GeneRanges GeneLengths Database Warnings
15-520 Escherichia coli O174:H21 Based on 3 allele(s) PASS (REPORTABLE) wzx:1; wzy:1; fliC:1; O104-5-wzx-origin;O104-13-wzy;H7-6-fliC-origin; 100;100;100; 100;100;100; contig00049;contig00001;contig00019; 22302-23492;178-1290;6507-8264; 1191;1113;1758; v1.0 (2020-05-07) -
EC20151709 Escherichia coli O157:H43 Based on 3 allele(s) PASS (REPORTABLE) wzx:1;wzy:0.999;fliC:1 O157-5-wzx-origin;O157-9-wzy-origin;H43-1-fliC-origin; 100;99.916;99.934; 100;100;100; contig00002;contig00002;contig00003; 62558-63949;64651-65835;59962-61467; 1392;1185;1506; v1.0 (2020-05-07) -

Availability

Resource Description Type
PyPI PyPI pacakge that could be installed via pip utility Terminal
Conda Conda package available from BioConda channel Terminal
Docker Images containing completely initialized ECTyper with all dependencies Terminal
Singluarity Images containing completely initialized ECTyper with all dependencies Terminal
GitHub Install source code as any Python package Terminal
Galaxy ToolShed Galaxy wrapper available for installation on a private/public instance Web-based
Galaxy Europe Galaxy public server to execute your analysis from anywhere Web-based
IRIDA plugin IRIDA instances could easily install additional pipeline Web-based