Merge pull request #25 from microbiomeDB/examples

examples etc

.gitignore

@@ -48,3 +48,4 @@ po/*~
 # RStudio Connect folder
 rsconnect/
 docs
+inst/doc

DESCRIPTION

@@ -14,13 +14,15 @@ Imports:
     igraph,
     veupathUtils,
     Maaslin2,
+    methods,
     microbiomeComputations,
     phyloseq,
     purrr
 Remotes:
     VEuPathDB/veupathUtils,
     microbiomeDB/corGraph,
-    microbiomeDB/microbiomeComputations
+    microbiomeDB/microbiomeComputations,
+    microbiomeDB/microbiomeData
 URL: https://github.com/microbiomeDB/MicrobiomeDB, https://microbiomedb.github.io/MicrobiomeDB/
 BugReports: https://github.com/microbiomeDB/MicrobiomeDB/issues
 Description: This package is intended to be used to explore the curated datasets from MicrobiomeDB.org, as well as your own datasets. It comes pre-packaged with the same functions used to power the analysis tools from the website. It also contains functions to facilitate easily transforming data between our custom objects, phyloseq objects, and .biom files that you can upload to the website.
@@ -30,5 +32,10 @@ Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.1
 Suggests: 
     testthat (>= 3.0.0),
-    S4Vectors
+    S4Vectors,
+    microbiomeData,
+    knitr,
+    rmarkdown,
+    tidyverse
 Config/testthat/edition: 3
+VignetteBuilder: knitr

NAMESPACE

@@ -16,6 +16,7 @@ export(selfCorrelation)
 export(updateCollectionName)
 exportMethods(getCollectionNames)
 exportMethods(getMetadataVariableNames)
+exportMethods(getMetadataVariableSummary)
 exportMethods(getSampleMetadata)
 import(data.table)
 importFrom(DESeq2,DESeqDataSetFromMatrix)
@@ -47,6 +48,7 @@ importFrom(veupathUtils,getCollectionNames)
 importFrom(veupathUtils,getDataFromSource)
 importFrom(veupathUtils,getIdColumns)
 importFrom(veupathUtils,getMetadataVariableNames)
+importFrom(veupathUtils,getMetadataVariableSummary)
 importFrom(veupathUtils,getSampleMetadata)
 importFrom(veupathUtils,getSampleMetadataIdColumns)
 importFrom(veupathUtils,matchArg)

R/method-differentialAbundance.R

@@ -72,7 +72,35 @@ buildBinaryComparator <- function(covariate, groupAValue, groupBValue) {
 #' about the data which may not be valid in other contexts. For better support of 
 #' longitudinal studies or metabolomic data, for example, please see our wrapper/ helper methods 
 #' for Maaslin2 (\code{MicrobiomeDB::Maaslin2}) and DESeq2 (\code{DESeqDataSetFromCollection}).
+#'
+#' @examples 
+#' ## a continuous variable
+#' diffAbundOutput <- MicrobiomeDB::differentialAbundance(
+#'        getCollection(microbiomeData::DiabImmune, '16S (V4) Genus'), 
+#'        "breastfed_duration_days", 
+#'        groupA = function(x) {x<300},
+#'        groupB = function(x) {x>=300},
+#'        method='Maaslin2', 
+#'        verbose=TRUE
+#' )
+#' 
+#' ## a categorical variable with 3 values, one of which we exclude
+#' diffAbundOutput <- MicrobiomeDB::differentialAbundance(
+#'        getCollection(microbiomeData::DiabImmune, '16S (V4) Genus'), 
+#'        "country", 
+#'        groupA = function(x) {x=="Russia"},
+#'        groupB = function(x) {x=="Finland"},
+#'        method='Maaslin2', 
+#'        verbose=FALSE
+#' )
 #' 
+#' ## a categorical variable with 2 values
+#' diffAbundOutput <- MicrobiomeDB::differentialAbundance(
+#'        getCollection(microbiomeData::DiabImmune, '16S (V4) Genus'),
+#'        "delivery_mode",
+#'        method='Maaslin2', 
+#'        verbose=FALSE
+#' ) 
 #' @param data AbundanceData object
 #' @param covariate character vector giving the name of a metadata variable of interest. If this 
 #' variable has only two values, you do not need to provide functions for arguments `groupA` and `groupB`.
@@ -160,6 +188,17 @@ function(data, covariate, groupA, groupB, method = c("Maaslin2", "DESeq2"), verb
 #' analysis methods (including support for multiple covariates and repeated measures)
 #' filtering, normalization, and transform options to customize analysis for your specific study.
 #' 
+#' @examples
+#' maaslinOutput <- MicrobiomeDB::Maaslin2(
+#'        data = getCollection(microbiomeData::DiabImmune, '16S (V4) Genus'), 
+#'        output = tempfile("maaslin"),
+#'        #min_prevalence = 0,
+#'        fixed_effects = 'delivery_mode',
+#'        analysis_method = "LM", # default LM
+#'        normalization = "TSS", # default TSS
+#'        transform = "LOG", # default LOG
+#'        plot_heatmap = FALSE,
+#'        plot_scatter = FALSE)
 #' @param data a CollectionWithMetadata
 #' @param verbose boolean indicating if timed logging is desired
 #' @param ... additional arguments to pass to Maaslin2::Maaslin2

R/methods-ComputeResult.R

@@ -2,6 +2,15 @@
 #' 
 #' Get the compute result from a Microbiome Dataset in a particular format.
 #' Some formats may not be supported for all compute results.
+#' 
+#' @examples 
+#' correlationOutput <- MicrobiomeDB::selfCorrelation(
+#'      getCollection(microbiomeData::DiabImmune, "16S (V4) Genus"), 
+#'      method='spearman', 
+#'      verbose=FALSE
+#' )
+#' correlationDT <- getComputeResult(correlationOutput, "data.table")
+#' correlationIGraph <- getComputeResult(correlationOutput, "igraph")
 #' @param object A Microbiome Dataset
 #' @param format The format of the compute result. Currently only "data.table" and "igraph" are supported.
 #' @param ... additional arguments passed to getComputeResult method of the subclasses of ComputeResult
@@ -74,6 +83,19 @@ mergeComputeResultAndMetadata <- function(computeResult, dataset, metadataVariab
 #' Get Microbiome Dataset Compute Result With Metadata
 #' 
 #' Get the compute result from a Microbiome Dataset in a particular format with metadata.
+#' 
+#' @examples 
+#' alphaDivOutput <- MicrobiomeDB::alphaDiv(
+#'      getCollection(microbiomeData::DiabImmune, "16S (V4) Genus"), 
+#'      method='shannon', 
+#'      verbose=FALSE
+#' )
+#' 
+#' alphaDivDT <- getComputeResultWithMetadata(
+#'      alphaDivOutput, 
+#'      microbiomeData::DiabImmune, 
+#'      metadataVariables = c('country', 'delivery_mode')
+#' )
 #' @param object A Microbiome Dataset
 #' @param dataset The MbioDataset, AbundanceData or Collection object from which the compute result was obtained.
 #' @param format The format you want the compute result in. Currently only "data.table" is supported.
@@ -120,6 +142,14 @@ function(object, dataset = NULL, format = c("data.table"), metadataVariables = N
 #' Correlation Network Visualization
 #' 
 #' Visualize a correlation result as a network
+#' 
+#' @examples 
+#' correlationOutput <- MicrobiomeDB::correlation(
+#'      getCollection(microbiomeData::DiabImmune, "16S (V4) Genus", continuousMetadataOnly = TRUE), 
+#'      method='spearman', 
+#'      verbose=FALSE
+#' )
+#' correlationNetwork(correlationOutput) ## renders html widget
 #' @param object A ComputeResult or data.frame
 #' @param correlationCoefThreshold threshold to filter edges by correlation coefficient.
 #' Edges with correlation coefficients below this threshold will be removed. Default is .5

R/methods-MbioDataset.R

@@ -2,6 +2,9 @@ collectionNamesGeneric <- getGeneric("getCollectionNames", "veupathUtils")
 #' Get Names of Collections
 #' 
 #' Get the names of the collections in a MbioDataset object
+#' 
+#' @examples 
+#' getCollectionNames(microbiomeData::DiabImmune)
 #' @param object An MbioDataset
 #' @return A character vector of collection names
 #' @export
@@ -12,6 +15,9 @@ metadataVarNamesGeneric <- getGeneric("getMetadataVariableNames", "veupathUtils"
 #' Get Variable Names of Metadata
 #' 
 #' Get the names of the metadata variables in an MbioDataset.
+#' 
+#' @examples 
+#' getMetadataVariableNames(microbiomeData::DiabImmune)
 #' @param object An MbioDataset
 #' @return a character vector of metadata variable names
 #' @export
@@ -22,6 +28,11 @@ metadataVarSummaryGeneric <- getGeneric("getMetadataVariableSummary", "veupathUt
 #' Get Summary of Metadata Variables
 #' 
 #' Get a summary of the requested metadata variable in an MbioDataset.
+#' 
+#' @examples 
+#' getMetadataVariableSummary(microbiomeData::DiabImmune, "age_months")
+#' getMetadataVariableSummary(microbiomeData::DiabImmune, "sex")
+#' getMetadataVariableSummary(microbiomeData::DiabImmune, "country")
 #' @param object An MbioDataset
 #' @param variable A character vector representing the name of the metadata variable to summarize
 #' @return a table summarizing the values of the requested metadata variable
@@ -48,6 +59,9 @@ sampleMetadataGeneric <- getGeneric("getSampleMetadata", "veupathUtils")
 #'
 #' Returns a data.table of sample metadata
 #' 
+#' @examples
+#' getSampleMetadata(microbiomeData::DiabImmune)
+#' getSampleMetadata(microbiomeData::DiabImmune, metadataVariables = c("age_months", "sex"))
 #' @param object MbioDataset
 #' @param asCopy boolean indicating whether to return the data as a copy or by reference
 #' @param includeIds boolean indicating whether we should include recordIdColumn and ancestorIdColumns
@@ -95,6 +109,10 @@ setMethod(metadataIdColsGeneric, "MbioDataset", function(object) veupathUtils::g
 #' Update Microbiome Dataset Collection Name
 #' 
 #' Update the name of a collection in the Microbiome Dataset.
+#' 
+#' @examples
+#' myCopyOfDiabImmune <- microbiomeData::DiabImmune
+#' myCopyOfDiabImmune <- updateCollectionName(myCopyOfDiabImmune, "16S (V4) Genus", "16S Genus")
 #' @param object A Microbiome Dataset
 #' @param oldName The name of the collection to update
 #' @param newName The new name of the collection
@@ -114,6 +132,32 @@ setMethod("updateCollectionName", "MbioDataset", function(object, oldName, newNa
 #' 
 #' Get a collection from the Microbiome Dataset. The collection will be returned
 #' as an AbundanceData, phyloseq, or Collection object.
+#' 
+#' @examples
+#' genus <- getCollection(
+#'      microbiomeData::DiabImmune, 
+#'      "16S (V4) Genus"
+#' )
+#' 
+#' genus_phyloseq <- getCollection(
+#'      microbiomeData::DiabImmune, 
+#'      "16S (V4) Genus", 
+#'      format = "phyloseq"
+#' )
+#' 
+#' ## to pass to correlation method, we want only continuous metadata
+#' genus_continuous <- getCollection(
+#'      microbiomeData::DiabImmune, 
+#'      "16S (V4) Genus", 
+#'      continuousMetadataOnly = TRUE
+#' ) 
+#' 
+#' ## with no metadata
+#' genus_collection <- getCollection(
+#'      microbiomeData::DiabImmune, 
+#'      "16S (V4) Genus", 
+#'      format = "Collection"
+#' )
 #' @param object A Microbiome Dataset
 #' @param collectionName The name of the collection to return
 #' @param format The format of the collection to return. Currently supported options are "AbundanceData", "phyloseq" and "Collection".

R/reexports-microbiomeComputations.R

@@ -1,20 +1,131 @@
+#' Ranked abundance
+#'
+#' This function returns abundances, ranked by a selected ranking function
+#' 
+#' @examples
+#' rankedAbundOutput <- rankedAbundance(
+#'      getCollection(microbiomeData::DiabImmune, "16S (V4) Genus"), 
+#'      method = "median"
+#' )
+#' @param data AbundanceData object
+#' @param method string defining the ranking strategy by which to order the taxa. Accepted values are 'median','max','q3',and 'variance'. Note that taxa that return a value of 0 for a given method will not be included in the results.
+#' @param cutoff integer indicating the maximium number of taxa to be kept after ranking.
+#' @param verbose boolean indicating if timed logging is desired
+#' @return ComputeResult object
 #' @importFrom microbiomeComputations rankedAbundance
 #' @export
+#' @rdname rankedAbundance-methods
 microbiomeComputations::rankedAbundance
 
+#' Alpha diversity
+#'
+#' This function returns alpha diversity values for each sample.
+#' 
+#' @examples
+#' alphaDivOutput <- alphaDiv(
+#'      getCollection(microbiomeData::DiabImmune, "16S (V4) Genus"), 
+#'      method = "shannon"
+#' )
+#' @param data AbundanceData object
+#' @param method string defining the the alpha diversity method. Accepted values are 'shannon','simpson', and 'evenness'
+#' @param verbose boolean indicating if timed logging is desired
+#' @return ComputeResult object
 #' @importFrom microbiomeComputations alphaDiv
 #' @export
+#' @rdname alphaDiv-methods
 microbiomeComputations::alphaDiv
 
+#' Beta diversity
+#'
+#' This function returns pcoa coordinates calculated from the beta diversity dissimilarity matrix.
+#' 
+#' @examples 
+#' betaDivOutput <- betaDiv(
+#'      getCollection(microbiomeData::DiabImmune, "16S (V4) Genus"), 
+#'      method = "bray", 
+#'      k = 2
+#' )
+#' @param data AbundanceData object
+#' @param method string defining the the beta diversity dissimilarity method. Accepted values are 'bray','jaccard', and 'jsd'
+#' @param k integer determining the number of pcoa axes to return
+#' @param verbose boolean indicating if timed logging is desired
+#' @return ComputeResult object
 #' @importFrom microbiomeComputations betaDiv
 #' @export
+#' @rdname betaDiv-methods
 microbiomeComputations::betaDiv
 
+#' Correlation
+#'
+#' This function returns correlation coefficients for variables in one dataset against variables in a second dataset
+#' 
+#' @examples
+#' diabImmune_genus <- getCollection(
+#'      microbiomeData::DiabImmune, 
+#'      "16S (V4) Genus", 
+#'      continuousMetadataOnly = TRUE
+#' )
+#' 
+#' correlationDT <- correlation(
+#'      diabImmune_genus, 
+#'      method = 'spearman', 
+#'      format = 'data.table'
+#' )
+#' 
+#' correlationOutput <- correlation(
+#'      diabImmune_genus, 
+#'      method = 'spearman', 
+#'      format = 'ComputeResult'
+#' )
+#' 
+#' alsoCorrelationDT <- getComputeResult(
+#'      correlationOutput, 
+#'      "data.table"
+#' )
+#' @param data1 first dataset. A data.table
+#' @param data2 second dataset. A data.table
+#' @param method string defining the type of correlation to run. 
+#' The currently supported values are specific to the class of data1 and data2.
+#' @param format string defining the desired format of the result. 
+#' The currently supported values are 'data.table' and 'ComputeResult'.
+#' @param verbose boolean indicating if timed logging is desired
+#' @param ... additional parameters
+#' @return data.frame with correlation coefficients or a ComputeResult object
 #' @importFrom veupathUtils correlation
 #' @export
+#' @rdname correlation-methods
 veupathUtils::correlation
 
+#' Self Correlation
+#'
+#' This function returns correlation coefficients for variables in one AbundanceData object against itself. It generally serves as a 
+#' convenience wrapper around veupathUtils::correlation, with the exception that it additionally supports sparcc.
+#' 
+#' @examples
+#' correlationDT <- selfCorrelation(
+#'      getCollection(microbiomeData::DiabImmune, "16S (V4) Genus"), 
+#'      method = 'sparcc', 
+#'      format = 'data.table'
+#' )
+#' 
+#' correlationOutput <- selfCorrelation(
+#'      getCollection(microbiomeData::DiabImmune, "16S (V4) Genus"), 
+#'      method = 'sparcc', 
+#'      format = 'ComputeResult'
+#' )
+#' 
+#' alsoCorrelationDT <- getComputeResult(
+#'      correlationOutput, 
+#'      "data.table"
+#' )
+#' @param data An AbundanceData object
+#' @param method string defining the type of correlation to run. The currently supported values are 'spearman','pearson' and 'sparcc'
+#' @param format string defining the desired format of the result. The currently supported values are 'data.table' and 'ComputeResult'.
+#' @param verbose boolean indicating if timed logging is desired
+#' @param ... additional parameters
+#' @return ComputeResult object
 #' @importFrom veupathUtils selfCorrelation
 #' @importFrom microbiomeComputations selfCorrelation
 #' @export
+#' @rdname selfCorrelation-methods
 veupathUtils::selfCorrelation