phyloseq: An R Package for Reproducible Interactive Analysis and Graphics of Microbiome Census Data

the analysis of microbial communities through dna sequencing brings many challenges: the integration of different types of data with methods from ecology, genetics, phylogenetics, multivariate statistics, visualization and testing. With the increased breadth of experimental designs now being pursued, project-specific statistical analyses are often needed, and these analyses are often difficult (or impossible) for peer researchers to independently reproduce. The vast majority of the requisite tools for performing these analyses reproducibly are already implemented in R and its extensions (packages), but with limited support for high throughput microbiome census data.Here we describe a software project, phyloseq, dedicated to the object-oriented representation and analysis of microbiome census data in R. It supports importing data from a variety of common formats, as well as many analysis techniques. These include calibration, filtering, subsetting, agglomeration, multi-table comparisons, diversity analysis, parallelized Fast UniFrac, ordination methods, and production of publication-quality graphics; all in a manner that is easy to document, share, and modify. We show how to apply functions from other R packages to phyloseq-represented data, illustrating the availability of a large number of open source analysis techniques. We discuss the use of phyloseq with tools for reproducible research, a practice common in other fields but still rare in the analysis of highly parallel microbiome census data. We have made available all of the materials necessary to completely reproduce the analysis and figures included in this article, an example of best practices for reproducible research.The phyloseq project for R is a new open-source software package, freely available on the web from both GitHub and Bioconductor.

section_content: Handling and analysis of high-throughput phylogenetic sequence data.
section_name: phyloseq-package

section_content: There are already several ecology and phylogenetic packages available in R, including the adephylo, vegan, ade4, picante, ape, phangorn, phylobase, and OTUbase packages. These can already take advantage of many of the powerful statistical and graphics tools available in R. However, prior to phyloseq a user must devise their own methods for parsing the output of their favorite OTU clustering application, and, as a consequence, there is also no standard within Bioconductor (or R generally) for storing or sharing the suite of related data objects that describe a phylogenetic sequencing project. The phyloseq package seeks to address these issues by providing a related set of S4 classes that internally manage the handling tasks associated with organizing, linking, storing, and analyzing phylogenetic sequencing data. phyloseq additionally provides some convenience wrappers for input from common clustering applications, common analysis pipelines, and native implementation of methods that are not available in other R packages.
section_name: Description

section_content: This function is used internally by many accessors and in many functions/methods that need to access a particular type of component data. If something is wrong, or the slot is missing, the expected behavior is that this function will return NULL. Thus, the output can be tested by is. null as verification of the presence of a particular data component. Unlike the component-specific accessors (e. g. otu_table, or phy_tree), the default behavior is not to stop with an error if the desired slot is empty. In all cases this is controlled by the errorIfNULL argument, which can be set to TRUE if an error is desired.
section_name: Description

section_content: Returns the component object specified by the argument slot. Returns NULL if slot does not exist. 

Returns physeq as-is if it is a component class that already matches the slot name. 

See Also
section_name: Value

section_content: Examples # ## data(GlobalPatterns) ## access(GlobalPatterns, "tax_table") ## access(GlobalPatterns, "phy_tree") ## access(otu_table(GlobalPatterns), "otu_table") ## # Should return NULL: ## access(otu_table(GlobalPatterns), "sample_data") ## access(otuTree(GlobalPatterns), "sample_data") ## access(otuSam(GlobalPatterns), "phy_tree") build_tax_table Build a tax_table from a named possibly-jagged list
section_name: getslots.phyloseq, merge_phyloseq

section_content: Build a tax_table from a named possibly-jagged list Usage build_tax_table(taxlist)

Arguments taxlist (Required). A list in which each element is a vector of taxonomic assignments named by rank. Every element of every vector must be named by the rank it represents. Every element of the list (every vector) should correspond to a single OTU and be named for that OTU.
section_name: Description

section_content: A tax_table (taxonomyTable-class) that has been built from taxlist. The OTU names of this output will be the element names of taxlist, and a separate taxonomic rank (column) will be included for each unique rank found among the element names of each vector in the list. 

NA_character_ is the default value of elements in the tax_table for which there is no corresponding information in taxlist.
section_name: Value

section_content: Examples taxvec1 = c("Root", "k__Bacteria", "p__Firmicutes", "c__Bacilli", "o__Bacillales", "f__Staphylococcaceae") parse_taxonomy_default(taxvec1) parse_taxonomy_greengenes(taxvec1) taxvec2 = c("Root;k__Bacteria;p__Firmicutes;c__Bacilli;o__Bacillales;f__Staphylococcaceae") parse_taxonomy_qiime(taxvec2) taxlist1 = list(OTU1=parse_taxonomy_greengenes(taxvec1), OTU2=parse_taxonomy_qiime(taxvec2)) taxlist2 = list(OTU1=parse_taxonomy_default(taxvec1), OTU2=parse_taxonomy_qiime(taxvec2)) build_tax_table(taxlist1) build_tax_table(taxlist2) capscale. phyloseq Constrained Analysis of Principal Coordinates, capscale.
section_name: See Also import_biom import_qiime

section_content: See capscale for details. A formula is main input.
section_name: Description

section_content: capscale. phyloseq(physeq, formula, distance,. . . )

## S4 method for signature 'phyloseq,formula,dist' capscale. phyloseq(physeq, formula, distance,. . . ) ## S4 method for signature 'phyloseq,formula,character' capscale. phyloseq(physeq, formula, distance,. . . )

Arguments physeq (Required). Phylogenetic sequencing data (phyloseq-class). The data on which you want to perform the ordination. 

cca. phyloseq formula (Required). A formula, specifying the input. No need to directly access components. capscale. phyloseq understands where to find the abundance table (LHS) and sample_data (RHS) from within the phyloseq object. 

distance (Required). A character string, specifying the name of the dissimilarity (or distance) method supported by the phyloseq distance function. Alternatively, a pre-computed dist-object can be provided here, in which case it supersedes any use of the otu_table in your phyloseq object. Note that capscale with Euclidean distances will be identical to rda in eigenvalues and in site, species, and biplot scores (except for possible sign reversal). However, it makes no sense to use capscale with Euclidean distances, since direct use of rda is much more efficient (and supported in the ordinate function with method=="RDA") Even with non-Euclidean dissimilarities, the rest of the analysis will be metric and linear. 

. . . (Optional). Additional named arguments passed to capscale.
section_name: Usage

section_content: Ordination object defined by capscale. 

See Also GP = prune_taxa(names(sort(taxa_sums(GlobalPatterns), TRUE)[1:50]), GlobalPatterns) ordcap = ordinate(GP, "CAP", "bray", ~SampleType) plot_ordination(GP, ordcap, "samples", color="SampleType") cca. phyloseq Constrained Correspondence Analysis and Redundancy Analysis.
section_name: Value

section_content: This is the internal function that simplifies getting phyloseq data into the constrained ordination functions, cca and rda. Unlike capscale. phyloseq, the formula argument to these methods is optional, and results in an unconstrained ordination. 

Usage cca. phyloseq(physeq, formula = NULL, method = "CCA",. . . ) ## S4 method for signature 'phyloseq,formula' cca. phyloseq(physeq, formula = NULL, method = "CCA",. . . )

## S4 method for signature 'otu_table,ANY' cca. phyloseq(physeq, formula = NULL, method = "CCA",. . . )

## S4 method for signature 'phyloseq,`NULL`' cca. phyloseq(physeq, formula = NULL, method = "CCA",. . . )

Arguments physeq (Required). Phylogenetic sequencing data (phyloseq-class). The data on which you want to perform the ordination. 

formula (Optional). A formula, specifying the contraining variable(s) format, with variable names corresponding to sample_data (RHS) from within physeq. method (Optional). A single character string, specifying "RDA" or "CCA". Default is "CCA". 

. . . (Optional). Additional named arguments passed to capscale. 

Value same output as cca or rda, respectively. 

See Also
section_name: Description

section_content: Examples # # cca. phyloseq(physeq, formula, method,. . . ) chunkReOrder Chunk re-order a vector so that specified newstart is first.
section_name: plot_ordination, rda, cca

section_content: Different than relevel.
section_name: Description

section_name: data-enterotype

section_content: Examples # Typical use-case # chunkReOrder(1:10, 5) # # Default is to not modify the vector # chunkReOrder(1:10) # # Another example not starting at 1 # chunkReOrder(10:25, 22) # # Should silently ignore the second element of `newstart# chunkReOrder (10:25, c(22, 11) ) # # Should be able to handle `newstart`being the first argument already # # without duplicating the first element at the end of `x# chunkReOrder(10:25, 10) # all(chunkReOrder(10:25, 10) == 10:25) # # This is also the default # all(chunkReOrder(10:25) == 10:25) # # An example with characters # chunkReOrder(LETTERS, "G") # chunkReOrder(LETTERS, "B") # chunkReOrder(LETTERS, "Z") # # What about when `newstart`is not in `x`? Return x as-is, throw warning. # chunkReOrder(LETTERS, "g") data-enterotype (Data) Enterotypes of the human gut microbiome (2011)
section_name: Usage chunkReOrder(x, newstart = x[[1]])

section_content: Published in Nature in early 2011, this work compared (among other things), the faecal microbial communities from 22 subjects using complete shotgun DNA sequencing. Authors further compared these microbial communities with the faecal communities of subjects from other studies. A total of 280 faecal samples / subjects are represented in this dataset, and 553 genera. The authors claim that the data naturally clumps into three community-level clusters, or "enterotypes", that are not immediately explained by sequencing technology or demographic features of the subjects, but with potential relevance to understanding human gut microbiota.
section_name: Description

section_content: abstract from research article (quoted):

Our knowledge of species and functional composition of the human gut microbiome is rapidly increasing, but it is still based on very few cohorts and little is known about variation across the world. By combining 22 newly sequenced faecal metagenomes of individuals from four countries with previously published data sets, here we identify three robust clusters (referred to as enterotypes hereafter) that are not nation or continent specific. We also confirmed the enterotypes in two published, larger cohorts, indicating that intestinal microbiota variation is generally stratified, not continuous. 

This indicates further the existence of a limited number of well-balanced host-microbial symbiotic states that might respond differently to diet and drug intake. The enterotypes are mostly driven by species composition, but abundant molecular functions are not necessarily provided by abundant species, highlighting the importance of a functional analysis to understand microbial communities. 

Although individual host properties such as body mass index, age, or gender cannot explain the observed enterotypes, data-driven marker genes or functional modules can be identified for each of these host properties. For example, twelve genes significantly correlate with age and three functional modules with the body mass index, hinting at a diagnostic potential of microbial markers. 

(end quote)

Author(s)

Arumugam, M., Raes, J., et al.
section_name: Details

section_content: Arumugam, M., et al. (2011). Enterotypes of the human gut microbiome. 

Nature, 473(7346), 174-180. 

http://www. nature. com/doifinder/10. 1038/nature09944 See supplemental information for subject data. 

OTU-clustered data was downloaded from the publicly-accessible:

http://www. bork. embl. de/Docu/Arumugam_et_al_2011/downloads. html

Examples data(enterotype) ig <-make_network(enterotype, "samples", max. dist=0. 3) plot_network (ig, enterotype, color="SeqTech", shape="Enterotype", line_weight=0. 3, label=NULL) data-esophagus (Data) Small example dataset from a human esophageal community (2004)
section_name: References

section_content: Includes just 3 samples, 1 each from 3 subjects. Although the research article mentions 4 subjects, only 3 are included in this dataset.
section_name: Description

section_content: abstract from research article (quoted):

The esophagus, like other luminal organs of the digestive system, provides a potential environment for bacterial colonization, but little is known about the presence of a bacterial biota or its nature. By using broad-range 16S rDNA PCR, biopsies were examined from the normal esophagus of four human adults. The 900 PCR products cloned represented 833 unique sequences belonging to 41 genera, or 95 species-level operational taxonomic units (SLOTU); 59 SLOTU were homologous data-GlobalPatterns with culture-defined bacterial species, 34 with 16S rDNA clones, and two were not homologous with any known bacterial 16S rDNA. Members of six phyla, Firmicutes, Bacteroides, Actinobacteria, Proteobacteria, Fusobacteria, and TM7, were represented. A large majority of clones belong to 13 of the 41 genera (783/900, 87%), or 14 SLOTU (574/900, 64%) that were shared by all four persons. Streptococcus (39%), Prevotella (17%), and Veilonella (14%) were most prevalent. The present study identified 56-79% of SLOTU in this bacterial ecosystem. Most SLOTU of esophageal biota are similar or identical to residents of the upstream oral biota, but the major distinction is that a large majority (82%) of the esophageal bacteria are known and cultivable. These findings provide evidence for a complex but conserved bacterial population in the normal distal esophagus. 

(end quote)

A description of the 16S rRNA sequence processing can be found on the mothur-wiki at the link below. A cutoff of 0. 10 was used for OTU clustering in that example, and it is taken here as well to create example data, esophagus, which was easily imported with the import_mothur() function.
section_name: Details

section_content: Pei et al. <zhiheng. pei@med. nyu. edu>
section_name: Author(s)

section_content: Pei, Z., Bini, E. J., Yang, L., Zhou, M., Francois, F., & Blaser, M. J. (2004). Bacterial biota in the human distal esophagus. Proceedings of the National Academy of Sciences of the United States of America, 101(12), 4250-4255. http://www. ncbi. nlm. nih. gov/pmc/articles/PMC384727 mothur-processed files and the sequence data can be downloaded from a zip-file, along with additional description, from the following URL: http://www. mothur. org/wiki/Esophageal_community_ analysis Examples data(esophagus) UniFrac(esophagus, weighted=TRUE) # How to re-create the esophagus dataset using import_mothur function mothlist <-system. file("extdata", "esophagus. fn. list. gz", package="phyloseq") mothgroup <-system. file("extdata", "esophagus. good. groups. gz", package="phyloseq") mothtree <-system. file("extdata", "esophagus. tree. gz", package="phyloseq") show_mothur_cutoffs(mothlist) cutoff <-"0. 10" esophman <-import_mothur (mothlist, mothgroup, mothtree, cutoff) data-GlobalPatterns (Data) Global patterns of 16S rRNA diversity at a depth of millions of sequences per sample (2011)
section_name: References

section_content: Published in PNAS in early 2011. This work compared the microbial communities from 25 environmental samples and three known "mock communities" -a total of 9 sample types -at a depth averaging 3. 1 million reads per sample. Authors were able to reproduce diversity patterns seen in many other published studies, while also invesitigating technical issues/bias by applying the same techniques to simulated microbial communities of known composition.
section_name: Description

section_content: abstract from research article (quoted):

The ongoing revolution in high-throughput sequencing continues to democratize the ability of small groups of investigators to map the microbial component of the biosphere. In particular, the coevolution of new sequencing platforms and new software tools allows data acquisition and analysis on an unprecedented scale. Here we report the next stage in this coevolutionary arms race, using the Illumina GAIIx platform to sequence a diverse array of 25 environmental samples and three known "mock communities" at a depth averaging 3. 1 million reads per sample. We demonstrate excellent consistency in taxonomic recovery and recapture diversity patterns that were previously reported on the basis of metaanalysis of many studies from the literature (notably, the saline/nonsaline split in environmental samples and the split between host-associated and free-living communities). We also demonstrate that 2,000 Illumina single-end reads are sufficient to recapture the same relationships among samples that we observe with the full dataset. The results thus open up the possibility of conducting large-scale studies analyzing thousands of samples simultaneously to survey microbial communities at an unprecedented spatial and temporal resolution. 

(end quote)

Many thanks to J. Gregory Caporaso for directly providing the OTU-clustered data files for inclusion in this package. 

Author(s) This data was imported from raw files supplied directly by the authors via personal communication for the purposes of including as an example in the phyloseq-package. As this data is sensitive to choices in OTU-clustering parameters, attempts to recreate the otu_table from the raw sequencing data may give slightly different results than the table provided here. 

abstract from research article (quoted):

To determine the reproducibility and quantitation of the amplicon sequencing-based detection approach for analyzing microbial community structure, a total of 24 microbial communities from a long-term global change experimental site were examined. Genomic DNA obtained from each community was used to amplify 16S rRNA genes with two or three barcode tags as technical replicates in the presence of a small quantity (0. 1% wt/wt) of genomic DNA from Shewanella oneidensis MR-1 as the control. The technical reproducibility of the amplicon sequencing-based detection approach is quite low, with an average operational taxonomic unit (OTU) overlap of 17. 2%+/-2. 3% between two technical replicates, and 8. 2%+/-2. 3% among three technical replicates, which is most likely due to problems associated with random sampling processes. Such variations in technical replicates could have substantial effects on estimating beta-diversity but less on alpha-diversity. A high variation was also observed in the control across different samples (for example, 66. 7-fold for the forward primer), suggesting that the amplicon sequencing-based detection approach could not be quantitative. In addition, various strategies were examined to improve the comparability of amplicon sequencing data, such as increasing biological replicates, and removing singleton sequences and less-representative OTUs across biological replicates. Finally, as expected, various statistical analyses with preprocessed experimental data revealed clear differences in the composition and structure of microbial communities between warming and non-warming, or between clipping and non-clipping. Taken together, these results suggest that amplicon sequencing-based detection is useful in analyzing microbial community structure even though it is not reproducible and quantitative. However, great caution should be taken in experimental design and data interpretation when the amplicon sequencing-based detection approach is used for quantitative analysis of the beta-diversity of microbial communities. 

(end quote)

Author(s)

# Graphically compare richness between the different treatments. man. col <-c(WC="red", WU="brown", UC="blue", UU="darkgreen") plot_richness(soilrep, x="Treatment", color="Treatment", measures=c("Observed", "Chao1", "Shannon")) decorana S3 class placeholder definition (list) for decorana
section_name: Details

section_content: The ape package does export a version of its decorana-class, partly because it is not really defined formally anywhere. Instead, it is an S3 class extended from the base class, list -this is a very common and easy approach -and proper behavior of any method taking an instance of this class requires exact naming conventions for element names of the list components. The phyloseq package does not provide any validity checks that a given phylo instance is valid (conforms to the conventions in the ape package). . . yet. If problems arise, this might be considered, and they could be defined judiciously and within phyloseq.
section_name: Description

section_name: Usage decorana

section_content: An object of class decorana of length 0. 

See Also decorana distance dist-class An S4 placeholder for the dist class.
section_name: Format

section_content: See dist for details about this type of a distance matrix object.
section_name: Description

section_content: dist, setOldClass distance
section_name: See Also

section_name: Calculate distance, dissimilarity

section_content: Takes a phyloseq-class object and method option, and returns a distance object suitable for certain ordination methods and other distance-based analyses. Only sample-wise distances are currently supported (the type argument), but eventually species-wise (OTU-wise) distances may be supported as well.
section_name: Description

section_content: distance(physeq, method, type = "samples",. . . )

## S4 method for signature 'phyloseq,ANY' distance(physeq, method) ## S4 method for signature 'otu_table,character' distance(physeq, method, type = "samples",. . . ) ## S4 method for signature 'phyloseq,character' distance(physeq, method, type = "samples",. . . )

Arguments physeq (Required). A phyloseq-class or an otu_table-class object. The latter is only appropriate for methods that do not require any additional data (one-table). 

For example, the "wunifrac" option (UniFrac) requires phyloseq-class that contains both an otu_table and a phylogenetic tree (phylo). method (Required). A character string. Provide one of the currently supported options. See distanceMethodList for a detailed list of the supported options here, and links to accompanying documentation. Note that for the common definition of Jaccard distance using the vegan-package implementation, an additional argument is needed, with the full call having the form: distance(physeq, method = "jaccard", binary = TRUE)

The following methods are implemented explicitly within the phyloseq-package, and accessed by the following method options:

"unifrac" Original (unweighted) UniFrac distance, UniFrac "wunifrac" weighted-UniFrac distance, UniFrac "dpcoa" sample-wise distance used in Double Principle Coordinate Analysis, DPCoA "jsd" Jensen-Shannon Divergence, JSD Alternatively, you can provide a character string that defines a custom distance method, if it has the form described in designdist.
section_name: Usage

section_content: (Optional). A character string. The type of pairwise comparisons being calculated: sample-wise or taxa-wise. The default is c("samples"). 

. . . Additional arguments passed on to the appropriate distance function, determined by the method argument.
section_name: type

section_content: Depending on the method argument, distance() wraps one of UniFrac, DPCoA, JSD, vegdist, betadiver, designdist, or dist.
section_name: Details

section_content: An object of class "dist" suitable for certain ordination methods and other distance-based analyses. 

See Also plot_ordination, UniFrac, DPCoA, JSD, vegdist, betadiver, designdist, dist. 

Examples data(esophagus) distance(esophagus, "uunifrac") # Unweighted UniFrac distance(esophagus, "wunifrac") # weighted UniFrac distance(esophagus, "jaccard", binary = TRUE) # vegdist jaccard distance(esophagus, "gower") # vegdist option "gower" distance(esophagus, "g") # designdist method option "g" distance(esophagus, "minkowski") # invokes a method from the base dist() function. distance(esophagus, "(A+B-2*J)/(A+B)") # designdist custom distance distanceMethodList help("distance") distanceMethodList List of distance method keys supported in distance
section_name: Value

section_content: Distance methods should be specified by exact string match. Cannot do partial matching for all options, because too many similar options in downstream method dispatch. scannf (Optional). Logical. Default is FALSE. This is passed directly to dpcoa, and causes a barplot of eigenvalues to be created if TRUE. This is not included in. . . because the default for dpcoa is TRUE, although in many expected situations we would want to suppress creating the barplot. 

. . . Additional arguments passed to dpcoa.
section_name: Description

section_content: A dpcoa-class object (see dpcoa).
section_name: Value

section_content: Julia Fukuyama <julia. fukuyama@gmail. com>. Adapted for phyloseq by Paul J. McMurdie.
section_name: Author(s)

section_name: See Also dpcoa

section_content: # # # # # # Esophagus data(esophagus) eso. dpcoa <-DPCoA(esophagus) eso. dpcoa plot_ordination(esophagus, eso. dpcoa, "samples") plot_ordination(esophagus, eso. dpcoa, "species") plot_ordination(esophagus, eso. dpcoa, "biplot") # # # # # # # # GlobalPatterns data(GlobalPatterns) # subset GP to top-150 taxa (to save computation time in example) keepTaxa <-names(sort(taxa_sums(GlobalPatterns), TRUE)[1:150]) GP <-prune_taxa(keepTaxa, GlobalPatterns) # Perform DPCoA GP. dpcoa <-DPCoA(GP) plot_ordination(GP, GP. dpcoa, color="SampleType") envHash2otu_table

Convert a sequence-sample hash (like ENV file) into an OTU table.
section_name: Examples

section_content: Parses an ENV-file into a sparse matrix of species-by-sample, where each species-row has only one non-zero value. We call this sparse abundance measures (Optional). Default is NULL, meaning that all available alpha-diversity measures will be included. Alternatively, you can specify one or more measures as a character vector of measure names. Values must be among those supported: c("Observed", "Chao1", "ACE", "Shannon", "Simpson", "InvSimpson", "Fisher").
section_name: Description

section_content: A data. frame of the richness estimates, and their standard error.
section_name: Value

section_content: Check out the custom plotting function, plot_richness, for easily showing the results of different estimates, with method-specific error-bars. Also check out the internal functions borrowed from the vegan package:
section_name: See Also

section_content: The purpose of this function is to allow a user to easily export a distance object as a pair of files that can be immediately imported by mothur for OTU clustering and related analysis. A distance object can be created in R in a number of ways, including via cataloguing the cophentic distances of a tree object. 

Usage export_mothur_dist(x, out=NULL, makeTrivialNamesFile=NULL)
section_name: Description

section_content: x (Required). A "dist" object, or a symmetric matrix. out (Optional). The desired output filename for the. dist file, OR left NULL, the default, in which case the mothur-formated distance table is returned to R standard out. makeTrivialNamesFile (Optional). Default NULL. The desired name of the. names file. If left NULL, the file name will be a modified version of the out argument.
section_name: Arguments

section_content: A character vector of the different cutoff values contained in the file. For a given set of arguments to the cluster() command from within mothur, a number of OTU-clustering results are returned in the same list file. The exact cutoff values used by mothur can vary depending on the input data. This simple function returns the cutoffs that were actually included in the mothur output. This an important extra step prior to importing the OTUs with the import_mothur_otulist() function.
section_name: Value

section_content: # data(esophagus) myDistObject <-as. dist(ape::cophenetic. phylo(phy_tree(esophagus))) export_mothur_dist(myDistObject) filterfun_sample A sample-wise filter function builder analogous to filterfun.
section_name: Examples

section_content: See the filterfun, from the Bioconductor repository, for a taxa-/gene-wise filter (and further examples). 

Usage filterfun_sample(. . . )
section_name: Description

section_content: . . . A comma-separated list of functions.
section_name: Arguments

section_content: An enclosure (function) that itself will return a logical vector, according to the functions provided in the argument list, evaluated in order. The output of filterfun_sample is appropriate for the 'flist' argument to the genefilter_sample method. genefilter_sample Filter OTUs with arbitrary function, sample-wise.
section_name: Value

section_content: A general OTU trimming function for selecting OTUs that satisfy some criteria within the distribution of each sample, and then also an additional criteria for number of samples that must pass. This is a genefilter-like function that only considers sample-wise criteria. The number of acceptable samples is used as the final criteria (set by the argument A) to determine whether or not the taxa should be retained (TRUE) or not (FALSE). Just like with genefilter, a logical having length equal to nrow()/ntaxa is returned, indicating which should be kept. This output can be provided directly to OTU trimming function, prune_taxa. By contrast, genefilter, of the genefilter package in Bioconductor, works only on the rows of a matrix. Note that, because otu_table-class inherits directly from the matrix-class, an unmodified otu_table can be provided to genefilter, but be mindful of the orientation of the otu_table (use taxa_are_rows), and transpose (t) if needed. 

Usage genefilter_sample(X, flist, A=1) ## S4 method for signature 'matrix' genefilter_sample(X, flist, A = 1) ## S4 method for signature 'otu_table' genefilter_sample(X, flist, A = 1) ## S4 method for signature 'phyloseq' genefilter_sample(X, flist, A = 1)
section_name: Description

section_name: Arguments

section_content: The object that needs trimming. Can be matrix, otu_table, or higher-order phyloseq classes that contain an otu_table. 

flist An enclosure object, typically created with filterfun_sample A An integer. The number of samples in which a taxa / OTUs passed the filter for it to be labeled TRUE in the output logical vector.
section_name: X

section_content: A logical vector with names equal to taxa_names (or rownames, if matrix). 

See Also import Universal import method (wrapper) for phyloseq-package
section_name: Value

section_content: A user must still understand the additional arguments required for each type of import data. Those arguments are described in detail at the tool-specific import_* links below. Each clustering tool / package / pipeline has its own idiosyncratic set of file names / types, and it remains the responsibility of the user to understand which file-path should be provided to each argument for the particular importing submethod. This method merely provides a central documentation and method-name, and the arguments are passed along as-is. 

Usage import(pipelineName,. . . )

Arguments pipelineName (Required). Character string. The name of the analysis tool / pipeline / package that created the OTU-cluster data or other data that you now want to import. Current options are c("mothur", "pyrotagger", "QIIME", "RDP"), and only the first letter is necessary. 

. . . (Required). Additional named arguments providing file paths, and possible other paramaters to the desired tool-specific import function.
section_name: Description

section_content: In most cases a phyloseq-class will be returned, though the included component data will vary by pipeline/tool, and also by the types of data files provided. The expected behavior is to return the most-comprehensive object possible, given the provided arguments and pipeline/tool. A file representing a phylogenetic tree or a phylo object. Files can be NEXUS or Newick format. See read_tree for more details. Also, if using a recent release of the GreenGenes database tree, try the read_tree_greengenes function -this should solve some issues specific to importing that tree. If provided, the tree should have the same OTUs/tip-labels as the OTUs in the other files. Any taxa or samples missing in one of the files is removed from all. As an example from the QIIME pipeline, this tree would be a tree of the representative 16S rRNA sequences from each OTU cluster, with the number of leaves/tips equal to the number of taxa/species/OTUs, or the complete reference database tree that contains the OTU identifiers of every OTU in your abundance table. Note that this argument can be a tree object (phylo-class) for cases where the tree has been -or needs to be -imported separately, as in the case of the GreenGenes tree mentioned earlier (coderead_tree_greengenes). parseFunction (Optional). A function. It must be a function that takes as its first argument a character vector of taxonomic rank labels for a single OTU and parses and names each element (an optionally removes unwanted elements). Further details and examples of acceptable functions are provided in the documentation for parse_taxonomy_default. There are many variations on taxonomic nomenclature, and naming conventions used to store that information in various taxonomic databases and phylogenetic assignment algorithms. A popular database, http://greengenes. lbl. gov/cgi-bin/nph-index. cgigreengenes, has its own custom parsing function provided in the phyloseq package, parse_taxonomy_greengenes, and more can be contributed or posted as code snippets as needed. They can be custom-defined by a user immediately prior to the the call to import_biom, and this is a suggested first step to take when trouble-shooting taxonomy-related errors during file import. parallel (Optional). Logical. Wrapper option for. parallel parameter in plyr-package functions. If TRUE, apply parsing functions in parallel, using parallel backend provided by foreach and its supporting backend packages. One caveat, plyr-parallelization currently works most-cleanly with multicore-like backends (Mac OS X, Unix?), and may throw warnings for SNOW-like backends.
section_name: Value

section_content: See the example below for code invoking multicore-style backend within the doParallel package. 

Finally, for many datasets a parallel import should not be necessary because a serial import will be just as fast and the import is often only performed one time; after which the data should be saved as an RData file using the save function. The file probably has extension ". tree". cutoff (Optional). A character string indicating the cutoff value, (or "unique"), that matches one of the cutoff-values used to produce the OTU clustering results contained within the list-file created by mothur (and specified by the mothur_list_file argument). The default is to take the largest value among the cutoff values contained in the list file. If only one cutoff is included in the file, it is taken and this argument does not need to be specified. Note that the cluster() function within the mothur package will often produce a list file with multiple cutoff values, even if a specific cutoff is specified. It is suggested that you check which cutoff values are available in a given list file using the show_mothur_cutoffs function. mothur_shared_file (Optional). A shared file produced by mothur. mothur_constaxonomy_file (Optional). A consensus taxonomy file produced by mothur. 

parseFunction (Optional). A specific function used for parsing the taxonomy string. See parse_taxonomy_default for an example. If the default is used, this function expects a semi-colon delimited taxonomy string, with no additional rank specifier. A common taxonomic database is GreenGenes, and in recent versions its taxonomy entries include a prefix, which is best cleaved and used to precisely label the ranks (parse_taxonomy_greengenes).
section_name: References

section_content: The object class depends on the provided arguments. A phyloseq object is returned if enough data types are provided. If only one data component can be created from the data, it is returned. 

FASTER (recommended for larger data sizes):

If only a mothur_constaxonomy_file is provided, then a taxonomyTable-class object is returned. 

If only a mothur_shared_file is provided, then an otu_table object is returned. 

SLOWER (but fine for small file sizes):

The list and group file formats are extremely inefficient for large datasets, and they are not recommended. The mothur software provides tools for converting to other file formats, such as a so-called "shared" file. You should provide a shared file, or group/list files, but not both at the same time. If only a list and group file are provided, then an otu_table object is returned. Similarly, if only a list and tree file are provided, then only a tree is returned (phylo-class). parseFunction (Optional). A specific function used for parsing the taxonomy string. See parse_taxonomy_default for an example. If the default is used, this function expects a semi-colon delimited taxonomy string, with no additional rank specifier. A common taxonomic database is GreenGenes, and for recent versions its taxonomy includes a prefix, which is best cleaved and used to precisely label the ranks (parse_taxonomy_greengenes).
section_name: Value

section_name: References

section_content: An taxonomyTable-class object. 

See Also import_mothur tax_table phyloseq import_mothur_dist Import mothur-formatted distance file
section_name: Value

section_content: The mothur application will produce a file containing the pairwise distances between all sequences in a dataset. This distance matrix can be the basis for OTU cluster designations. R also has many built-in or off-the-shelf tools for dealing with distance matrices. 

Usage import_mothur_dist(mothur_dist_file)
section_name: Description

section_content: Required. The distance file name / location produced by mothur.
section_name: Arguments mothur_dist_file

section_content: A distance matrix object describing all sequences in a dataset.
section_name: Value

section_name: See Also import_mothur

section_content: # # Take a look at the dataset shown here as an example: # # "http://www. mothur. org/wiki/Esophageal_community_analysis" # # find the file ending with extension ". dist", download to your system # # The location of your file may vary # mothur_dist_file <-"~/Downloads/mothur/Esophagus/esophagus. dist" # myNewDistObject <-import_mothur_dist(mothur_dist_file)

import_mothur_groups Parse mothur group file into a simple hash table.
section_name: Examples

section_content: The data. frame object returned by this function is not immediately useable by other phyloseq functions, and must be first parsed in conjunction with a separate mothur "list" file. This function is made accessible to phyloseq users for troubleshooting and inspection, but the link{import_mothur()} function is suggested if the goal is to import the OTU clustering results from mothur into phyloseq. 

You will need both a group file and a list file for that end. 

import_mothur_otulist Usage
section_name: Description

section_content: Arguments mothur_group_file A character string indicating the location of the mothur-produced group file in which the sample-source of each sequence is recorded. See http://www. mothur. org/wiki/Make. group
section_name: import_mothur_groups(mothur_group_file)

section_content: A data. frame that is effectively a hash table between sequence names and their sample source. 

See Also import_mothur import_mothur_otulist Import mothur list file and return as list object in R.
section_name: Value

section_content: This is a user-available module of a more comprehensive function for importing OTU clustering/abundance data using the mothur package. The list object returned by this function is not immediately useable by other phyloseq functions, and must be first parsed in conjunction with a separate mothur "group" file. This function is made accessible to phyloseq users for troubleshooting and inspection, but the link{import_mothur()} function is suggested if the goal is to import the OTU clustering results from mothur into phyloseq. 

Usage import_mothur_otulist(mothur_list_file, cutoff=NULL)
section_name: Description

section_content: The list file name and/or location as produced by mothur.
section_name: Arguments mothur_list_file

section_content: A character string indicating the cutoff value, (or "unique"), that matches one of the cutoff-values used to produce the OTU clustering results contained within the list-file created by mothur. The default is to take the largest value among the cutoff values contained in the list file. If only one cutoff is included in the file, it is taken and this argument does not need to be specified. Note that the cluster() function within the mothur package will often produce a list file with multiple cutoff values, even if a specific cutoff is specified. It is suggested that you check which cutoff values are available in a given list file using the show_mothur_cutoffs function.
section_name: cutoff

section_content: A list, where each element is a character vector of 1 or more sequence identifiers, indicating how each sequence from the original data is clustered into OTUs by mothur. Note that in some cases this is highly dependent on the choice for cutoff.
section_name: Value

section_content: show_mothur_cutoffs, import_mothur import_mothur_otu_table Import mothur list and group files and return an otu_table
section_name: See Also

section_content: Import mothur list and group files and return an otu_table Usage import_mothur_otu_table(mothur_list_file, mothur_group_file, cutoff=NULL)
section_name: Description

section_content: The list file name and/or location as produced by mothur. mothur_group_file

The name/location of the group file produced by mothur's make. group() function. It contains information about the sample source of individual sequences, necessary for creating a species/taxa abundance table (otu_table). See http://www. mothur. org/wiki/ cutoff A character string indicating the cutoff value, (or "unique"), that matches one of the cutoff-values used to produce the OTU clustering results contained within the list-file created by mothur (and specified by the mothur_list_file argument). The default is to take the largest value among the cutoff values contained in the list file. If only one cutoff is included in the file, it is taken and this argument does not need to be specified. Note that the cluster() function within the mothur package will often produce a list file with multiple cutoff values, even if a specific cutoff is specified. It is suggested that you check which cutoff values are available in a given list file using the show_mothur_cutoffs function.
section_name: Arguments mothur_list_file

section_content: An otu_table object. 

See Also
section_name: Value

section_content: PyroTagger is a web-server that takes raw, barcoded 16S rRNA amplicon sequences and returns an excel spreadsheet (". xls") with both abundance and taxonomy data. It also includes some confidence information related to the taxonomic assignment.
section_name: Description

section_content: PyroTagger is created and maintained by the Joint Genome Institute at "http://pyrotagger. jgi-psf. org/"

The typical output form PyroTagger is a spreadsheet format ". xls", which poses additional import challenges. However, virtually all spreadsheet applications support the ". xls" format, and can further export this file in a tab-delimited format. It is recommended that you convert the xls-file without any modification (as tempting as it might be once you have loaded it) into a tab-delimited text file. Deselect any options to encapsulate fields in quotes, as extra quotes around each cell's contents might cause problems during file processing. These quotes will also inflate the file-size, so leave them out as much as possible, while also resisting any temptation to modify the xls-file "by hand". 

A highly-functional and free spreadsheet application can be obtained as part of the cross-platform OpenOffice suite. It works for the above required conversion. Go to "http://www. openoffice. org/". 

It is regrettable that this importer does not take the xls-file directly as input. However, because of the moving-target nature of spreadsheet file formats, there is limited support for direct import of these formats into R. Rather than add to the dependency requirements of emphphyloseq and the relative support of these xls-support packages, it seems more efficient to choose an arbitrary delimited text format, and focus on the data structure in the PyroTagger output. This will be easier to support in the long-run.
section_name: Details

section_content: An otuTax object containing both the otu_table and TaxonomyTable data components, parsed from the pyrotagger output. mapfilename (Optional). The QIIME map file is required for processing barcoded primers in QIIME as well as some of the post-clustering analysis. This is a required input file for running QIIME. Its strict formatting specification should be followed for correct parsing by this function. Default value is NULL. treefilename (Optional). Default value is NULL. A file representing a phylogenetic tree or a phylo object. Files can be NEXUS or Newick format. See read_tree for more details. Also, if using a recent release of the GreenGenes database tree, try the read_tree_greengenes function -this should solve some issues specific to importing that tree. If provided, the tree should have the same OTUs/tip-labels as the OTUs in the other files. Any taxa or samples missing in one of the files is removed from all. As an example from the QIIME pipeline, this tree would be a tree of the representative 16S rRNA sequences from each OTU cluster, with the number of leaves/tips equal to the number of taxa/species/OTUs, or the complete reference database tree that contains the OTU identifiers of every OTU in your abundance table. Note that this argument can be a tree object (phylo-class) for cases where the tree has been -or needs to be -imported separately, as in the case of the GreenGenes tree mentioned earlier (coderead_tree_greengenes). 

refseqfilename (Optional). Default NULL. The file path of the biological sequence file that contains at a minimum a sequence for each OTU in the dataset. Alternatively, you may provide an already-imported XStringSet object that satisfies this condition. In either case, the names of each OTU need to match exactly the taxa_names of the other components of your data. If this is not the case, for example if the data file is a FASTA format but contains additional information after the OTU name in each sequence header, then some additional parsing is necessary, which you can either perform separately before calling this function, or describe explicitly in a custom function provided in the (next) argument, refseqFunction. 

Note that the XStringSet class can represent any arbitrary sequence, including user-defined subclasses, but is most-often used to represent RNA, DNA, or amino acid sequences. The only constraint is that this special list of sequences has exactly one named element for each OTU in the dataset. 

refseqFunction (Optional). Default is readDNAStringSet, which expects to read a fasta-formatted DNA sequence file. If your reference sequences for each OTU are amino acid, RNA, or something else, then you will need to specify a different function here. This is the function used to read the file connection provided as the the previous argument, refseqfilename. This argument is ignored if refseqfilename is already a XStringSet class. 

refseqArgs (Optional). Default NULL. Additional arguments to refseqFunction. See XStringSet-io for details about additional arguments to the standard read functions in the Biostrings package. parseFunction (Optional). An optional custom function for parsing the character string that contains the taxonomic assignment of each OTU. The default parsing function is parse_taxonomy_qiime, specialized for splitting the ";"-delimited strings and also attempting to interpret greengenes prefixes, if any, as that is a common format of the taxonomy string produced by QIIME. verbose (Optional). A logical. Default is TRUE. Should progresss messages be catted to standard out?. . .
section_name: Value

section_name: Additional arguments passed to read_tree

section_content: Other related files include the mapping-file that typically stores sample covariates, converted naturally to the sample_data-class component data type in the phyloseq-package. QIIME may also produce a phylogenetic tree with a tip for each OTU, which can also be imported specified here or imported separately using read_tree. 

See "http://www. qiime. org/" for details on using QIIME. While there are many complex dependencies, QIIME can be downloaded as a pre-installed linux virtual machine that runs "off the shelf". 

The different files useful for import to phyloseq are not collocated in a typical run of the QIIME pipeline. See the main phyloseq vignette for an example of where ot find the relevant files in the output directory.
section_name: Details

section_content: A phyloseq-class object. Examples otufile <-system. file("extdata", "GP_otu_table_rand_short. txt. gz", package="phyloseq") mapfile <-system. file("extdata", "master_map. txt", package="phyloseq") trefile <-system. file("extdata", "GP_tree_rand_short. newick. gz", package="phyloseq") import_qiime(otufile, mapfile, trefile)
section_name: Value

section_content: import_qiime_otu_tax Import now legacy-format QIIME OTU table as a list of two matrices.
section_name: References

section_content: Now a legacy-format, older versions of QIIME produced an OTU file that typically contains both OTU-abundance and taxonomic identity information in a tab-delimted Only a few steps are actually parallelized, and for most datasets it will actually be faster and more efficient to keep this set to FALSE. Also, to get any benefit at all, you will need to register a parallel "backend" through one of the backend packages supported by the foreach-package.
section_name: Description

section_content: This function uses chunking to perform both the reading and parsing in blocks of optional size, thus constrain the peak memory usage. feature should make this importer accessible to machines with modest memory, but with the caveat that the full numeric matrix must be a manageable size at the end, too. In principle, the final tables will be large, but much more efficiently represented than the character-stored numbers. If total memory for storing the numeric matrix becomes problematic, a switch to a sparse matrix representation of the abundance -which is typically well-suited to this data -might provide a solution.
section_name: Details

section_content: A list of two matrices. $otutab contains the OTU
section_name: Value

section_content: The RDP cluster pipeline (specifically, the output of the complete linkage clustering step) has no formal documentation for the ". clust" file or its apparent sequence naming convention.
section_name: Description

section_name: Usage import_RDP_cluster(RDP_cluster_file)

section_content: RDP_cluster_file A character string. The name of the ". clust" file produced by the the complete linkage clustering step of the RDP pipeline.
section_name: Arguments

section_content: http://pyro. cme. msu. edu/index. jsp

The cluster file itself contains the names of all sequences contained in input alignment. If the upstream barcode and aligment processing steps are also done with the RDP pipeline, then the sequence names follow a predictable naming convention wherein each sequence is named by its sample and sequence ID, separated by a "_" as delimiter:

"sampleName_sequenceIDnumber"

This import function assumes that the sequence names in the cluster file follow this convention, and that the sample name does not contain any "_". It is unlikely to work if this is not the case. It is likely to work if you used the upstream steps in the RDP pipeline to process your raw (barcoded, untrimmed) fasta/fastq data. 

This function first loops through the ". clust" file and collects all of the sample names that appear. It secondly loops through each OTU ("cluster"; each row of the cluster file) and sums the number of sequences (reads) from each sample. The resulting abundance table of OTU-by-sample is trivially coerced to an otu_table object, and returned.
section_name: Details

section_content: An otu_table object parsed from the ". clust" file.
section_name: Value

section_content: Because usearch is an external (non-R) application, there is no direct way to continuously check that these suggested arguments and file formats will remain in their current state. If there is a problem, please verify your version of usearch, create a small reproducible example of the problem, and post it as an issue on the phyloseq issues tracker. The version of usearch upon which this import function was created is 7. 0. 109. Hopefully later versions of usearch maintain this function and format, but the phyloseq team has no way to guarantee this, and so any feedback about this will help maintain future functionality. For instance, it is currently assumed that the 9th and 10th columns of the. uc table hold the read-label and OTU ID, respectively; and it is also assumed that the delimiter between sample-name and read in the read-name entries is a single "_". If this is not true, you may have to update these parameters, or even modify the current implementation of this function. 

Also note that there is now a UPARSE-specific output file format, uparseout, and it might make more sense to create and import that file for use in phyloseq. If so, you'll want to import using the import_uparse() function. 

See Also index_type (Optional). A character string specifying the indices to properly order. Supported values are c("both", "taxa", "samples"). Default is "both", meaning samples and taxa indices will be checked/re-ordered. 

intersect_taxa Returns the intersection of species and samples for the components of x
section_name: Details

section_content: This function is used internally as part of the infrastructure to ensure that component data types in a phyloseq-object have exactly the same taxa/species. It relies heavily on the Reduce function to determine the strictly common species.
section_name: Description

section_name: Usage intersect_taxa(x)

section_content: x (Required). A phyloseq-class object that contains 2 or more components that in-turn describe species/taxa.
section_name: Arguments

section_content: Returns a character vector of only those species that are present in all species-describing components of x.
section_name: Value

section_content: Reduce, intersect
section_name: See Also

section_content: This is a phyloseq-specific implementation of the Jensen-Shannon Divergence for comparing pairs of microbial communities (samples) in an experiment. The expectation is that you have many samples (say. more than two) and you want a distance matrix on which will perform further analysis. 

JSD is intended to be "wrapped" by the more general distance function in phyloseq, and it can be invoked using "jsd" as the argument to the method parameter of distance.
section_name: Description

section_name: Usage

section_content: Arguments physeq (Required). phyloseq-class. The phyloseq data on which to compute the pairwise sample distance matrix.
section_name: JSD(physeq)

section_content: One of the motivations for providing JSD in phyloseq was its recent use in the analysis of the enterotype dataset.
section_name: Details

section_content: An object of class "dist" suitable for certain ordination methods and other distance-based analyses. See distance.
section_name: Value

section_content: Susan Holmes <susan@stat. stanford. edu>. type (Optional). Default "samples". Whether the network should be samples or taxa/OTUs. Supported arguments are "samples", "taxa", where "taxa" indicates using the OTUs/taxaindices, whether they actually represent species or some other taxonomic rank. NOTE: not all distance methods are supported if "taxa" selected for type. For example, the UniFrac distance and DPCoA cannot be calculated for taxa-wise distances, because they use a taxa-wise tree as part of their calculation between samples, and there is no transpose-equivalent for this tree. 

distance (Optional). Default "jaccard". Any supported argument to the method parameter of the distance function is supported here. Some distance methods, like "unifrac", may take a non-trivial amount of time to calculate, in which case merge_phyloseq Merge arguments into one phyloseq object.
section_name: Author(s)

section_content: Takes a comma-separated list of phyloseq objects as arguments, and returns the most-comprehensive single phyloseq object possible. 

Usage merge_phyloseq(. . . )
section_name: Description

section_content: . . . a comma-separated list of phyloseq objects.
section_name: Arguments

section_content: Higher-order objects can be created if arguments are appropriate component data types of different classes, and this should mirror the behavior of the phyloseq method, which is the suggested method if the goal is simply to create a higher-order phyloseq object from different data types (1 of each class) describing the same experiment. 

By contrast, this method is intended for situations in which one wants to combine multiple higherorder objects, or multiple core component data objects (e. g. more than one otu_table) that should be combined into one object. 

Merges are performed by first separating higher-order objects into a list of their component objects; then, merging any component objects of the same class into one object according to the behavior desribed in merge_phyloseq_pair; and finally, building back up a merged-object according to the constructor behavior of the phyloseq method. If the arguments contain only a single component type -several otu_table objects, for example -then a single merged object of that component type is returned.
section_name: Details

section_content: Merges are performed by first separating higher-order objects into a list of their component objects; then, merging any component objects of the same class into one object according to the behavior desribed in merge_phyloseq_pair; and finally, re-building a merged-object according to the constructor behavior of the phyloseq method. If the arguments contain only a single component type -several otu_table objects, for example -then a single merged object of the relevant component type is returned. 

Merges between 2 or more tree objects are ultimately done using consensus from the ape package. This has the potential to limit somewhat the final data object, because trees don't merge with other trees in the same granular manner as data tables, and ultimately the species/taxa in higher-order phyloseq objects will be clipped to what is contained in the tree. If this an issue, the tree component should be ommitted from the argument list. 

merge_phyloseq_pair Examples # ## # Make a random complex object ## OTU1 <-otu_table(matrix(sample(0:5,250,TRUE),25,10), taxa_are_rows=TRUE) ## tax1 <-tax_table(matrix("abc", 30, 8)) ## map1 <-data. frame( matrix(sample(0:3,250,TRUE),25,10), ## matrix(sample(c("a","b","c"),150,TRUE), 25, 6) ) ## map1 <-sample_data(map1) ## exam1 <-phyloseq(OTU1, map1, tax1) ## x <-exam1 ## x <-phyloseq(exam1) ## y <-tax_table(exam1) ## merge_phyloseq(x, y) ## merge_phyloseq(y, y, y, y) merge_phyloseq_pair Merge pair of phyloseq component data objects of the same class.
section_name: Value

section_content: Internal S4 methods to combine pairs of objects of classes specified in the phyloseq package. These objects must be component data of the same type (class). This is mainly an internal method, provided to illustrate how merging is performed by the more general merge_phyloseq function.
section_name: Description

section_content: ## S4 method for signature 'otu_table,otu_table' merge_phyloseq_pair(x, y) ## S4 method for signature 'taxonomyTable,taxonomyTable' merge_phyloseq_pair(x, y) ## S4 method for signature 'sample_data,sample_data' merge_phyloseq_pair(x, y) ## S4 method for signature 'phylo,phylo' merge_phyloseq_pair(x, y) ## S4 method for signature 'XStringSet,XStringSet' merge_phyloseq_pair(x, y)
section_name: Usage merge_phyloseq_pair(x, y)

section_content: x A character vector of the species in object x that you want to keep -OR alternatively -a logical vector where the kept species are TRUE, and length is equal to the number of species in object x. If species is a named logical, the species retained is based on those names. Make sure they are compatible with the taxa_names of the object you are modifying (x). 

y Any phyloseq object.
section_name: Arguments

section_content: The merge_phyloseq function is recommended in general. 

Special note: non-identical trees are merged using consensus.
section_name: Details

section_content: A single component data object that matches x and y arguments. The returned object will contain the union of the species and/or samples of each. If there is redundant information between a pair of arguments of the same class, the values in x are used by default. Abundance values are summed for otu_table objects for those elements that describe the same species and sample in x and y.
section_name: Value

section_content: Examples # ## # merge two simulated otu_table objects. ## x <-otu_table(matrix(sample(0:5,200,TRUE),20,10), taxa_are_rows=TRUE) ## y <-otu_table(matrix(sample(0:5,300,TRUE),30,10), taxa_are_rows=FALSE) ## xy <-merge_phyloseq_pair(x, y) ## yx <-merge_phyloseq_pair(y, x) ## # merge two simulated tax_table objects ## x <-tax_table(matrix("abc", 20, 6)) ## y <-tax_table(matrix("def", 30, 8)) ## xy <-merge_phyloseq_pair(x, y) ## # merge two simulated sample_data objects ## x <-data. frame( matrix(sample(0:3,250,TRUE),25,10), ## matrix(sample(c("a","b","c"),150,TRUE),25,6) ) ## x <-sample_data(x) ## y <-data. frame( matrix(sample(4:6,200,TRUE),20,10), ## matrix(sample(c("d","e","f"),120,TRUE),20,8) ) ## y <-sample_data(y) ## merge_phyloseq_pair(x, y) ## data. frame(merge_phyloseq_pair(x, y)) ## data. frame(merge_phyloseq_pair(y, x))

merge_samples merge_samples Merge samples based on a sample variable or factor.
section_name: See Also merge_phyloseq merge_taxa

section_content: The purpose of this method is to merge/agglomerate the sample indices of a phyloseq object according to a categorical variable contained in a sample_data or a provided factor. archetype is not a valid index or index-name in eqtaxa, the first will be used, and the value in archetype will be used as the index-name for the new species.
section_name: Description

section_content: The object, x, in its original class, but with the specified species merged into one entry in all relevant components. 

See Also tip_glom, tax_glom, merge_phyloseq, merge_samples
section_name: Value

section_content: # data(esophagus) tree <-phy_tree(esophagus) otu <-otu_table(esophagus) otutree0 <-phyloseq(otu, tree) # plot_tree(otutree0) otutree1 <-merge_taxa(otutree0, 1:8, 2) # plot_tree(esophagus, ladderize="left") metaMDS S3 class placeholder definition (list) for metaMDS
section_name: Examples

section_content: The ape package does export a version of its metaMDS-class, partly because it is not really defined formally anywhere. Instead, it is an S3 class extended from the base class, list -this is a very common and easy approach -and proper behavior of any method taking an instance of this class requires exact naming conventions for element names of the list components. The phyloseq package does not provide any validity checks that a given phylo instance is valid (conforms to the conventions in the ape package). . . yet. If problems arise, this might be considered, and they could be defined judiciously and within phyloseq.
section_name: Description

section_name: Usage metaMDS

section_content: An object of class metaMDS of length 0. Usage mt(physeq, classlabel, minPmaxT = "minP", method = "fdr",. . . )
section_name: Format

section_content: ## S4 method for signature 'phyloseq,ANY' mt(physeq, classlabel, minPmaxT = "minP", method = "fdr",. . . )

## S4 method for signature 'otu_table,integer' mt(physeq, classlabel, minPmaxT = "minP", method = "fdr",. . . )

## S4 method for signature 'otu_table,numeric' mt(physeq, classlabel, minPmaxT = "minP", method = "fdr",. . . )

## S4 method for signature 'otu_table,logical' mt(physeq, classlabel, minPmaxT = "minP", method = "fdr",. . . )

## S4 method for signature 'otu_table,character' mt(physeq, classlabel, minPmaxT = "minP", method = "fdr",. . . )

## S4 method for signature 'otu_table,factor' mt(physeq, classlabel, minPmaxT = "minP", method = "fdr",. . . )
section_name: See

section_content: Is not a labeling function itself, but returns one. The returned function is capable of adding whatever label is on a node. Note that the function that is returned has two completely different arguments to those listed here: the plot object already built by earlier steps in plot_tree, and the data. frame that contains the relevant plotting data for the nodes (especially x, y, label), respectively. See nodeplotboot for a more sophisticated example. The main purpose of this and nodeplotboot is to provide a useful default function generator for arbitrary and bootstrap node labels, respectively, and also to act as examples of functions that will successfully interact with plot_tree to add node labels to the graphic.
section_name: Description

section_content: nodeplotdefault(size=2L, hjust=-0. 2) Arguments size (Optional). Numeric. Should be positive. The size parameter used to control the text size of taxa labels. Default is 2. These are ggplot2 sizes. 

hjust (Optional). The horizontal justification of the node labels. Default is -0. 2.
section_name: Usage

section_content: A function that can add a node-label layer to a graphic.
section_name: Value

section_content: This function wraps several commonly-used ordination methods. The type of ordination depends upon the argument to method. Try ordinate("help") or ordinate("list") for the currently supported method options. 

Usage ordinate(physeq, method = "DCA", distance = "bray", formula = NULL,. . . )

Arguments physeq (Required). Phylogenetic sequencing data (phyloseq-class). The data on which you want to perform the ordination. In general, these methods will be based in some fashion on the abundance table ultimately stored as a contingency matrix (otu_table-class). If you're able to import data into phyloseq-class format, than you don't need to worry, as an otu_table is a required component of this class. In addition, some ordination methods require additional data, like a constraining variable or phylogenetic tree. If that is the case, the relevant data should be included in physeq prior to running. Integrating the data in this way also results in these different data components being checked for validity and completeness by the method. method (Optional). A character string. Default is "DCA". 

Currently supported method options are: c("DCA", "CCA", "RDA", "CAP", "DPCoA", "NMDS", "MDS", "PCoA") (Optional). Additional arguments to supporting functions. For example, the additional argument weighted=TRUE would be passed on to UniFrac if "unifrac" were chosen as the distance option and "MDS" as the ordination method option. Alternatively, if "DCA" were chosen as the ordination method option, additional arguments would be passed on to the relevant ordination function, decorana, for example.
section_name: Description

section_content: An ordination object. The specific class of the returned object depends upon the ordination method, as well as the function/package that is called internally to perform it. As a general rule, any of the ordination classes returned by this function will be recognized by downstream tools in the phyloseq package, for example the ordination plotting function, plot_ordination.
section_name: Value

section_content: The plot_ordination Tutorial Related component ordination functions described within phyloseq:
section_name: See Also

section_content: Described/provided by other packages: cca/rda, decorana, metaMDS, pcoa, capscale NMDS and MDS/PCoA both operate on distance matrices, typically based on some pairwise comparison of the microbiomes in an experiment/project. There are a number of common methods to use to calculate these pairwise distances, and the most convenient function (from a phyloseq point of view) for calculating these distance matrices is the otu_table distance function. It can be thought of as a distance / dissimilarity-index companion function for ordinate, and indeed the distance options provided to ordinate are often simply passed on to distance. 

A good quick summary of ordination is provided in the introductory vignette for vegan:

vegan introductory vignette

The following R task views are also useful for understanding the available tools in R:
section_name: DPCoA

section_content: The S4 class for storing taxa-abundance information.
section_name: otu_table-class

section_content: Because orientation of these tables can vary by method, the orientation is defined explicitly in the taxa_are_rows slot (a logical). The otu_table class inherits the matrix class to store abundance values. Various standard subset and assignment nomenclature has been extended to apply to the otu_table class, including square-bracket, t, etc.
section_name: Description

section_content: taxa_are_rows A single logical specifying the orientation of the abundance table. 

. Data This slot is inherited from the matrix class.
section_name: Details

section_name: otu_table<-

section_content: Assign a new OTU Table to x
section_name: otu_table<-

section_content: Assign a new OTU
section_name: Description

section_content: # data(GlobalPatterns) # # An example of pruning to just the first 100 taxa in GlobalPatterns. # ex2a <-prune_taxa(taxa_names(GlobalPatterns)[1:100], GlobalPatterns) # # The following 3 lines produces an ex2b that is equal to ex2a # ex2b <-GlobalPatterns # OTU <-otu_table(GlobalPatterns)[1:100, ] # otu_table(ex2b) <-OTU # identical(ex2a, ex2b) # print(ex2b) # # Relace otu_table by implying the component in context. # ex2c <-GlobalPatterns # otu_table(ex2c) <-ex2b # identical(ex2a, ex2c) parse_taxonomy_default Parse elements of a taxonomy vector
section_name: Examples

section_content: These are provided as both example and default functions for parsing a character vector of taxonomic rank information for a single taxa. As default functions, these are intended for cases where the data adheres to the naming convention used by greengenes (http://greengenes. lbl. gov/ cgi-bin/nph-index. cgi) or where the convention is unknown, respectively. To work, these functions -and any similar custom function you may want to create and use -must take as input a single character vector of taxonomic ranks for a single OTU, and return a named character vector that has been modified appropriately (according to known naming conventions, desired length limits, etc. 

The length (number of elements) of the output named vector does not need to be equal to the input, which is useful for the cases where the source data files have extra meaningless elements that should probably be removed, like the ubiquitous "Root" element often found in greengenes/QIIME taxonomy labels. In the case of parse_taxonomy_default, no naming convention is assumed and so dummy rank names are added to the vector. More usefully if your taxonomy data is based on greengenes, the parse_taxonomy_greengenes function clips the first 3 characters that identify the rank, and uses these to name the corresponding element according to the appropriate taxonomic rank name used by greengenes (e. g. "p__" at the beginning of an element means that element is the name of the phylum to which this OTU belongs). Most importantly, the expectations for these functions described above make them compatible to use during data import, specifcally the import_biom function, but it is a flexible structure that will be implemented soon for all phyloseq import functions that deal with taxonomy (e. g. import_qiime). 

Usage parse_taxonomy_default(char. vec) parse_taxonomy_greengenes(char. vec) parse_taxonomy_qiime(char. vec) Arguments char. vec (Required). A single character vector of taxonomic ranks for a single OTU, unprocessed (ugly).
section_name: Description

section_content: A character vector in which each element is a different taxonomic rank of the same OTU, and each element name is the name of the rank level. For example, an element might be "Firmicutes" and named "phylum". These parsed, named versions of the taxonomic vector should reflect embedded information, naming conventions, desired length limits, etc; or in the case of parse_taxonomy_default, not modified at all and given dummy rank names to each element. 

phylo See Also
section_name: Value

section_content: Examples taxvec1 = c("Root", "k__Bacteria", "p__Firmicutes", "c__Bacilli", "o__Bacillales", "f__Staphylococcaceae") parse_taxonomy_default(taxvec1) parse_taxonomy_greengenes(taxvec1) taxvec2 = c("Root;k__Bacteria;p__Firmicutes;c__Bacilli;o__Bacillales;f__Staphylococcaceae") parse_taxonomy_qiime(taxvec2) pcoa S3 class for ape-calculated MDS results
section_name: import_biom import_qiime

section_content: Nothing to import, because ape doesn't (yet) export this S3 class. We will define it here, but keep it internal. For the moment, its only use is for proper dispatch in our extensions to the scores S3 generic from vegan, for generic extraction of coordinates and possibly other features from any ordination results.
section_name: Description

section_name: Usage pcoa

section_content: An object of class pcoa of length 0. 

phylo S3 class placeholder definition (list) for phylogenetic trees.
section_name: Format

section_content: The ape package does not export a version of its phylo-class, partly because it is not really defined formally anywhere. Instead, it is an S3 class extended from the base class, list -this is a very common and easy approach -and proper behavior of any method taking an instance of this class requires exact naming conventions for element names of the components. The phyloseq package does not provide any validity checks that a given phylo instance is valid (conforms to the conventions in the ape package). Yet. If problems arise, this might be considered, and they could be defined judiciously and within phyloseq. Similarly, if a formal definition for the the phylo-class is ever exported by ape, the current philosophy of phyloseq would be to remove this internal definition and import the former. Note that there is still some work going on for the phylobase package, which is addressing these same exact issues for S4 phylogenetic tree interaction. A very large number of packages (around 60 at my last count), depend on ape, making it easily the de facto standard for representing phylogenetic trees in R; and the phyloseq team would prefer to use any exported definitions from the ape package if possible and available.
section_name: Description

section_name: Usage phylo

section_content: An object of class phylo of length 0. 

See Also phylo phylo-class An S4 placeholder of the main phylogenetic tree class from the ape package.
section_name: Format

section_content: See the ape package for details about this type of representation of a phylogenetic tree. It is used throughout the ape package. 

See Also phylo, setOldClass phyloseq Build phyloseq-class objects from their components. 

Description phyloseq() is a constructor method, This is the main method suggested for constructing an experimentlevel (phyloseq-class) object from its component data (component data classes: otu_table-class, sample_data-class, taxonomyTable-class, phylo-class). 

Usage phyloseq(. . . )
section_name: Description

section_content: . . . One or more component objects among the set of classes defined by the phyloseq package, as well as phylo-class (defined by the ape-package). Each argument should be a different class. For combining multiple components of the same class, or multiple phyloseq-class objects, use the merge_phyloseq function. Unlike in earlier versions, the arguments to phyloseq do not need to be named, and the order of the arguments does not matter.
section_name: Arguments

section_name: phyloseq-class

section_content: The class of the returned object depends on the argument class(es). For an experiment-level object, two or more component data objects must be provided. Otherwise, if a single component-class is provided, it is simply returned as-is. The order of arguments does not matter.
section_name: Value

section_content: Examples data(esophagus) x1 = phyloseq(otu_table(esophagus), phy_tree(esophagus)) identical(x1, esophagus) # # data(GlobalPatterns) # # GP <-GlobalPatterns # # phyloseq(sample_data(GP), otu_table(GP)) # # phyloseq(otu_table(GP), phy_tree(GP)) # # phyloseq(tax_table(GP), otu_table(GP)) # # phyloseq(phy_tree(GP), otu_table(GP), sample_data(GP)) # # phyloseq(otu_table(GP), tax_table(GP), sample_data(GP)) # # phyloseq(otu_table(GP), phy_tree(GP), tax_table(GP), sample_data(GP))
section_name: See Also merge_phyloseq

section_content: The main experiment-level class for phyloseq data
section_name: phyloseq-class

section_content: Contains all currently-supported component data classes: otu_table-class, sample_data-class, taxonomyTable-class ("tax_table" slot), phylo-class ("phy_tree" slot), and the XStringSet-class ("refseq" slot). There are several advantages to storing your phylogenetic sequencing experiment as an instance of the phyloseq class, not the least of which is that it is easy to return to the data later and feel confident that the different data types "belong" to one another. Furthermore, the phyloseq constructor ensures that the different data components have compatible indices (e. g. OTUs and samples), and performs the necessary trimming automatically when you create your "experimentlevel" object. Downstream analyses are aware of which data classes they require -and where to find them -often making your phyloseq-class object the only data argument required for analysis and plotting functions (although there are many options and parameter arguments available to you).
section_name: Description

section_content: In the case of missing component data, the slots are set to NULL. As soon as a phyloseq-class object is to be updated with new component data (previously missing/NULL or not), the indices of all components are re-checked for compatibility and trimmed if necessary. This is to ensure by design that components describe the same taxa/samples, and also that these trimming/validity checks do not need to be repeated in downstream analyses.
section_name: Details

section_content: otu_table a single object of class otu_table. 

sam_data a single object of class sample_data. 

tax_table a single object of class taxonomyTable. 

phy_tree a single object of the phylo-class, from the ape package. 

refseq a biological sequence set object of a class that inherits from the XStringSet-class, from the Biostrings package.
section_name: slots:

section_content: The constructor, phyloseq, the merger merge_phyloseq, and also the component constructor/accessors otu_table, sample_data, tax_table, phy_tree, and refseq. 

phyloseq-deprecated Depcrecated functions in the phyloseq package.
section_name: See Also

section_content: These will be migrated to "defunct" status in the next release, and removed completely in the release after that. These functions are provided for compatibility with older version of the phyloseq package. They may eventually be completely removed. 

Usage deprecated_phyloseq_function(x, value,. . . )
section_name: Description

section_content: x For assignment operators, the object that will undergo a replacement (object inside parenthesis). 

value For assignment operators, the value to replace with (the right side of the assignment). 

. . . For functions other than assignment operators, parameters to be passed to the modern version of the function (see table ). Required). A formula which specifies the design of the experiment, taking the form formula(~x + y + z). That is, a formula with right-hand side only. By default, the functions in this package and DESeq2 will use the last variable in the formula (e. g. z) for presenting results (fold changes, etc. ) and plotting.
section_name: Arguments

section_content: When considering your specification of experimental design, you will want to re-order the levels so that the NULL set is first. For example, the following line of code would ensure that Enterotype 1 is used as the reference sample class in tests by setting it to the first of the factor levels using the relevel function: sample_data(entill)$Enterotype <-relevel(sample_data(entill)$Enterotype, "1"). . . (Optional). Additional named arguments passed to DESeqDataSetFromMatrix. Most users will not need to pass any additional arguments here. Most testingrelated options should be provided in a following call to DESeq.
section_name: Details

section_content: A DESeqDataSet object. 

See Also vignette("phyloseq-mixture-models")

The phyloseq-extensions tutorials.
section_name: Value

section_name: DESeq results

section_name: DESeqDataSetFromMatrix

section_content: # Check out the vignette phyloseq-mixture-models for more details. # vignette("phyloseq-mixture-models") data( soilrep phy_tree Retrieve phylogenetic tree (phylo-class) from object.
section_name: Examples

section_content: This is the suggested method for accessing the phylogenetic tree, (phylo-class) from a phyloseq-class. 

Like other accessors (see See Also, below), the default behavior of this method is to stop with an error if physeq is a phyloseq-class but does not contain a phylogenetic tree (the component data you are trying to access in this case). 

Usage phy_tree(physeq, errorIfNULL=TRUE) ## S4 method for signature 'ANY' phy_tree(physeq, errorIfNULL = TRUE) ## S4 method for signature 'phylo' phy_tree(physeq)

Arguments physeq (Required). An instance of phyloseq-class that contains a phylogenetic tree. If physeq is a phylogenetic tree (a component data class), then it is returned as-is. 

errorIfNULL (Optional). Logical. Should the accessor stop with an error if the slot is empty (NULL)? Default TRUE.
section_name: Description

section_content: Note that the tip labels should be named to match the taxa_names of the other objects to which it is going to be paired. The phyloseq constructor automatically checks for exact agreement in the set of species described by the phlyogenetic tree and the other components (taxonomyTable, otu_table), and trims as-needed. Thus, the tip. labels in a phylo object must be named to match the results of taxa_names of the other objects to which it will ultimately be paired.
section_name: Details

section_content: The phylo-class object contained within physeq; or NULL if physeq does not have a tree. This method stops with an error in the latter NULL case be default, which can be over-ridden by changing the value of errorIfNULL to FALSE. 

See Also plot_heatmap
section_name: Value

section_name: Create an ecologically-organized heatmap using ggplot2 graphics

section_content: There are many useful examples of phyloseq heatmap graphics in the phyloseq online tutorials. 

In a 2010 article in BMC Genomics, Rajaram and Oono show describe an approach to creating a heatmap using ordination methods to organize the rows and columns instead of (hierarchical) cluster analysis. In many cases the ordination-based ordering does a much better job than h-clustering. 

An immediately useful example of their approach is provided in the NeatMap package for R. The NeatMap package can be used directly on the abundance table (otu_table-class) of phylogeneticsequencing data, but the NMDS or PCA ordination options that it supports are not based on ecological distances. To fill this void, phyloseq provides the plot_heatmap() function as an ecologyoriented variant of the NeatMap approach to organizing a heatmap and build it using ggplot2 graphics tools. The distance and method arguments are the same as for the plot_ordination function, and support large number of distances and ordination methods, respectively, with a strong leaning toward ecology. This function also provides the options to re-label the OTU and sample axis-ticks with a taxonomic name and/or sample variable, respectively, in the hope that this might hasten your interpretation of the patterns (See the sample. label and taxa. label documentation, below). Note that this function makes no attempt to overlay hierarchical clustering trees on the axes, as hierarchical clustering is not used to organize the plot. Also note that each re-ordered axis repeats at the edge, and so apparent clusters at the far right/left or top/bottom of the heat-map may actually be the same. For now, the placement of this edge can be considered arbitrary, so beware of this artifact of this graphical representation. If you benefit from this phyloseq-specific implementation of the NeatMap approach, please cite both our packages/articles.
section_name: Description

section_content: plot_heatmap(physeq, method = "NMDS", distance = "bray", sample. label = NULL, taxa. label = NULL, low = "#000033", high = "#66CCFF", na. value = "black", trans = log_trans( 4 sample. order (Optional). Default NULL. Either a single character string matching one of the sample_variables in your data, or a character vector of sample_names in the precise order that you want them displayed in the heatmap. This overrides any ordination ordering that might be done with the method/distance arguments. 

taxa. order (Optional). Default NULL. Either a single character string matching one of the rank_names in your data, or a character vector of taxa_names in the precise order that you want them displayed in the heatmap. This overrides any ordination ordering that might be done with the method/distance arguments. 

first. sample (Optional). Default NULL. A character string matching one of the sample_names of your input data (physeq). It will become the left-most sample in the plot. For the ordination-based ordering (recommended), the left and right edges of the axes are adjaacent in a continuous ordering. Therefore, the choice of starting sample is meaningless and arbitrary, but it is aesthetically poor to have the left and right edge split a natural cluster in the data. This argument allows you to specify the left edge and thereby avoid cluster-splitting, emphasize a gradient, etc. 

first. taxa (Optional). Default NULL. A character string matching one of the taxa_names of your input data (physeq). This is equivalent to first. sample (above), but for the taxa/OTU indices, usually the vertical axis. 

. . . (Optional). Additional parameters passed to ordinate.
section_name: Usage

section_content: This approach borrows heavily from the heatmap1 function in the NeatMap package. Highly recommended, and we are grateful for their package and ideas, which we have adapted for our specific purposes here, but did not use an explicit dependency. At the time of the first version of this implementation, the NeatMap package depends on the rgl-package, which is not needed in phyloseq, at present. Although likely a transient issue, the rgl-package has some known installation issues that have further influenced to avoid making NeatMap a formal dependency (Although we love both NeatMap and rgl!).
section_name: Details

section_content: A heatmap plot, in the form of a ggplot2 plot object, which can be further saved and modified. Examples data("GlobalPatterns") gpac <-subset_taxa(GlobalPatterns, Phylum=="Crenarchaeota") # FYI, the base-R function uses a non-ecological ordering scheme, # but does add potentially useful hclust dendrogram to the sides. . . gpac <-subset_taxa(GlobalPatterns, Phylum=="Crenarchaeota") # Remove the nearly-empty samples (e. g. 10 reads or less) gpac = prune_samples(sample_sums(gpac) > 50, gpac) # Arbitrary order if method set to NULL plot_heatmap(gpac, method=NULL, sample. label="SampleType", taxa. label="Family") # Use ordination plot_heatmap(gpac, sample. label="SampleType", taxa. label="Family") # Use ordination for OTUs, but not sample-order plot_heatmap(gpac, sample. label="SampleType", taxa. label="Family", sample. order="SampleType") # Specifying both orders omits any attempt to use ordination. The following should be the same. p0 = plot_heatmap(gpac, sample. label="SampleType", taxa. label="Family", taxa. order="Phylum", sample. order="Sample p1 = plot_heatmap(gpac, method=NULL, sample. label="SampleType", taxa. label="Family", taxa. order="Phylum", sample. #expect_equivalent(p0, p1) # Example: Order matters. Random ordering of OTU indices is difficult to interpret, even with structured sample orde rando = sample(taxa_names(gpac), size=ntaxa(gpac), replace=FALSE) plot_heatmap(gpac, method=NULL, sample. label="SampleType", taxa. label="Family", taxa. order=rando, sample. order=" # # Select the edges of each axis. # First, arbitrary edge, ordering plot_heatmap(gpac, method=NULL) # Second, biological-ordering (instead of default ordination-ordering), but arbitrary edge plot_heatmap(gpac, taxa. order="Family", sample. order="SampleType") # Third, biological ordering, selected edges plot_heatmap(gpac, taxa. order="Family", sample. order="SampleType", first. taxa="546313", first. sample="NP2") # Fourth, add meaningful labels plot_heatmap(gpac, sample. label="SampleType", taxa. label="Family", taxa. order="Family", sample. order="SampleType plot_net
section_name: Value

section_name: Microbiome Network Plot using ggplot2

section_content: There are many useful examples of phyloseq network graphics in the phyloseq online tutorials. A custom plotting function for displaying networks using advanced ggplot2 formatting. Note that this function is a performance and interface revision to plot_network, which requires an igraph object as its first argument. This new function is more in-line with other plot_* functions in plot_net the phyloseq-package, in that its first/main argument is a phyloseq-class instance. Edges in the network are created if the distance between nodes is below a (potentially arbitrary) threshold, and special care should be given to considering the choice of this threshold. However, network line thickness and opacity is scaled according to the similarity of vertices (either samples or taxa), helping to temper, somewhat, the effect of the threshold. Also note that the choice of network layout algorithm can have a large effect on the impression and interpretability of the network graphic, and you may want to familiarize yourself with some of these options (see the laymeth argument). 

Usage plot_net(physeq, distance = "bray", type = "samples", maxdist = 0. 7, laymeth = "fruchterman. reingold", color = NULL, shape = NULL, rescale = FALSE, point_size = 5, point_alpha = 1, point_label = NULL, hjust = 1. 35, title = NULL)

Arguments physeq (Required). The phyloseq-class object that you want to represent as a network. distance (Optional). Default is "bray". Can be either a distance method supported by distance, or an already-computed dist-class with labels that match the indices implied by both the physeq and type arguments (that is, either sample or taxa names). If you used distance to pre-calculate your distance, and the same type argument as provided here, then they will match. type (Optional). Default "samples". Whether the network represented in the primary argument, g, is samples or taxa/OTUs. Supported arguments are "samples", "taxa", where "taxa" indicates using the taxa indices, whether they actually represent species or some other taxonomic rank. maxdist (Optional). Default 0. 7. The maximum distance value between two vertices to connect with an edge in the graphic. laymeth (Optional). Default "fruchterman. reingold". A character string that indicates the method that will determine the placement of vertices, typically based on conectedness of vertices and the number of vertices. This is an interesting topic, and there are lots of options
section_name: Description

section_content: A ggplot2 network plot. Will render to default graphic device automatically as print side effect. 

Can also be saved, further manipulated, or rendered to a vector or raster file using ggsave.
section_name: Value

section_content: Original network plotting functions: make_network plot_network Examples data(enterotype) plot_net(enterotype, color="SeqTech", maxdist = 0. 3) plot_net(enterotype, color="SeqTech", maxdist = 0. 3, laymeth = "auto") plot_net(enterotype, color="SeqTech", maxdist = 0. 3, laymeth = "svd") plot_net(enterotype, color="SeqTech", maxdist = 0. 3, laymeth = "circle") plot_net(enterotype, color="SeqTech", shape="Enterotype", maxdist = 0. 3, laymeth = "circle") plot_network
section_name: See Also

section_content: There are many useful examples of phyloseq network graphics in the phyloseq online tutorials. A custom plotting function for displaying networks using advanced ggplot2 formatting. The network itself should be represented using the igraph package. For the phyloseq-package it is suggested that the network object (argument g) be created using the make_network function, and based upon sample-wise or taxa-wise microbiome ecological distances calculated from a phylogenetic sequencing experiment (phyloseq-class). In this case, edges in the network are created if the distance between nodes is below a potentially arbitrary threshold, and special care should be given to considering the choice of this threshold. 

Usage plot_network(g, physeq=NULL, type="samples", color=NULL, shape=NULL, point_size=4, alpha=1, label="value", hjust = 1. 35, line_weight=0. 5, line_color=color, line_alpha=0. 4, layout. method=layout. fruchterman. reingold, title=NULL) Arguments g (Required). An igraph-class object created either by the convenience wrapper make_network, or directly by the tools in the igraph-package. physeq (Optional). Default NULL. A phyloseq-class object on which g is based. type (Optional). Default "samples". Whether the network represented in the primary argument, g, is samples or taxa/OTUs. Supported arguments are "samples", "taxa", where "taxa" indicates using the taxa indices, whether they actually represent species or some other taxonomic rank. color (Optional). Default NULL. The name of the sample variable in physeq to use for color mapping of points (graph vertices). shape (Optional). Default NULL. The name of the sample variable in physeq to use for shape mapping. of points (graph vertices). point_size (Optional). Default 4. The size of the vertex points. alpha (Optional). Default 1. A value between 0 and 1 for the alpha transparency of the vertex points. label (Optional). Default "value". The name of the sample variable in physeq to use for labelling the vertex points. hjust (Optional). Default 1. 35. The amount of horizontal justification to use for each label. line_weight (Optional). Default 0. 3. The line thickness to use to label graph edges. line_color (Optional). Default color. The name of the sample variable in physeq to use for color mapping of lines (graph edges). line_alpha (Optional). Default 0. 4. The transparency level for graph-edge lines. layout. method (Optional). Default layout. fruchterman. reingold. A function (closure) that determines the placement of the vertices for drawing a graph. Should be able to take an igraph-class as sole argument, and return a two-column coordinate matrix with nrow equal to the number of vertices. For possible options already included in igraph-package, see the others also described in the help file: title (Optional). Default NULL. Character string. The main title for the graphic. layout. fruchterman. reingold
section_name: Description

section_content: A ggplot2 plot representing the network, with optional mapping of variable(s) to point color or shape.
section_name: Value

section_content: This code was adapted from a repo original hosted on GitHub by Scott Chamberlain: https: //github. com/SChamberlain/gggraph

The code most directly used/modified was first posted here: http://www. r-bloggers. com/basic-ggplot2-network-grap See Also make_network Examples data(enterotype) ig <-make_network(enterotype, max. dist=0. 3) plot_network(ig, enterotype, color="SeqTech", shape="Enterotype", line_weight=0. 3, label=NULL) # Change distance parameter ig <-make_network(enterotype, max. dist=0. 2) plot_network(ig, enterotype, color="SeqTech", shape="Enterotype", line_weight=0. 3, label=NULL) plot_ordination General ordination plotter based on ggplot2.
section_name: References

section_content: There are many useful examples of phyloseq ordination graphics in the phyloseq online tutorials. 

Convenience wrapper for plotting ordination results as a ggplot2-graphic, including additional annotation in the form of shading, shape, and/or labels of sample variables. There is no default, as the expectation is that the ordination will be performed and saved prior to calling this plot function. 

type (Optional). The plot type. Default is "samples". The currently supported options are c("samples", "sites", "species", "taxa", "biplot", "split", "scree"). The option "taxa" is equivalent to "species" in this case, and similarly, "samples" is equivalent to "sites". The options "sites" and "species" result in a single-plot of just the sites/samples or species/taxa of the ordination, respectively. The "biplot" and "split" options result in a combined plot with both taxa and samples, either combined into one plot ("biplot") or separated in two facet panels ("split"), respectively. The "scree" option results in a call to plot_scree, which produces an ordered bar plot of the normalized eigenvalues associated with each ordination axis. 

axes (Optional). A 2-element vector indicating the axes of the ordination that should be used for plotting. Can be character-class or integer-class, naming the index name or index of the desired axis for the horizontal and vertical axes, respectively, in that order. The default value, c(1, 2), specifies the first two axes of the provided ordination. 

color (Optional). Default NULL. Character string. The name of the variable to map to colors in the plot. This can be a sample variable (among the set returned by sample_variables(physeq) ) or taxonomic rank (among the set returned by rank_names(physeq)). 

Note that the color scheme is chosen automatically by link{ggplot}, but it can be modified afterward with an additional layer using scale_color_manual. shape (Optional). Default NULL. Character string. The name of the variable to map to different shapes on the plot. Similar to color option, but for the shape if points. 

The shape scale is chosen automatically by link{ggplot}, but it can be modified afterward with an additional layer using scale_shape_manual. label (Optional). Default NULL. Character string. The name of the variable to map to text labels on the plot. Similar to color option, but for plotting text. 

title (Optional). Default NULL. Character string. The main title for the graphic. justDF (Optional). Default FALSE. Logical. Instead of returning a ggplot2-object, do you just want the relevant data. frame that was used to build the plot? This is a user-accessible option for obtaining the data. frame, in in principal to make a custom plot that isn't possible with the available options in this function. For contributing new functions (developers), the phyloseq-package provides/uses an internal function to build the key features of the data. frame prior to plotbuild.
section_name: Description

section_content: A ggplot plot object, graphically summarizing the ordination result for the specified axes.
section_name: Value

section_content: Many more examples are included in the phyloseq online tutorials.
section_name: See Also

section_content: plot_phyloseq Examples # See other examples at # http://joey711. github. io/phyloseq/plot_ordination-examples data(GlobalPatterns) GP = prune_taxa(names(sort(taxa_sums(GlobalPatterns), TRUE)[1:50]), GlobalPatterns) gp_bray_pcoa = ordinate(GP, "CCA", "bray") plot_ordination(GP, gp_bray_pcoa, "samples", color="SampleType") plot_phyloseq Generic plot defaults for phyloseq.
section_name: Also see the general wrapping function:

section_content: There are many useful examples of phyloseq graphics functions in the phyloseq online tutorials. 

The specific plot type is chosen according to available non-empty slots. This is mainly for syntactic convenience and quick-plotting. See links below for some examples of available graphics tools available in the phyloseq-package. 

Usage plot_phyloseq(physeq,. . . ) ## S4 method for signature 'phyloseq' plot_phyloseq(physeq,. . . )

Arguments physeq (Required). phyloseq-class. The actual plot type depends on the available (non-empty) component data types contained within. 

. . . (Optional). Additional parameters to be passed on to the respective specific plotting function. See below for different plotting functions that might be called by this generic plotting wrapper.
section_name: Description

section_content: A plot is created. The nature and class of the plot depends on the physeq argument, specifically, which component data classes are present. 

See Also phyloseq frontpage tutorials.
section_name: Value

section_content: Examples data(esophagus) plot_phyloseq(esophagus) plot_richness
section_name: plot_ordination plot_heatmap plot_tree plot_network plot_bar plot_richness

section_name: Plot alpha diversity, flexibly with ggplot2

section_content: There are many useful examples of alpha-diversity graphics in the phyloseq online tutorials. This function estimates a number of alpha-diversity metrics using the estimate_richness function, and returns a ggplot plotting object. The plot generated by this function will include every sample in physeq, but they can be further grouped on the horizontal axis through the argument to x, and shaded according to the argument to color (see below). You must use untrimmed, non-normalized count data for meaningful results, as many of these estimates are highly dependent on the number of singletons. You can always trim the data later on if needed, just not before using this function. 

Usage plot_richness(physeq, x = "samples", color = NULL, shape = NULL, title = NULL, scales = "free_y", nrow = 1, shsi = NULL, measures = NULL, sortby = NULL) Arguments physeq (Required). phyloseq-class, or alternatively, an otu_table-class. The data about which you want to estimate. 

x (Optional). A variable to map to the horizontal axis. The vertical axis will be mapped to the alpha diversity index/estimate and have units of total taxa, and/or index value (dimensionless). This parameter (x) can be either a character string indicating a variable in sample_data (among the set returned by sample_variables(physeq) ); or a custom supplied vector with length equal to the number of samples in the dataset (nsamples(physeq)). The default value is "samples", which will map each sample's name to a separate horizontal position in the plot. 

color (Optional). Default NULL. The sample variable to map to different colors. Like x, this can be a single character string of the variable name in sample_data (among the set returned by sample_variables(physeq) ); or a custom supplied vector with length equal to the number of samples in the dataset (nsamples(physeq)). The color scheme is chosen automatically by link{ggplot}, but it can be modified afterward with an additional layer using scale_color_manual. shape (Optional). Default NULL. The sample variable to map to different shapes. Like x and color, this can be a single character string of the variable name in sample_data (among the set returned by sample_variables(physeq) ); or a custom supplied vector with length equal to the number of samples in the dataset (nsamples(physeq)). The shape scale is chosen automatically by link{ggplot}, but it can be modified afterward with an additional layer using scale_shape_manual. title (Optional). Default NULL. Character string. The main title for the graphic. scales (Optional). Default "free_y". Whether to let vertical axis have free scale that adjusts to the data in each panel. This argument is passed to facet_wrap. If set to "fixed", a single vertical scale will be used in all panels. This can obscure values if the measures argument includes both richness estimates and diversity indices, for example. nrow (Optional). Default is 1, meaning that all plot panels will be placed in a single row, side-by-side. This argument is passed to facet_wrap. If NULL, the number of rows and columns will be chosen automatically (wrapped) based on the number of panels and the size of the graphics device. 

shsi (Deprecated). No longer supported. Instead see 'measures' below. 

measures (Optional). Default is NULL, meaning that all available alpha-diversity measures will be included in plot panels. Alternatively, you can specify one or more measures as a character vector of measure names. Values must be among those supported: c("Observed", "Chao1", "ACE", "Shannon", "Simpson", "InvSimpson", "Fisher"). sortby (Optional). A character string subset of measures argument. Sort x-indices by the mean of one or more measures, if x-axis is mapped to a discrete variable. Default is NULL, implying that a discrete-value horizontal axis will use default sorting, usually alphabetic.
section_name: Description

section_content: NOTE: Because this plotting function incorporates the output from estimate_richness, the variable names of that output should not be used as x or color (even if it works, the resulting plot might be kindof strange, and not the intended behavior of this function). The following are the names you will want to avoid using in x or color: c("Observed", "Chao1", "ACE", "Shannon", "Simpson", "InvSimpson", "Fisher").
section_name: Details

section_content: A ggplot plot object summarizing the richness estimates, and their standard error.
section_name: Value

section_name: See Also

section_content: There are many more interesting examples at the phyloseq online tutorials.
section_name: estimate_richness estimateR diversity

section_content: ## There are many more interesting examples at the phyloseq online tutorials. ## http://joey711. github. io/phyloseq/plot_richness-examples data("soilrep") plot_richness(soilrep, measures=c("InvSimpson", "Fisher")) plot_richness(soilrep, "Treatment", "warmed", measures=c("Chao1", "ACE", "InvSimpson"), nrow=3) data("GlobalPatterns") plot_scree plot_richness(GlobalPatterns, x="SampleType", measures=c("InvSimpson")) plot_richness(GlobalPatterns, x="SampleType", measures=c("Chao1", "ACE", "InvSimpson"), nrow=3) plot_richness(GlobalPatterns, x="SampleType", measures=c("Chao1", "ACE", "InvSimpson"), nrow=3, sortby = "Chao1") plot_scree General ordination eigenvalue plotter using ggplot2.
section_name: Examples

section_content: Convenience wrapper for plotting ordination eigenvalues (if available) using a ggplot2-graphic. 

Usage plot_scree(ordination, title = NULL) Arguments ordination (Required). An ordination object. Many different classes of ordination are defined by R packages. Ordination classes currently supported/created by the ordinate function are supported here. There is no default, as the expectation is that the ordination will be performed and saved prior to calling this plot function. title (Optional). Default NULL. Character string. The main title for the graphic.
section_name: Description

section_content: A ggplot plot object, graphically summarizing the ordination result for the specified axes. 

See Also plot_ordination ordinate distance phyloseq online tutorials
section_name: Value

section_content: # First load and trim a dataset data("GlobalPatterns") GP = prune_taxa(names(sort(taxa_sums(GlobalPatterns), TRUE)[1:50]), GlobalPatterns) # Test plots (preforms ordination in-line, then makes scree plot) plot_scree(ordinate(GP, "DPCoA", "bray")) plot_scree(ordinate(GP, "PCoA", "bray")) # Empty return with message plot_scree(ordinate(GP, "NMDS", "bray")) # Constrained ordinations plot_scree(ordinate(GP, "CCA", formula=~SampleType)) plot_scree(ordinate(GP, "RDA", formula=~SampleType)) plot_scree(ordinate(GP, "CAP", formula=~SampleType))

# Deprecated example of constrained ordination (emits a warning) #plot_scree(ordinate(GP ~SampleType, "RDA")) plot_scree(ordinate(GP, "DCA")) plot_ordination(GP, ordinate(GP, "DCA"), type="scree") plot_tree
section_name: Examples

section_name: Plot a phylogenetic tree with optional annotations

section_content: There are many useful examples of phyloseq tree graphics in the phyloseq online tutorials. This function is intended to facilitate easy graphical investigation of the phylogenetic tree, as well as sample data. Note that for phylogenetic sequencing of samples with large richness, some of the options in this function will be prohibitively slow to render, or too dense to be interpretable. A rough "rule of thumb" is to use subsets of data with not many more than 200 OTUs per plot, sometimes less depending on the complexity of the additional annotations being mapped to the tree. It is usually possible to create an unreadable, uninterpretable tree with modern datasets. However, the goal should be toward parameter settings and data subsets that convey (honestly, accurately) some biologically relevant feature of the data. One of the goals of the phyloseq-package is to make the determination of these features/settings as easy as possible. 

Usage plot_tree(physeq, method = "sampledodge", nodelabf = NULL, color = NULL, shape = NULL, size = NULL, min. abundance = Inf, label. tips = NULL, text. size = NULL, sizebase = 5, base. spacing = 0. 02, ladderize = FALSE, plot. margin = 0. 2, title = NULL, treetheme = NULL, justify = "jagged")

Arguments physeq (Required). The data about which you want to plot and annotate a phylogenetic tree, in the form of a single instance of the phyloseq-class, containing at minimum a phylogenetic tree component (try phy_tree). One of the major advantages of this function over basic tree-plotting utilities in the ape-package is the ability to easily annotate the tree with sample variables and taxonomic information. For these uses, the physeq argument should also have a sample_data and/or tax_table component(s). method (Optional). Character string. Default "sampledodge". The name of the annotation method to use. This will be expanded in future versions. Currently only "sampledodge" and "treeonly" are supported. The "sampledodge" option results in points drawn next to leaves if individuals from that taxa were observed, and a separate point is drawn for each sample. nodelabf (Optional). A function. Default NULL. If NULL, the default, a function will be selected for you based upon whether or not there are node labels in phy_tree(physeq). 

For convenience, the phyloseq package includes two generator functions for adding arbitrary node labels (can be any character string), nodeplotdefault; plot_tree as well as for adding bootstrap values in a certain range, nodeplotboot. To not have any node labels in the graphic, set this argument to nodeplotblank. color (Optional). Character string. Default NULL. The name of the variable in physeq to map to point color. Supported options here also include the reserved special variables of psmelt. shape (Optional). Character string. Default NULL. The name of the variable in physeq to map to point shape. Supported options here also include the reserved special variables of psmelt. size (Optional). Character string. Default NULL. The name of the variable in physeq to map to point size. A special argument "abundance" is reserved here and scales point size using abundance in each sample on a log scale. Supported options here also include the reserved special variables of psmelt. 

min. abundance (Optional). Numeric. The minimum number of individuals required to label a point with the precise number. Default is Inf, meaning that no points will have their abundance labeled. If a vector, only the first element is used. 

label. tips (Optional). Character string. Default is NULL, indicating that no tip labels will be printed. If "taxa_names", then the name of the taxa will be added to the tree; either next to the leaves, or next to the set of points that label the leaves. Alternatively, if this is one of the rank names (from rank_names(physeq)), then the identity (if any) for that particular taxonomic rank is printed instead. 

text. size (Optional). Numeric. Should be positive. The size parameter used to control the text size of taxa labels. Default is NULL. If left NULL, this function will automatically calculate a (hopefully) optimal text size given the vertical constraints posed by the tree itself. This argument is included in case the automaticallycalculated size is wrong, and you want to change it. Note that this parameter is only meaningful if label. tips is not NULL. sizebase (Optional). Numeric. Should be positive. The base of the logarithm used to scale point sizes to graphically represent abundance of species in a given sample. Default is 5. 

base. spacing (Optional). Numeric. Default is 0. 02. Should be positive. This defines the basespacing between points at each tip/leaf in the the tree. The larger this value, the larger the spacing between points. This is useful if you have problems with overlapping large points and/or text indicating abundance, for example. Similarly, if you don't have this problem and want tighter point-spacing, you can shrink this value. 

ladderize (Optional). Boolean or character string (either FALSE, TRUE, or "left"). Default is FALSE. This parameter specifies whether or not to ladderize the tree (i. e., reorder nodes according to the depth of their enclosed subtrees) prior to plotting. This tends to make trees more aesthetically pleasing and legible in a graphical display. When TRUE or "right", "right" ladderization is used. When set to FALSE, no ladderization is applied. When set to "left", the reverse direction ("left" ladderization) is applied. This argument is passed on to tree_layout. 

plot. margin (Optional). Numeric. Default is 0. 2. Should be positive. This defines how much right-hand padding to add to the tree plot, which can be required to not truncate tip labels. The margin value is specified as a fraction of the overall tree width which is added to the right side of the plot area. So a value of 0. 2 adds twenty percent extra space to the right-hand side of the plot. title (Optional). Default NULL. Character string. The main title for the graphic. treetheme (Optional). A custom ggplot2 theme layer to use for the tree. Supplants any default theme layers used within the function. A value of NULL uses a default, minimal-annotations theme. If anything other than a them or NULL, the current global ggplot2 theme will result. justify (Optional). A character string indicating the type of justification to use on dodged points and tip labels. A value of "jagged", the default, results in these tip-mapped elements being spaced as close to the tips as possible without gaps. Currently, any other value for justify results in a left-justified arrangement of both labels and points.
section_name: Description

section_content: This function received an early development contribution from the work of Gregory Jordan via the ggphylo package. plot_tree has since been re-written. For details see tree_layout. 

Value A ggplot2 plot.
section_name: Details

section_content: There are many useful examples of phyloseq tree graphics in the phyloseq online tutorials.
section_name: plot.phylo

section_name: Examples

section_content: The class of the object returned by prune_samples matches the class of the phyloseq object, x.
section_name: Value

section_content: Examples data(GlobalPatterns) # Subset to just the Chlamydiae phylum. GP. chl <-subset_taxa(GlobalPatterns, Phylum=="Chlamydiae") # Remove the samples that have less than 20 total reads from Chlamydiae GP. chl <-prune_samples(sample_sums(GP. chl)>=20, GP. chl) # (p <-plot_tree(GP. chl, color="SampleType", shape="Family", label. tips="Genus", size="abundance")) psmelt x (Required). A phylogenetic object, including phylo trees, as well as all phyloseq classes that represent taxa. If the function taxa_names returns a non-NULL value, then your object can be pruned by this function.
section_name: See Also subset_samples

section_content: The class of the object returned by prune_taxa matches the class of the argument, x.
section_name: Value

section_content: The psmelt function is a specialized melt function for melting phyloseq objects (instances of the phyloseq class), usually for producing graphics with ggplot2. psmelt relies heavily on the melt and merge functions. The naming conventions used in downstream phyloseq graphics functions have reserved the following variable names that should not be used as the names of sample_variables or taxonomic rank_names. These reserved names are c("Sample", "Abundance", "OTU"). Also, you should not have identical names for sample variables and taxonomic ranks. That is, the intersection of the output of the following two functions sample_variables, rank_names should be an empty vector (e. g. intersect(sample_variables(physeq), rank_names(physeq))). All of these potential name collisions are checked-for and renamed automtically with a warning. However, if you (re)name your variables accordingly ahead of time, it will reduce confusion and eliminate the warnings.
section_name: Description

section_content: Arguments physeq (Required). An otu_table-class or phyloseq-class. Function most useful for phyloseq-class.
section_name: Usage psmelt(physeq)

section_content: Note that "melted" phyloseq data is stored much less efficiently, and so RAM storage issues could arise with a smaller dataset (smaller number of samples/OTUs/variables) than one might otherwise expect. For common sizes of graphics-ready datasets, however, this should not be a problem. Because the number of OTU entries has a large effect on the RAM requirement, methods to reduce the number of separate OTU entries -for instance by agglomerating OTUs based on phylogenetic distance using tip_glom -can help alleviate RAM usage problems. This function is made useraccessible for flexibility, but is also used extensively by plot functions in phyloseq.
section_name: Details

section_name: Value

section_content: Please note that the authors of phyloseq do not advocate using this as a normalization procedure, despite its recent popularity. Our justifications for using alternative approaches to address disparities in library sizes have been made available as an article in PLoS Computational Biology. See phyloseq_to_deseq2 for a recommended alternative to rarefying directly supported in the phyloseq package, as well as the supplemental materials for the PLoS-CB article and the phyloseq extensions repository on GitHub. Nevertheless, for comparison and demonstration, the rarefying procedure is implemented here in good faith and with options we hope are useful. This function uses the standard R sample function to resample from the abundance values in the otu_table component of the first argument, physeq. Often one of the major goals of this procedure is to achieve parity in total number of counts between samples, as an alternative to other formal normalization procedures, which is why a single value for the sample. size is expected. This kind of resampling can be performed with and without replacement, with replacement being the more computationallyefficient, default setting. See the replace parameter documentation for more details. We recommended that you explicitly select a random number generator seed before invoking this function, or, alternatively, that you explicitly provide a single positive integer argument as rngseed.
section_name: Description

section_content: This approach is sometimes mistakenly called "rarefaction", which in physics refers to a form of wave decompression; but in this context, ecology, the term refers to a repeated sampling procedure to assess species richness, first proposed in 1968 by Howard Sanders. In contrast, the procedure implemented here is used as an ad hoc means to normalize microbiome counts that have resulted from libraries of widely-differing sizes. Here we have intentionally adopted an alternative name, rarefy, that has also been used recently to describe this process and, to our knowledge, not previously used in ecology. 

Make sure to use set. seed for exactly-reproducible results of the random subsampling.
section_name: Details

section_content: An object of class phyloseq. Only the otu_table component is modified. . . . (Optional). Additional parameter(s) passed to the relevant tree-importing function.
section_name: Value

section_content: If successful, returns a phylo-class object as defined in the ape-package. Returns NULL if neither tree-reading function worked. 

See Also read_tree_greengenes phylo read. tree read. nexus Examples read_tree(system. file("extdata", "esophagus. tree. gz", package="phyloseq")) read_tree(system. file("extdata", "GP_tree_rand_short. newick. gz", package="phyloseq"))

read_tree_greengenes Read GreenGenes tree released in annotated newick format
section_name: Value

section_content: In principal, this is a standard newick format, that can be imported into R using read_tree, which in-turn utilizes read. tree. However, read. tree has failed to import recent (October 2012 and later) releases of the GreenGenes tree, and this problem has been traced to the additional annotations added to some internal nodes that specify taxonomic classification between single-quotes. To solve this problem and create a clear container for fixing future problems with the format of GreenGenesreleased trees, this function is available in phyloseq and exported for users. It is also referenced in the documentation of the import functions for QIIME legacy and BIOM format importers -import_qiime and import_biom, respectively. However, since the precise format of the tree is not restricted to GreenGenes trees by QIIME or for the biom-format, this function is not called automatically by those aforementioned import functions. If your tree is formatted like, or is one of, the official GreenGenes release trees, then you should use this function and provide its output to your relevant import function. reconcile_categories Cleans absent levels in sample_data/data. frame.
section_name: Description

section_content: This is used internally by the builder method, sample_data, to ensure that the factors describing categorical variables in a data. frame or sample_data object are free of extra levels that can plague downstream plots analysis.
section_name: Description

section_content: Arguments DFSM (Required). A data. frame or sample_data object that needs to be cleaned.
section_name: Usage reconcile_categories(DFSM)

section_content: A single data. frame object. Even if the input argument is a sample_data, the return is a data. frame. 

Because this is intended to be used internally by the builder method, it cannot also call the builder function to re-build the cleaned sample_data.
section_name: Value

section_content: # # # data(GlobalPatterns) # # # SM <-sample_data(GlobalPatterns) # # # DF <-data. frame(SM) # # # DF <-data. frame(DF, col1=1:nrow(DF), col2=paste(1:nrow(DF), "t", sep="")) # # # DF <-reconcile_categories(DF) # # # SM <-sample_data(reconcile_categories(SM))

rm_outlierf rm_outlierf Set to FALSE any outlier species greater than f fractional abundance.
section_name: Examples

section_content: This is for removing overly-abundant outlier taxa, not for trimming low-abundance taxa. show,otu_table-method method extensions to show for phyloseq objects.
section_name: Description

section_content: See the general documentation of show method for expected behavior. Optional). A character string. One of c("farthest", "radial", "square").
section_name: Description

section_content: Default is "farthest". This determines how threshold will be interpreted. 

farthest Unlike the other two options, this option implies removing a certain fraction or number of points from the plot, depending on the value of threshold. If threshold is greater than or equal to 1, then all but threshold number of points farthest from the origin are removed. Otherwise, if threshold is less than 1, all but threshold fraction of points farthests from origin are retained. radial Keep only those points that are beyond threshold radial distance from the origin. Has the effect of removing a circle of points from the plot, centered at the origin. square Keep only those points with at least one coordinate greater than threshold. 

Has the effect of removing a "square" of points from the plot, centered at the origin.
section_name: Usage

section_content: A data. frame suitable for creating a ggplot plot object, graphically summarizing the ordination result according to previously-specified parameters. 

See Also phyloseq online tutorial for this function., where x is the vector of sample IDs and subset is the logical that results from your subsetting expression. This is important to keep in mind, as users are often unaware that this subsetting step also removes/omits samples that have a missing value, NA, somewhere in the expression. 

Usage subset_samples(physeq,. . . ) subset_taxa Arguments physeq A sample_data-class, or a phyloseq-class object with a sample_data. If the sample_data slot is missing in physeq, then physeq will be returned as-is, and a warning will be printed to screen. 

. . . The subsetting expression that should be applied to the sample_data. This is passed on to subset, see its documentation for more details.
section_name: Value

section_content: A subsetted object with the same class as physeq. 

See Also subset_species
section_name: Value

section_content: # data(GlobalPatterns) # subset_samples(GlobalPatterns, SampleType=="Ocean") subset_taxa
section_name: Examples

section_name: Subset species by taxonomic expression

section_content: This is a convenience wrapper around the subset function. It is intended to speed subsetting complex experimental objects with one function call. In the case of subset_taxa, the subsetting will be based on an expression related to the columns and values within the tax_table (taxonomyTable component) slot of physeq. The OTUs retained in the dataset is equivalent to x[subset & !is. na(subset)], where x is the vector of OTU IDs and subset is the logical that results from your subsetting expression. This is important to keep in mind, as users are often unaware that this subsetting step also removes/omits OTUs that have a missing value result, NA, somewhere in the expression. 

Usage subset_taxa(physeq,. . . )
section_name: Description

section_content: A taxonomyTable-class, or phyloseq-class that contains a taxonomyTable. 

If the tax_table slot is missing in physeq, then physeq will be returned as-is and a warning will be printed to screen. 

. . . The subsetting expression that should be applied to the taxonomyTable. This is passed on to subset, and more details and examples about how it functions can be found in its documentation.
section_name: Arguments physeq

section_content: A subsetted object with the same class as physeq. taxonomyTable-class An S4 class that holds taxonomic classification data as a character matrix.
section_name: Value

section_name: See

section_content: Row indices represent taxa, columns represent taxonomic classifiers.
section_name: Description

section_content: . Data This slot is inherited from the matrix class. 

tax_glom Agglomerate taxa of the same type.
section_name: Details

section_content: This method merges species that have the same taxonomy at a certain taxonomic rank. Its approach is analogous to tip_glom, but uses categorical data instead of a tree. In principal, other categorical data known for all taxa could also be used in place of taxonomy, but for the moment, this must be stored in the taxonomyTable of the data. Also, columns/ranks to the right of the rank chosen to use for agglomeration will be replaced with NA, because they should be meaningless following agglomeration. 

Usage tax_glom(physeq, taxrank=rank_names(physeq)[1], NArm=TRUE, bad_empty=c(NA, "", " ", "\t")) NArm (Optional). Logical, length equal to one. Default is TRUE. CAUTION. The decision to prune (or not) taxa for which you lack categorical data could have a large effect on downstream analysis. You may want to re-compute your analysis under both conditions, or at least think carefully about what the effect might be and the reasons explaining the absence of information for certain taxa. In the case of taxonomy, it is often a result of imprecision in taxonomic designation based on short phylogenetic sequences and a patchy system of nomenclature. If this seems to be an issue for your analysis, think about also trying the nomenclatureagnostic tip_glom method if you have a phylogenetic tree available. bad_empty (Optional). Character vector. Default: c(NA, "", " ", "\t"). Defines the bad/empty values that should be ignored and/or considered unknown. They will be removed from the internal agglomeration vector derived from the argument to tax, and therefore agglomeration will not combine taxa according to the presence of these values in tax. Furthermore, the corresponding taxa can be optionally pruned from the output if NArm is set to TRUE.
section_name: Description

section_content: A taxonomically-agglomerated, optionally-pruned, object with class matching the class of physeq. threshrankfun A closure version of the threshrank function.
section_name: Value

section_content: Takes the same arguments as threshrank, except for x, because the output is a single-argument function rather than a rank-transformed numeric. This is useful for higher-order functions that require a single-argument function as input, like transform_sample_counts. 

Usage threshrankfun(thresh, keep0s=FALSE,. . . )

Arguments thresh A single numeric value giving the threshold.
section_name: Description

section_content: All tips of the tree separated by a cophenetic distance smaller than h will be agglomerated into one taxa using merge_taxa. 

Usage tip_glom(physeq, h = 0. 2, hcfun = agnes,. . . )

Arguments physeq (Required). A phyloseq-class, containing a phylogenetic tree. Alternatively, a phylogenetic tree phylo will also work. 

h (Optional). Numeric scalar of the height where the tree should be cut. This refers to the tree resulting from hierarchical clustering of cophenetic. phylo(phy_tree(physeq)), not necessarily the original phylogenetic tree, phy_tree(physeq). Default value is 0. 2. Note that this argument used to be named speciationMinLength, before this function/method was rewritten.
section_name: Description

section_content: Can be used to create a non-trivial OTU Table, if a phylogenetic tree is available. 

For now, a simple, "greedy", single-linkage clustering is used. In future releases it should be possible to specify different clustering approaches available in R, in particular, complete-linkage clustering appears to be used more commonly for OTU clustering applications.
section_name: Details

section_content: An instance of the phyloseq-class. Or alternatively, a phylo object if the physeq argument was just a tree. In the expected-use case, the number of OTUs will be fewer (see ntaxa), after merging OTUs that are related enough to be called the same OTU.
section_name: Value

section_content: This function takes a phylo or phyloseq-class object and returns a list of two data. tables suitable for plotting a phylogenetic tree with ggplot2. 

Usage tree_layout(phy, ladderize = FALSE) Arguments phy (Required). The phylo or phyloseq-class object (which must contain a phylogenetic tree) that you want to converted to data. tables suitable for plotting with ggplot2. ladderize (Optional). Boolean or character string (either FALSE, TRUE, or "left"). Default is FALSE (no ladderization). This parameter specifies whether or not to ladderize the tree (i. e., reorder nodes according to the depth of their enclosed subtrees) prior to plotting. This tends to make trees more aesthetically pleasing and legible in a graphical display. When TRUE or "right", "right" ladderization is used. When set to FALSE, no ladderization is applied. When set to "left", the reverse direction ("left" ladderization) is applied.
section_name: Description

section_content: Arguments physeq (Required). phyloseq-class, containing at minimum a phylogenetic tree (phylo-class) and contingency table (otu_table-class). See examples below for coercions that might be necessary. 

weighted (Optional). Logical. Should use weighted-UniFrac calculation? Weighted-UniFrac takes into account the relative abundance of species/taxa shared between samples, whereas unweighted-UniFrac only considers presence/absence. Default is FALSE, meaning the unweighted-UniFrac distance is calculated for all pairs of samples. normalized (Optional). Logical. Should the output be normalized such that values range from 0 to 1 independent of branch length values? Default is TRUE. Note that (unweighted) UniFrac is always normalized by total branch-length, and so this value is ignored when weighted == FALSE. parallel (Optional). Logical. Should execute calculation in parallel, using multiple CPU cores simultaneously? This can dramatically hasten the computation time for this function. However, it also requires that the user has registered a parallel "backend" prior to calling this function. Default is FALSE. If FALSE, UniFrac will register a serial backend so that foreach::%dopar% does not throw a warning. 

fast (Optional). Logical. DEPRECATED. Do you want to use the "Fast UniFrac" algorithm? Implemented natively in the phyloseq-package. TRUE is now the only supported option. There should be no difference in the output between the two algorithms. Moreover, the original UniFrac algorithm only outperforms this implementation of fast-UniFrac if the datasets are so small (approximated by the value of ntaxa(physeq) * nsamples(physeq)) that the difference in time is inconsequential (less than 1 second). In practice it does not appear that this parameter should have ever been set to FALSE, and therefore the original UniFrac implementation perhaps never should have been supported here. For legacy code support the option is now deprecated here (the implementation was an internal function, anyway) and the fast option will remain for one release cycle before being removed completely in order to avoid causing unsupported-argument errors.
section_name: UniFrac

section_content: UniFrac() accesses the abundance (otu_table-class) and a phylogenetic tree (phylo-class) data within an experiment-level (phyloseq-class) object. If the tree and contingency table are separate objects, suggested solution is to combine them into an experiment-level class using the phyloseq function. For example, the following code phyloseq(myotu_table, myTree) returns a phyloseq-class object that has been pruned and comprises the minimum arguments necessary for UniFrac(). 

Parallelization is possible for UniFrac calculated with the phyloseq-package, and is encouraged in the instances of large trees, many samples, or both. Parallelization has been implemented via the foreach-package. This means that parallel calls need to be preceded by 2 or more commands that # # Now try a parallel implementation using doParallel, which leverages the # # new 'parallel' core package in R 2. 14. 0+ # # Note that simply loading the 'doParallel' package is not enough, you must # # call a function that registers the backend. In general, this is pretty easy # # with the 'doParallel package' (or one of the alternative 'do*' packages) # # # # Also note that the esophagus example has only 3 samples, and a relatively small # # tree. This is fast to calculate even sequentially and does not warrant # # parallelized computation, but provides a good quick example for using UniFrac() # # in a parallel fashion. The number of cores you should specify during the # # backend registration, using registerDoParallel(), depends on your system and # # needs. 3 is chosen here for convenience. If your system has only 2 cores, this # # will probably fault or run slower than necessary.
section_name: Details

section_content: See the documentation for the Extract generic, defined in the R base-package for the expected behavior.
section_name: Description

section_content: ## S4 method for signature 'otu_table,ANY,ANY,ANY'

x [i, j,. . .,
section_name: Usage

section_content: One special exception to standard behavior of these methods in phyloseq is that the drop argument is set internally to FALSE. This helps avoid bugs during complicated subsetting with multiple components, where it is necessary to be able to use a two dimensional indexing even if one of those dimensions has only 1 rank. Put another way, these phyloseq-defined extractions never collapse their result into a vector. See the documentation of Extract for more information about the drop argument. 8, 16, 17, 19, 20, 58, 77, 96 dist-class, 16 distance, 8, 16, 18, 19, 58-60, 77, 78, 93, 96, 104, 147 distance,otu_table,character-method (distance) get_taxa, 31, 32, 33, 34, 86, 112, 124 get_taxa,otu_table-method (get_taxa), 32 get_taxa,phyloseq-method (get_taxa), 32 get_taxa_unique, 33, 86 INDEX sample_names<-,otu_table,character-method (sample_names<-), 122 sample_names<-,phyloseq,character-method (sample_names<-), 122 sample_names<-,sample_data,character-method (sample_names<-), 122 sample_sums, 85, 113, 123, 134 sample_variables, 34, 86, 94, 110, tax_glom, 65, 66, 86, 134 tax_table, 6, 7, 42, 79, 85, 89, 105, 117, 119, 136, 137 tax_table,ANY-method (tax_table), 136 tax_table,data. frame-method (tax_table), 136 tax_table,matrix-method (tax_table), 136 tax_table<-, 86, 137 tax_table<-,phyloseq,ANY-method (tax_table<-), 137 tax_table<-,phyloseq,taxonomyTable-method (tax_table<-), 137 tax_table<-,taxonomyTable,ANY-method (tax_table<-), 137 tax_table<-,taxonomyTable,taxonomyTable-method (tax_table<-), 137 taxa_are_rows, 28, 86, 129, 130 taxa_are_rows,ANY-method (taxa_are_rows), 130 taxa_are_rows,otu_table-method (taxa_are_rows), 130 taxa_are_rows,phyloseq-method (taxa_are_rows), 130 taxa_are_rows<-, 86, 130 taxa_are_rows<-,otu_table,logical-method (taxa_are_rows<-), 130 taxa_are_rows<-,phyloseq,logical-method (taxa_are_rows<-), 130 taxa_names, 31-34, 36, 48, 74, 86, 89, 94, 110, 112, 121, 124, 131, 133, 137 taxa_names,ANY-method (taxa_names), 131 taxa_names,otu_table-method (taxa_names), 131 taxa_names,phylo-method (taxa_names), 131 taxa_names,phyloseq-method (taxa_names), 131 taxa_names,sample_data-method (taxa_names), 131 taxa_names,taxonomyTable-method (taxa_names), 131 taxa_names,XStringSet-method (taxa_names), 131 taxa_names<-, 132 taxa_names<-,ANY,ANY-method (taxa_names<-), 132 taxa_names<-,ANY,character-method (taxa_names<-), 132
section_name: Details

section_name: Extract

section_content: RoxygenNote 6. 1. 1 git_url https://git. bioconductor. org/packages/phyloseq git_branch devel git_last_commit fca5959 git_last_commit_date 2024-10-29 Repository Bioconductor 3. 21 Date/Publication 2025-03-24

section_name: Examples

section_content: # data(GlobalPatterns) GP = GlobalPatterns mergedGP = merge_samples(GlobalPatterns, "SampleType") SD = merge_samples(sample_data(GlobalPatterns), "SampleType") print(SD) print(mergedGP) sample_names(GlobalPatterns) sample_names(mergedGP) identical(SD, sample_data(mergedGP)) # The OTU abundances of merged samples are summed # Let's investigate this ourselves looking at just the top10 most abundance OTUs. . . OTUnames10 = names(sort(taxa_sums(GP), TRUE)[1:10]) GP10 = prune_taxa(OTUnames10, GP) mGP10 = prune_taxa(OTUnames10, mergedGP) ocean_samples = sample_names(subset(sample_data(GP), SampleType=="Ocean")) print(ocean_samples) otu_table(GP10)[, ocean_samples] rowSums(otu_table(GP10)[, ocean_samples]) otu_table(mGP10) ["Ocean", ] merge_taxa

Merge a subset of the species in x into one species/taxa/OTU.
section_name: Examples

section_content: Takes as input an object that describes species/taxa (e. g. phyloseq-class, otu_table-class, phylo-class, taxonomyTable-class), as well as a vector of species that should be merged. It is intended to be able to operate at a low-level such that related methods, such as tip_glom and tax_glom can both reliably call merge_taxa for their respective purposes. 

Usage merge_taxa(x, eqtaxa, archetype=1) ## S4 method for signature 'phyloseq' merge_taxa(x, eqtaxa, archetype = eqtaxa [which. max(taxa_sums(x) [eqtaxa])])

## S4 method for signature 'sample_data' merge_taxa(x, eqtaxa, archetype = 1L) ## S4 method for signature 'otu_table' merge_taxa (x, eqtaxa, archetype = eqtaxa[which. max(taxa_sums(x) [eqtaxa])])

## S4 method for signature 'phylo' prune_taxa Prune unwanted OTUs / taxa from a phylogenetic object.
section_name: Description

section_content: An S4 Generic method for removing (pruning) unwanted OTUs/taxa from phylogenetic objects, including phylo-class trees, as well as native phyloseq package objects. This is particularly useful for pruning a phyloseq object that has more than one component that describes OTUs
section_name: Description

section_content: The phylo-class object contained within physeq; or NULL if physeq does not have a tree. This method stops with an error in the latter NULL case be default, which can be over-ridden by changing the value of errorIfNULL to FALSE. 

See Also
section_name: Value

section_content: The S4 for storing sample variables.
section_name: sample_data-class

section_content: Row indices represent samples, while column indices represent experimental categories, variables (and so forth) that describe the samples.
section_name: Description

section_content: . Data data-frame data, inherited from the data. frame class. 

row. names Also inherited from the data. frame class; it should contain the sample names. 

names Inherited from the data. frame class.
section_name: Details

section_name: sample_data<-Assign (new) sample_data to x

section_content: This replaces the current sample_data component of x with value, if value is a sample_data-class. However, if value is a data. frame, then value is first coerced to a sample_data-class, and then assigned. Alternatively, if value is phyloseq-class, then the sample_data component will first be accessed from value and then assigned. This makes possible some concise assignment/replacement statements when adjusting, modifying, or building subsets of experiment-level data. See some examples below. 

Internally, this re-builds the phyloseq-class object using the standard phyloseq constructor. Thus, index mismatches between sample-describing components will not be allowed, and subsetting will occurr automatically such that only the intersection of sample IDs are included in any components. This has the added benefit of re-checking (internally) for any other issues.
section_name: Description

section_name: Usage sample_data(x) <-value

section_content: x (Required). phyloseq-class. The object to modify. value (Required). Either a sample_data-class, a data. frame that can be coerced into sample_data-class, or a phyloseq-class that contains a suitable sample_data component to assign to x. If unsure, try sample_data(value), which should return a sample_data-class object without error.
section_name: Arguments

section_content: No return. This is an assignment statement.
section_name: Value

section_content: This function calculates the (Fast) UniFrac distance for all sample-pairs in a phyloseq-class object.
section_name: Description

section_content: UniFrac(physeq, weighted=FALSE, normalized=TRUE, parallel=FALSE, fast=TRUE) ## S4 method for signature 'phyloseq' UniFrac(physeq, weighted = FALSE, normalized = TRUE, parallel = FALSE, fast = TRUE) register the parallel "backend". This is acheived via your choice of helper packages. One of the simplest seems to be the doParallel package. 

For more information, see the following links on registering the "backend": 55, [90] [91] [92] 94, 95, 97, 98, 100, 103, 104, 107, 110, 126, 127, 144 ggsave, 12 hclust, 140 identical, 40 igraph, 95 import, 34, 38, 39, 51, 52, 56, 93 import_biom, 7, 35, 36, 37, 40, 47, 50, 56, 68, 81, 82, 115 import_env_file, 22, 39, 51, 52 import_mothur, 35, 40, [42] [43] [44] [45] [46] 8, 76, 94, 99, 104 otu_table, 5, 8, 20, 22, 41, 45, 46, 53, 55, 78, 85, 86, 89, 93, 112, 117, 119, 130, 135, 5, 20, 79, 85, 86, 88, 105, 117, 119, 136 phy_tree,ANY-method (phy_tree), 88 phy_tree,phylo-method (phy_tree), 88 phy_tree<-, 86, 89 phy_tree<-,phyloseq,phylo-method (phy_tree<-), 89 phy_tree<-,phyloseq,phyloseq-method (phy_tree<-), 89 phylo, 20, 36, 41, 48, 64, 66, 75, 82, 82, 83-85, 88, 89, 115-117, 132, 140, 144 phylo-class, 83 phyloseq, 42, 49, 51, 52, 55, 61, 79, 83, 84, 85, 89, 117, 119, 120, 136, 146 phyloseq-class, 84, 125 86, 93, 94, 110, 111 rarefy_even_depth, 112 rda, 8, 9, 76, 77 rda. phyloseq (cca. phyloseq), 8 read. nexus, 114, 115 read. table, 39, 51, 55 read. tree, 114, 115 read_biom, 38 read_tree, [36] [37] [38] 40, 48, 49, 51, 114, 115 read_tree_greengenes, 36, 38, 48, 49, 51, 115, 115 readDNAStringSet, 37, 8, 9, 70, 74, 79, 85, 87, 89, 105, 116, 117, 119, 120, 121, 127, 136 sample_data,ANY-method (sample_data), 119 sample_data,data. frame-method (sample_data), 119 sample_data-class, 120 sample_data<-, 86, 120 sample_metadata, 38 sample_names, 31-34, 74, 86, 94, 112, 119, 121, 122, 124 sample_names,ANY-method (sample_names), 121 sample_names,otu_table-method (sample_names), 121 sample_names,phyloseq-method (sample_names), 121 sample_names,sample_data-method (sample_names), 121 sample_names<-, 122 sample_names<-,ANY,ANY-method (sample_names<-), 122 sample_names<-,ANY,character-method (sample_names<-), 122
section_name: Usage