library(epi2me2r)The epi2me2r package includes fully automated methods to take raw CSVs of CARD ARMA and WIMP output from the EPI2ME pipeline from Oxford Nanopore and quickly convert it into common R package formats, namely phyloseq and metagenomeSeq.
There are three main types of functions in epi2me2r:
phyloseq or metagenomeSeq objects for downstream analysis:
amr_raw_to_phyloseq()amr_raw_to_metagenomeseq()wimp_raw_to_phyloseq()wimp_raw_to_metagenomeseq()read_in_amr_files()read_in_wimp_files()generate_amr_taxonomy()generate_wimp_taxonomy()amr_read_taxonomy(). This function reads in both AMR and WIMP raw data and adds the taxonomic information to the AMR gene if available.Prior to starting, making sure the metadata file is formatted appropriately will ensure your data is imported correctly. You can use one combined metadata file for both your AMR and WIMP samples or a separate file for each. Both options are described below.
This file has 4 required columns that must be named as follows:
arma_filename : the original amr file name without the .csv extensionarma_barcode : the barcodes of each sample (note: if you did not barcode any of your samples, enter none in all of the cells). In the AMR workflow, missing barcodes are coded as nonewimp_filename : the original amr file name without the .csv extensionwimp_barcode : the barcodes of each sample (note: if you did not barcode any of your samples, enter NA in all of the cells). In the WIMP workflow, missing barcodes are coded as NAadditional information after these four required columns, you may include any additional metadata that is important, such as treatment type, sample numbers, etc.An example of a combo metadata file is included with this package.
epi2me.metadata <- read.csv(system.file("extdata", "example_metadata.csv", package = "epi2me2r"))
head(epi2me.metadata)## arma_filename wimp_filename arma_barcode wimp_barcode Samplename treatment
## 1 arma_288715 324212_1777 barcode02 barcode02 Animal1 control
## 2 arma_288715 324212_1777 barcode03 barcode03 Animal2 antibiotic
## 3 arma_288715 324212_1777 barcode04 barcode04 Animal3 control
## 4 arma_288716 324212_1778 none <NA> Animal4 antibioticIf you are just importing WIMP or CARD ARMA files, you do not need all the metadata associated with the other workflow.
If you are just processing ARMA CARD data, the required columns are: * arma_filename * arma_barcode * other metadata such as treatment and sample names
On the other hand, if you are just processing WIMP data the required columns are: * wimp_filename * wimp_barcode * other metadata such as treatment and sample names
Even if you are just processing one type of data, both ARMA and WIMP information can be included in the metadata (as seen in the section on combo metadata above).
For both AMR and WIMP data, the raw CSVs downloaded from the epi2me website need to be in their own directory (without any other files). Note that if you are processing both WIMP and ARMA data you will need two directories, one for each set of data.
Reading the AMR data requires a directory and a metadata file. The directory should have only the CSV files generated by EPI2ME in it. An example of the metadata file is above. The data we will be using is from an example run on the EPI2ME pipeline. There are four options:
path.to.amr.files required: the path to the raw CSV files (for example "Desktop/raw_data/")metadata required: metadata formatted as described above as a data.framecoveragenumber optional : the total length of the gene that must be present for it to be included in the count table. The default is 80%; this argument takes any number from 1 to 99. Default is 80.keepSNP optional : whether to include genes that are considered resistance genes only with a SNP mutation. Default is FALSE (does not include these genes) but can be changed to TRUE to include these genes.In the following code example, we use the amr_raw_to_phyloseq() function and the included example metadata file read in above, as well as a directory containing example AMR files also included with the epi2me2r package. This code creates a phyloSeq object from the example AMR files and metadata.
example.amr.dir <- system.file("extdata", "example_amr_data", package = "epi2me2r")
ps.amr.object <- amr_raw_to_phyloseq(path.to.amr.files = example.amr.dir,
metadata = epi2me.metadata,
coveragenumber = 80,
keepSNP = FALSE)## Reading in raw AMR files from C:/Users/qdread/AppData/Local/Temp/RtmpSCYKke/Rinst14fc4d0559bb/epi2me2r/extdata/example_amr_dataThe amr_raw_to_metagenomeseq() function uses the same arguments as above for importing to metagenomeSeq:
mgs.amr.object <- amr_raw_to_metagenomeseq(path.to.amr.files = example.amr.dir,
metadata = epi2me.metadata,
coveragenumber = 80,
keepSNP = FALSE)## Reading in raw AMR files from C:/Users/qdread/AppData/Local/Temp/RtmpSCYKke/Rinst14fc4d0559bb/epi2me2r/extdata/example_amr_datamgs.amr.object## MRexperiment (storageMode: environment)
## assayData: 67 features, 4 samples
## element names: counts
## protocolData: none
## phenoData
## sampleNames: arma_288715_barcode02 arma_288715_barcode03
## arma_288715_barcode04 arma_288716_none
## varLabels: arma_filename wimp_filename ... sampleID (7 total)
## varMetadata: labelDescription
## featureData
## featureNames: sp1 sp2 ... sp67 (67 total)
## fvarLabels: OTUname CVTERMID ... ARO.Name (6 total)
## fvarMetadata: labelDescription
## experimentData: use 'experimentData(object)'
## Annotation:WIMP files are similar to the AMR files but use the package taxonomizr to add taxonomic hierarchical information.
Reading in the WIMP data requires a directory and a metadata file. The directory should have only the CSV files generated by EPI2ME in it. An example of the metadata file is above. The data we will be using is from an example run on the EPI2ME pipeline. There are four options:
path.to.wimp.files required: the path to the raw CSV files (for example "Desktop/raw_data/")metadata required: metadata formatted as described above as a data.framekeep.unclassified optional : whether to keep genes that do not classify or do not classify beyond a superkingdom. Default is FALSE (does not include these reads) but can be changed to TRUE to include these readskeep.human optional : whether to keep reads associated with Homo sapiens (usually considered a contaminant in microbiome data). Default is FALSE (does not include human-associated reads) but can be changed to TRUE to include these reads.The following code uses the wimp_raw_to_phyloseq() function and the example metadata we read in above as well as a directory of example WIMP files included with the package to convert the raw WIMP files to a phyloSeq object:
example.wimp.dir <- system.file("extdata", "example_wimp_data", package = "epi2me2r")
ps.wimp.object <- wimp_raw_to_phyloseq(path.to.wimp.files = example.wimp.dir,
metadata = epi2me.metadata,
keep.unclassified = FALSE,
keep.human = FALSE)Like the functions for AMR, the wimp_raw_to_metagenomeSeq() function uses the same arguments for importing to metagenomeSeq are used as were used above in the wimp_raw_to_phyloseq() function:
mgs.wimp.object <- wimp_raw_to_metagenomeseq(path.to.wimp.files = example.wimp.dir,
metadata = epi2me.metadata,
keep.unclassified = FALSE,
keep.human = FALSE)In some cases you might not want a phyloseq or metagenomeSeq object, but instead just a count matrix or taxonomic list. In these cases you can use the below functions.
This takes the directory that the AMR CSV files are in and creates a count matrix that can be used in downstream analysis. The inputs are similar to those in the previous examples (but metadata is not required):
path.to.amr.files required: the path to the raw CSV files (for example "Desktop/raw_data/")coveragenumber optional : the total length of the gene that must be present for it to be included in the count table. The default is 80%; this argument takes any number from 1 to 99. Default is 80.keepSNP optional : whether to include genes that are considered resistance genes only with a SNP mutation. Default is FALSE (does not include these genes) but can be changed to TRUE to include these genes.amr.count.table <- read_in_amr_files(path.to.amr.files = example.amr.dir,
coveragenumber = 80,
keepSNP = FALSE)## Reading in raw AMR files from C:/Users/qdread/AppData/Local/Temp/RtmpSCYKke/Rinst14fc4d0559bb/epi2me2r/extdata/example_amr_datahead(amr.count.table)## CVTERMID arma_288715_barcode02 arma_288715_barcode03 arma_288715_barcode04
## 1: 36033 5 1 1
## 2: 36036 0 0 1
## 3: 36213 0 1 1
## 4: 36355 3 2 3
## 5: 36376 0 0 0
## 6: 36448 2 0 0
## arma_288716_none
## 1: 3
## 2: 0
## 3: 1
## 4: 1
## 5: 1
## 6: 1This function assigns AMR taxonomic hierarchical information from CARD using a count table with CV TERM ID’s as the first column ("CVTERMID"). Only one input is needed:
amr.count.table required: data frame of generated with amr.count.table or that has CVTERMID as the first column for AMR taxonomic assignmentverbose optional : only a subset of column names are included in the output by default: (CVTERMID,Drug Class, AMR Gene Family, Resistance Mechanism, and ARO Name). If verbose==TRUE 13 columns are returned.amr.taxonomy <- generate_amr_taxonomy(amr.count.table = amr.count.table,
verbose = FALSE)
head(amr.taxonomy)## CVTERMID
## 1: 36033
## 2: 36036
## 3: 36213
## 4: 36355
## 5: 36376
## 6: 36448
## Drug Class
## 1: fluoroquinolone antibiotic
## 2: fluoroquinolone antibiotic
## 3: fluoroquinolone antibiotic
## 4: cephalosporin;fluoroquinolone antibiotic;glycylcycline;penam;phenicol antibiotic;rifamycin antibiotic;tetracycline antibiotic;triclosan
## 5: aminocoumarin antibiotic;aminoglycoside antibiotic;carbapenem;cephalosporin;cephamycin;fluoroquinolone antibiotic;glycylcycline;macrolide antibiotic;penam;penem;peptide antibiotic;phenicol antibiotic;rifamycin antibiotic;tetracycline antibiotic;triclosan
## 6: N/A
## AMR Gene Family
## 1: ATP-binding cassette (ABC) antibiotic efflux pump
## 2: major facilitator superfamily (MFS) antibiotic efflux pump
## 3: major facilitator superfamily (MFS) antibiotic efflux pump
## 4: resistance-nodulation-cell division (RND) antibiotic efflux pump
## 5: ATP-binding cassette (ABC) antibiotic efflux pump;major facilitator superfamily (MFS) antibiotic efflux pump;resistance-nodulation-cell division (RND) antibiotic efflux pump
## 6: major facilitator superfamily (MFS) antibiotic efflux pump
## Resistance Mechanism ARO Name
## 1: antibiotic efflux patA
## 2: antibiotic efflux emrA
## 3: antibiotic efflux emrB
## 4: antibiotic efflux acrB
## 5: antibiotic efflux TolC
## 6: antibiotic efflux emrDThis takes the directory the WIMP CSV files are in and creates a count matrix that can be used in downstream analysis. The inputs are similar to those in the previous examples (but metadata is not required):
path.to.wimp.files required: the path to the raw CSV files (for example "Desktop/raw_data/")example.wimp.dir <- system.file("extdata", "example_wimp_data", package = "epi2me2r")
wimp.count.table <- read_in_wimp_files(path.to.wimp.files = example.wimp.dir)## Reading in raw WIMP files from C:/Users/qdread/AppData/Local/Temp/RtmpSCYKke/Rinst14fc4d0559bb/epi2me2r/extdata/example_wimp_data## The percentage of classified reads was 94.4head(wimp.count.table)## taxID 324212_1777_barcode02 324212_1777_barcode03 324212_1777_barcode04
## 1: 0 9 6 6
## 2: 286 3 0 0
## 3: 287 8 9 11
## 4: 543 2 1 2
## 5: 544 0 0 1
## 6: 561 0 0 0
## 324212_1778_NA
## 1: 7
## 2: 1
## 3: 16
## 4: 0
## 5: 0
## 6: 1This function assigns phylogenetic taxonomic hierarchical information with the help of taxonomizr. A count table with NCBI taxonomic ID’s ("taxID") as the first column is required.
wimp.count.table required: data frame generated with wimp.count.table or that has "taxID" as the first column for phylogenetic taxonomic assignmentwimp.taxonomy <- generate_wimp_taxonomy(wimp.count.table = wimp.count.table)Another useful function is amr_read_taxonomy, which matches any classified AMR read with the phylogenetic taxonomy (if it is assigned) using read_id(). This function takes the following arguments:
path.to.amr.files required: the path to the raw AMR CSV files (for example "Desktop/raw_amr_data/")path.to.wimp.files required: the path to the raw WIMP CSV files (for example "Desktop/raw_wimp_data/")coveragenumber optional : the total length of the gene that must be present for it to be included in the count table. The default is 80%; this argument takes any number from 1 to 99. Default is 80.amr.read.classification <- amr_read_taxonomy(path.to.amr.files = example.amr.dir,
path.to.wimp.files = example.wimp.dir)