epi2me2r vignette"

In epi2me2r: Process Nanopore EPI2ME Output for Use in R

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:

• fully automated: these functions take minimal input (just raw CSV files and metadata) and produce either phyloseq or metagenomeSeq objects for downstream analysis:

  • amr_raw_to_phyloseq()
  • amr_raw_to_metagenomeseq()
  • wimp_raw_to_phyloseq()
  • wimp_raw_to_metagenomeseq()

• step-by-step: If you need output from an intermediate step, you can these functions to generate only what you need:

  • read_in_amr_files()
  • read_in_wimp_files()
  • generate_amr_taxonomy()
  • generate_wimp_taxonomy()

• other: An additional function we created but does not fit into the main workflows is amr_read_taxonomy(). This function reads in both AMR and WIMP raw data and adds the taxonomic information to the AMR gene if available.

Preparation of metadata file

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.

Combo metadata file

This file has 4 required columns that must be named as follows:

• arma_filename : the original amr file name without the .csv extension
• arma_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 none
• wimp_filename : the original amr file name without the .csv extension
• wimp_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 NA
• additional 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)

Individual metadata file

If 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).

Fully automated data import

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.

AMR data

amr_raw_to_phyloseq

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.frame
• 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.

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)

amr_raw_to_metagenomeseq

The 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)
mgs.amr.object

WIMP

wimp_raw_to_phyloseq

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.frame
• keep.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 reads
• keep.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)

wimp_raw_to_metagenomeseq

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)

Step-by-step import

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.

AMR data

read_in_amr_file

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)
head(amr.count.table)

generate_amr_taxonomy

This 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 assignment
• verbose 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)

WIMP data

read_in_wimp_file

This 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)
head(wimp.count.table)

generate_wimp_taxonomy

This 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 assignment

wimp.taxonomy <- generate_wimp_taxonomy(wimp.count.table = wimp.count.table)

Other functions

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)

epi2me2r documentation built on June 3, 2022, 9:07 a.m.