CPgeneProfiler

Generate a profile of carbapenamase genes from the genome assemblies

Content

Synopsis
Input Requirements
Installation
Example Usage
Working with testData
Output Files
Version
A few example plots
Community Guidelines
Bug Report and Support Request

Synopsis

Current AMR detection tools generate comparative tables across genomes and can help in visualization of comprehensive AMR gene complement. Nevertheless, they do not readily generate a genetic profile for the presence of CP genes, extract and visualize the cocarriage of CP genes. Achieving this currently necessitates a restructuring and transformation of the output from these tools.

To address this need, we describe here a lightweight R package, CPgeneProfiler that scans multiple bacterial genome assemblies to detect and visualize the presence of CP genes and their cocarriage using the R framework. Input required is a directory of FASTA file with genome assemblies.

Additionally, this package also allows to assess the size of CP contigs to check if the CP genes are distributed on the particular sequence size by generating the contig length distribution plots.

Other assembly statistics such as N50, N90, Assembly Size from the assembly are calculated and plots of length distribution of CP gene contigs from the list of assemblies are reported.

Currently the package works only on Unix systems.

Input Requirements

Path of a directory with multiple FASTA files (can be in multiple contigs)
Path of Carbapenemase Gene Database file (FASTA) directory

Conda (https://anaconda.org/bioconda/cpgeneprofiler)

To install this package with conda run:

conda install -c bioconda cpgeneprofiler

Requirements

R packages (REQUIRED): tidyverse, UpSetR, scales, ape, BiocManager, Biostrings, reshape2, gridExtra png, tiff, jpeg, pdftools, grid

Install these packages using R (versions >=3.6):

install.packages(c("BiocManager", "tidyverse", "UpSetR", "scales", "ape", 
                    "reshape2", "gridExtra","png", "tiff", "jpeg", "pdftools", "grid"))

BiocManager::install("Biostrings")

External software (REQUIRED): NCBI BLAST 2.9.0+
- Go to page: https://ftp.ncbi.nlm.nih.gov/blast/executables/blast+/2.9.0/
- Save ncbi-blast-2.9.0+-x64-linux.tar.gz in the local directory
- To install, simply extract the downloaded package using the following command
```
 tar zxvpf ncbi-blast-2.9.0+-x64-linux.tar.gz
```
- Configure of NCBI BLAST+ executables using the following command. This would append the path to the new BLAST bin directory to the existing PATH setting.
```
 export PATH=$PATH:$HOME/ncbi-blast-2.9.0+/bin
```
- Refer here for source documentation
  
  Note 1: R package assumes blastn and makeblastdb files are in path
  
  Note 2: BLAST version 2.9.0+ was used for the present program although other BLAST+ similar to version 2.9.0+ parameters might also run without problems
CP gene Database Download (REQUIRED)

The CP gene database can be downloaded either of the following 3 ways:

Using R console

# Specify CP gene database URL 
url <- "https://raw.githubusercontent.com/ramadatta/CPgeneProfiler/master/testData/db/NCBI_BARRGD_CPG_DB.fasta"

# Specify destination where CP gene database file should be saved 
path <- "/home/user/db" # Can change to prefarable location
setwd(path)
destfile <- "NCBI_BARRGD_CPG_DB.fasta"

# Download the CP gene database file to the folder set in "path"
download.file(url, destfile)

Using UNIX/Linux command line terminal and download the db folder with SVN

svn export https://github.com/ramadatta/CPgeneProfiler/trunk/testData/db

Else, simply Click to save database folder and uncompress the db.zip folder.

Installation

From Github

The R package is available through github repository can be installed using devtools.

install.packages("devtools")
devtools::install_github("ramadatta/CPgeneProfiler")

Check installation

Ensure you have installed the package properly:

library("CPgeneProfiler")
?CPgeneProfiler

Example Usage

CPgeneProfiler package can be run using the following functions: cpblast(), filt_blast(), cocarriage(), cpprofile(), upsetR_plot(), plot_conlen(),assemblystat(), cp_summarize(), db_summary(). Below are the examples of CPgeneProfiler commands usage.

Generates NCBI BLAST Results by aligning input genome assemblies against Carbapenamase (CP) gene database

cpblast(fastalocation = "/home/user/CPgeneProfiler/testData/fasta", dblocation = "/home/user/CPgeneProfiler/testData/db")

Filtering NCBI BLAST Results based on CP gene coverage and percent identity. By default, alignment coverage of CP gene (cpgcov) and percentage identity (cpgpident) are set to 100%.

filt_blast(cpgcov = 100, cpgpident = 100)

Report cocarriage of CP genes across all the input genome assemblies (Default:cpgcov = 100 and cpgpident = 100)

cocarriage(cpgcov = 100, cpgpident = 100)

Generate CP gene Profile across all the input genome assemblies (Default:cpgcov = 100 and cpgpident = 100)

cpprofile(xlab = "Carbapenamase Genes", ylab = "Assembly", title = "Carbapenamase Gene Profile Heatmap")

Plot CP gene contig length distributions across all the input genome assemblies (Default:cpgcov = 100 and cpgpident = 100)

plot_conlen(outputType = "png", xlab = "Contig Length", ylab = "Number of Contigs", title = " Contig Length Distribution", colorfill = "#F99245")

Generate set intersection plot of CP genes across all the input genome assemblies (Default:cpgcov = 100 and cpgpident = 100)

upsetR_plot(outputType="png", width = 2000, height = 2000, res = 250, xlab="Carbapenamase Gene Set Size", ylab="Number of genome assemblies",cpgcov=100, cpgpident=100, order.by = "degree",nsets = 40, number.angles = 0,point.size = 1.5, line.size = 1,sets.bar.color = "red")

Generate basic assembly statistics such N50, N90 and Assembly Size and plots comparing Assembly Size with N50, N90 stats

assemblystat(fastalocation = "/home/user/CPgeneProfiler/testData/fasta")

Summarize the plots and organize all the output files in specific folders

cp_summarize(outdir_loc = "/home/user/Desktop", outdir = "CPgeneProfiler_Output")

Database information

db_summary()

Working with `testData`

Test Data Download

To test the package with test input data, Go to the UNIX/Linux command line terminal and download the fasta folder with SVN

svn export https://github.com/ramadatta/CPgeneProfiler/trunk/testData/fasta

else simply Click to save fasta folder and uncompress the fasta.zip folder.

1) A simple NCBI BLAST using `cpblast()` command

As a first step, CPgeneProfiler generates NCBI BLAST Results by aligning input genome assemblies against Carbapenamase (CP) gene database. Now that you already have a directory with fasta files (should have extensions .fasta or .fa) in fasta folder and cp gene database sequence in db folder, you can specify the path of both directories as an input and run the package with cpblast() command.

cpblast(fastalocation = "/home/user/CPgeneProfiler/testData/fasta", dblocation = "/home/user/CPgeneProfiler/testData/db", num_threads = 4, evalue = "1e-3")

The users can adjust BLAST parameters num_threads, evalue, word_size and max_target_seqs accordingly. If not adjusted and command is simply executed with the file locations for fasta and db, then default parameters are used for the analysis.

2) Filtering BLAST results using `filt_blast()` command

filt_blast() then filters the output BLAST results obtained from cpblast() command. This filtering is to find the presence of CP genes given a particular CP gene coverage and Percentage Identity. Therefore, the BLAST hits are filtered based on CP gene coverage and Percentage Identity. By default, CP Gene Coverage and Percentage Identity are set at a threshold of 100% (cpgcov=100, cpgpident=100). This means that a CP gene should have 100% alignment length and 100% identity, without even a single mismatch with the input genome sequence. The default parameters can be adjusted.

filt_blast(cpgcov = 100, cpgpident = 100)

This should generate the following table:

assemblyName	qseqid	sseqid	qlen	slen	qstart	qend	length	pident	cov
genome_001.fasta	4_length=71861_depth=1.95x_circular=true	KPC-2	71861	918	3810	4727	918	100	100
genome_001.fasta	5_length=71851_depth=1.95x_circular=true	KPC-2	71851	918	3810	4727	918	100	100
genome_002.fasta	5_length=51479_depth=1.31x_circular=true	OXA-181	51479	998	31280	32277	998	100	100
genome_003.fasta	2_length=316292_depth=2.71x_circular=true	NDM-1	316292	1013	149582	150594	1013	100	100
genome_003.fasta	2_length=316292_depth=2.71x_circular=true	OXA-181	316292	998	49123	50120	998	100	100
genome_004.fasta	3_length=66727_depth=0.76x	OXA-181	66727	998	49850	50847	998	100	100
genome_004.fasta	3_length=66727_depth=0.76x	OXA-181	66727	998	43441	44438	998	100	100
genome_004.fasta	3_length=66727_depth=0.76x	OXA-181	66727	998	37032	38029	998	100	100
genome_005.fasta	2_length=79441_depth=2.21x_circular=true	KPC-2	79441	918	11390	12307	918	100	100
genome_005.fasta	2_length=79441_depth=2.21x_circular=true	KPC-2	79441	918	3810	4727	918	100	100
genome_007.fasta	2_length=246497_depth=2.06x_circular=true	KPC-2	246497	918	178390	179307	918	100	100
genome_007.fasta	2_length=246497_depth=2.06x_circular=true	IMP-26	246497	861	145325	146185	861	100	100
genome_008.fasta	3_length=41186_depth=4.61x_circular=true	NDM-1	41186	1013	23027	24039	1013	100	100
genome_009.fasta	4_length=41182_depth=4.10x_circular=true	NDM-1	41182	1013	23023	24035	1013	100	100
genome_010.fasta	5_length=51479_depth=1.31x_circular=true	OXA-181	51479	998	31280	32277	998	100	100
genome_010.fasta	3_length=41186_depth=4.61x_circular=true	NDM-1	41186	1013	23027	24039	1013	100	100
genome_012.fasta	2_length=79441_depth=2.21x_circular=true	KPC-2	79441	918	11390	12307	918	100	100
genome_012.fasta	2_length=79441_depth=2.21x_circular=true	KPC-2	79441	918	3810	4727	918	100	100
genome_013.fasta	3_length=41186_depth=4.61x_circular=true	NDM-1	41186	1013	23027	24039	1013	100	100
genome_014.fasta	4_length=41182_depth=4.10x_circular=true	NDM-1	41182	1013	23023	24035	1013	100	100
genome_015.fasta	3_length=66727_depth=0.76x	OXA-181	66727	998	49850	50847	998	100	100
genome_015.fasta	3_length=66727_depth=0.76x	OXA-181	66727	998	43441	44438	998	100	100
genome_015.fasta	3_length=66727_depth=0.76x	OXA-181	66727	998	37032	38029	998	100	100

3) Finding cocarriage genes using `cocarriage()` command

cocarriage() command finds if two or more CP genes exists in same contig or multiple contigs across all the input genome assemblies. This function can be used only after running filt_blast(). By default, parameters such as CP Gene Coverage and Percentage Identity are set to 100% (cpgcov=100, cpgpident=100) but can be adjusted as per requirement.

cocarriage(cpgcov = 100, cpgpident = 100)

4) Finding CP gene profile using `cpprofile()` command

cpprofile() creates a heatmap of CP gene profile across the input genome assemblies. By default, the command generates png image but user can also create image with other output formats (jpeg/tiff/pdf) and parameters such as width, height of image, label, titles and colors of the heatmap can be adjusted as per requirement.

cpprofile(outputType="png", width = 2000, height = 2000, res = 250, xlab="Carbapenamase Genes", ylab="Assembly", title="Carbapenamase Gene Profile Heatmap", titlesize=15, labelsize=12, colorcode_low = "#143D59", colorcode_high = "#F4B41A", cpgcov=100, cpgpident=100)

5) Plot CP gene contig length distribution using `plot_conlen()` command

plot_conlen() generates length distribution for all the CP gene contigs present across all the input genome assemblies. By default, the command generates png image but user can also create image with other output formats (jpeg/tiff/pdf) and parameters such as width, height of image, label, titles and colors of the heatmap can be adjusted as per requirement.

plot_conlen(outputType="tiff", width = 700, height = 700, res = 150, xlab="Contig Length", ylab="Number of Contigs", title=" Contig Length Distribution",element_text_angle=90,unit="KB", breaks=15, colorfill = "#F99245",cpgcov=100, cpgpident=100)

6) Generate assembly statistics using `assemblystat()` command

assemblystat() generates basic assembly stats which includes N50 size, N90 size and Genome assembly size. This function also generates Assembly Size vs N50 & Assembly Size vs N90 plots. This function requires the location of fasta file directory. By default, the command generates png image plots.

assemblystat("/home/user/CPgeneProfiler/testData/fasta", outputType="png", width = 700, height = 700, res = 150, geom_point_size=3, n50colorfill = "#0072B2", n90colorfill = "#D55E00")

7) Generate Set Intersection of CP genes using `upsetR_plot()` command

upsetR_plot() generates set intersection plot of CP genes across all the input genome assemblies. By default, the command generates png image but user can change the output image type, width and height of image, label, titles and colors.

upsetR_plot(outputType="png", width = 2000, height = 2000, res = 250, xlab="Carbapenamase Gene Set Size", ylab="Number of genome assemblies",cpgcov=100, cpgpident=100, order.by = "degree",nsets = 40, number.angles = 0,point.size = 1.5, line.size = 1,sets.bar.color = "red")

8) Summarize all the results using `cp_summarize()` command

cp_summarize() arranges all the output files generated from above commands into respective folders. This also creates a summary of all the plots from CPgeneProfiler output into a single PDF file. Users can specify the output directory name and summary pdf name and also can provide the location of where the output folder to be generated. Note: All the output image plots need to be in the same format i.e, either png/tiff/jpeg.

cp_summarize(outdir = "CPgeneProfiler_Output", report="Summary" , image = "png")

9) Find Database summary details using `db_summary()` command

db_summary() command displays the details of Database. This includes Database Name, Version, Total number of sequences in currently in CP gene Database, Last updated date, Reference web link from which database was downloaded.

db_summary()
[1] "DATABASE: NCBI Bacterial Antimicrobial Resistance Reference Gene Database"
[1] "VERSION: 2020-07-16.2"
[1] "SEQUENCES: 875"
[1] "DBTYPE: nucl"
[1] "DATE: 2020-Aug-23"
[1] "Reference Gene Catalog: ftp://ftp.ncbi.nlm.nih.gov/pathogen/Antimicrobial_resistance/AMRFinderPlus/database/3.8/"

Output Files

A folder "CPgeneProfiler_Output" with the following files in respective directories

Command	File	Description
cpblast()	blastResults.txt	Blast Results of contigs against the CP genes
filt_blast()	blastResults.filt.txt	Filtered blast results with contains contigs matching CP genes (default: 100% identity and 100% coverage)
cocarriage()	Cocarriage_Report.txt	Information of Number of assemblies with the co-carriage broken down to category
cocarriage()	Cocarriage_combinedResults.txt	Combined cocarriage details across all the assemblies
cocarriage()	DiffCP_DiffContig.txt	Information of assemblies with different CP genes present in different contigs
cocarriage()	DiffCP_SameContig.txt	Information of assemblies with different CP genes present in same contigs
cocarriage()	SameCP_DiffContig.txt	Information of assemblies with same CP genes present in different contigs
cocarriage()	SameCP_SameContig.txt	Information of assemblies with same CP genes present in same contigs
cpprofile()	CPgeneProfile.png	Carbapenamase Gene Profile (default:png)
plot_conlen()	CPContigSizeDist.txt	Contig Size distribution
plot_conlen()	"CPGene"_Contig_Dist.png	CP gene contig length distribution (for each CP gene a separate distribution plot is generated. Default image format: png)
upsetR_plot()	cp_presence-absence_matrix.csv	Presence-absence matrix of CP genes across assemblies
upsetR_plot()	upset_plot.pdf	Set intersection plot of CP genes across all the input genome assemblies
assemblystat()	N50_N90.pdf	Assembly Size vs N50, N90 plots
assemblystat()	assemblyStats.txt	A simple text file with N50, N90, Assembly Size for each assembly
cp_summarize()	SummaryPlots.pdf	All the plots in a single pdf file

A few example plots

`CP Gene Profile HeatMap`

`Assembly Size vs N50 and N90 plots`

`UpsetR plot` (orderby: freq vs degree)

`Contig Length Distribution Plots`

Version

version 2.1.1

Modularised single function to multiple functions
Added more flexibility to each function
Changed the database from ARG-ANNOT to NCBI Bacterial AMR Reference Gene Database

version 2.1.0

Changed the heatmap colors
User can decide to download the ARG-annot database to desired location
Both fasta folder and db location are to be provided for the package

Community Guidelines

How to Contribute

In general, you can contribute to this project by creating issues. You are also welcome to contribute to the source code directly by forking the project, modifying the code, and creating pull requests. If you are not familiar with pull requests, check out this post. Please use clear and organized descriptions when creating issues and pull requests.

Please note that CPgeneProfiler is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

Bug Report and Support Request

You can use issues to report bugs and seek support. Before creating any new issues, please check for similar ones in the issue list first.

Citation

If you publish the results of CPgeneProfiler, please also cite the following software and the database:

Sridatta et al., (2020). CPgeneProfiler: A lightweight R package to profile the Carbapenamase genes from genome assemblies. Journal of Open Source Software, 5(54), 2473, https://doi.org/10.21105/joss.02473

Camacho, C., Coulouris, G., Avagyan, V., Ma, N., Papadopoulos, J., Bealer, K., & Madden, T. L. (2009). BLAST+: Architecture and applications. BMC Bioinformatics, 10(1), 421.doi:10.1186/1471-2105-10-421

Jake R Conway, Alexander Lex, Nils Gehlenborg, UpSetR: an R package for the visualization of intersecting sets and their properties, Bioinformatics, Volume 33, Issue 18, 15 September 2017, Pages 2938–2940, https://doi.org/10.1093/bioinformatics/btx364

NCBI Bacterial Antimicrobial Resistance Reference Gene Database (https://www.ncbi.nlm.nih.gov/bioproject/PRJNA313047)

Name		Name	Last commit message	Last commit date
Latest commit History 161 Commits
R		R
man		man
testData		testData
testData_Output		testData_Output
CPgeneProfiler.Rproj		CPgeneProfiler.Rproj
Code_of_Conduct.md		Code_of_Conduct.md
DESCRIPTION		DESCRIPTION
LICENSE.md		LICENSE.md
NAMESPACE		NAMESPACE
README.md		README.md
as1_2.png		as1_2.png
cpprof_upset.png		cpprof_upset.png
image.jpg		image.jpg
len1_2.png		len1_2.png
paper.bib		paper.bib
paper.md		paper.md

License

ramadatta/CPgeneProfiler

Folders and files

Latest commit

History

Repository files navigation

CPgeneProfiler

Content

Synopsis

Input Requirements

Conda (https://anaconda.org/bioconda/cpgeneprofiler)

Requirements

Installation

From Github

Check installation

Example Usage

Working with testData

Test Data Download

1) A simple NCBI BLAST using cpblast() command

2) Filtering BLAST results using filt_blast() command

3) Finding cocarriage genes using cocarriage() command

4) Finding CP gene profile using cpprofile() command

5) Plot CP gene contig length distribution using plot_conlen() command

6) Generate assembly statistics using assemblystat() command

7) Generate Set Intersection of CP genes using upsetR_plot() command

8) Summarize all the results using cp_summarize() command

9) Find Database summary details using db_summary() command

Output Files

A few example plots

CP Gene Profile HeatMap

Assembly Size vs N50 and N90 plots

UpsetR plot (orderby: freq vs degree)

Contig Length Distribution Plots