Merge pull request #6 from blekhmanlab/2_datasets

Laura revisions

.gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+.Rhistory
+

DESCRIPTION

@@ -1,10 +1,10 @@
 Package: biomehorizon
-Title: Plot Microbiome Time Series 
-Version: 0.0.0.9000
+Title: Plot Microbiome Time Series
+Version: 1.0.0.0000
 Authors@R: person("Isaac", "Fink", email = "[email protected]", role = c("aut", "cre"))
-Description: This package provides a toolset for visualizing longitudinal microbiome data with a horizon 
-  plot. A horizon plot provides a compact method to display change in the distribution of microbial taxa 
-  over time. This method is valuable for highlighting changes in individual taxa, but more importantly, 
+Description: This package provides a toolset for visualizing longitudinal microbiome data with a horizon
+  plot. A horizon plot provides a compact method to display change in the distribution of microbial taxa
+  over time. This method is valuable for highlighting changes in individual taxa, but more importantly,
   emphasizes broad trends among groups of taxa. This package can also be used to visualize other types of
   longitudinal data.
 Depends: R (>= 3.5.2)
@@ -16,8 +16,7 @@ Imports:
   magrittr
 Suggests:
   RColorBrewer
-License: What license is it under?
+License: MIT
 Encoding: UTF-8
 LazyData: true
-RoxygenNote: 6.1.1
-
+RoxygenNote: 7.1.1

LICENSE

@@ -0,0 +1,9 @@
+Copyright 2021 Regents of the University of Minnesota
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+End license text.

R/BiomeHorizon.R

@@ -172,58 +172,60 @@
 #' @examples
 #' # Pass just the OTU table to prepanel, and it will assume all samples belong
 #' # to the same subject.
-#' prepanel(otusample)
+#' prepanel(otusample = otusample_diet)
 #'
 #' # Supplement metadata and a subject name, and it will select samples from
 #' # just one subject (this is what you should do with more than one subject).
-#' prepanel(otusample, metadatasample, subj="subject_1")
+#' prepanel(otusample = otusample_diet, metadatasample = metadatasample_diet, subj="MCTs01")
 #'
 #' # Pass taxonomydata to prepanel if you want to label facets by taxonomy
 #' # rather than by OTU ID.
-#' prepanel(otusample, metadatasample, taxonomysample, subj="subject_1",
-#' facetLabelsByTaxonomy=TRUE)
+#' prepanel(otusample = otusample_diet, metadatasample = metadatasample_diet, 
+#' taxonomydata = taxonomysample_diet, subj="MCTs01", facetLabelsByTaxonomy=TRUE)
 #'
 #' # OTU filtering using both a prevalence and an abundance standard (default)
-#' prepanel(otusample, metadatasample, subj="subject_2", thresh_prevalence=75,
-#' thresh_abundance=0.75)
+#' prepanel(otusample = otusample_diet, metadatasample = metadatasample_diet, subj="MCTs01", 
+#' thresh_prevalence=75, thresh_abundance=0.75)
 #'
 #' # OTU filtering using just an abundance standard
-#' prepanel(otusample, metadatasample, subj="subject_2", thresh_prevalence=NA,
-#' thresh_abundance=0.75)
+#' prepanel(otusample = otusample_diet, metadatasample = metadatasample_diet, subj="MCTs01",
+#' thresh_prevalence=NA, thresh_abundance=0.75)
 #'
 #' # If an OTU's average abundance reaches a high enough threshold, override
 #' # other standards and include it in analysis
-#' prepanel(otusample, metadatasample, subj="subject_2", thresh_prevalence=90,
-#' thresh_abundance=0.75, thresh_abundance_override=1.5)
+#' prepanel(otusample = otusample_diet, metadatasample = metadatasample_diet, subj="MCTs01", 
+#' thresh_prevalence=90, thresh_abundance=0.75, thresh_abundance_override=1.5)
 #'
 #' # Filter OTUs where >2% samples are NA values
-#' prepanel(otusample, metadatasample, subj="subject_2", thresh_NA=2)
+#' prepanel(otusample = otusample_diet, metadatasample = metadatasample_diet, subj="MCTs01", 
+#' thresh_NA=2)
 #'
 #' # You can also manually select OTUs by OTU ID
-#' prepanel(otusample, metadatasample, subj="subject_2",
-#' otulist=c("otu_1000","otu_1243","otu_1530","otu_6821","otu_7737"))
+#' prepanel(otusample = otusample_diet, metadatasample = metadatasample_diet, subj="MCTs01",
+#' otulist=c("taxon 1", "taxon 2", "taxon 10", "taxon 14"))
 #'
 #' # Manual selection can be used to specify the order OTUs will appear on
 #' # the horizon plot. For example, these two datasets have identical OTUs, but
 #' # they are ordered differently.
-#' params <- prepanel(otusample, metadatasample, subj="subject_1",
-#' thresh_prevalence=95, thresh_abundance=1.5)
+#' params <- prepanel(otusample = otusample_diet, metadatasample = metadatasample_diet, 
+#' subj="MCTs01", thresh_prevalence=95, thresh_abundance=1.5, 
+#' otulist=c("taxon 1", "taxon 2", "taxon 10", "taxon 14"))
 #' params[[1]]$otuid
-#' params <- prepanel(otusample, metadatasample, subj="subject_1",
-#' otulist=c("otu_2526","otu_1530", "otu_7737", "otu_6821", "otu_3773",
-#' "otu_2457", "otu_1243", "otu_2378"))
+#' params <- prepanel(otusample = otusample_diet, metadatasample = metadatasample_diet, 
+#' subj="MCTs01", otulist=c("taxon 10", "taxon 2", "taxon 1", "taxon 14"))
 #' params[[1]]$otuid
 #'
 #' # The origin and band.thickness variables can be set to either a numeric
 #' # constant or a function that evaluates separately for every OTU subpanel based
 #' # on its sample values.
 #'
 #' # Use a fixed origin of 5% for all OTU subpanels
-#' prepanel(otusample, metadatasample, subj="subject_1", origin=5)
+#' prepanel(otusample = otusample_diet, metadatasample = metadatasample_diet, 
+#' subj="MCTs01", origin=5)
 #'
 #' # Evaluate a different origin for each OTU subpanel using a custom function
-#' prepanel(otusample, metadatasample, subj="subject_1",
-#' origin=function(y){mad(y, na.rm=TRUE)})
+#' prepanel(otusample = otusample_diet, metadatasample = metadatasample_diet, 
+#' subj="MCTs01", origin=function(y){mad(y, na.rm=TRUE)})
 #'
 #' @import dplyr
 #' @importFrom magrittr %>%
@@ -462,9 +464,9 @@ prepanel <- function(otudata, metadata=NA, taxonomydata=NA,
     otudata <- otudata %>% dplyr::filter(otuid == singleVarOTU)
   }
 
-  # Covert otudata format for single variable analysis
+  # Covert otudata format for single variable analysis. Remove extra metadata columns
   if(!is.na(singleVarOTU)) {
-    samplenames <- metadata %>% dplyr::select(-collection_date) %>% dplyr::group_by(subject) %>% dplyr::mutate(row_id=1:dplyr::n()) %>% dplyr::ungroup() %>% tidyr::spread(subject,sample) %>% dplyr::select(-row_id) %>% t() %>% as.data.frame() %>% tibble::rowid_to_column("otuid")
+    samplenames <- metadata %>% dplyr::select(subject, sample) %>% dplyr::group_by(subject) %>% dplyr::mutate(row_id=1:dplyr::n()) %>% dplyr::ungroup() %>% tidyr::spread(subject,sample) %>% dplyr::select(-row_id) %>% t() %>% as.data.frame() %>% tibble::rowid_to_column("otuid")
     ids <- samplenames$otuid
     samplenames <- samplenames %>% dplyr::select(-otuid)
     otudata <- matrix(otudata[1,][c(as.matrix(samplenames))],nrow(samplenames)) %>% as.data.frame() %>% dplyr::mutate(otuid=ids) %>% dplyr::select(otuid,everything())
@@ -730,17 +732,18 @@ prepanel <- function(otudata, metadata=NA, taxonomydata=NA,
 #'
 #' @examples
 #' # Basic plot form. By default, samples are plotted next to each other.
-#' plist <- prepanel(otusample, metadatasample, taxonomysample, subj = "subject_4")
+#' plist <- prepanel(otudata = otusample_diet, metadata = metadatasample_diet,
+#' taxonomysample = taxonomysample_diet, subj = "MCTs16")
 #' horizonplot(plist)
 #'
 #' # For irregularly spaced time series, you can "regularize" the data to create
 #' # an accurate timescale.
 #'
-#' # Adjust data to regular time intervals each 100 days. This will interpolate
-#' # new data points for each OTU at day = 1, 101, 201, etc. based on values
+#' # Adjust data to regular time intervals each 1 day. This will interpolate
+#' # new data points for each OTU at day = 1, 2, 3 etc. based on values
 #' # at previous and subsequent timepoints.
-#' plist <- prepanel(otusample, metadatasample, taxonomysample, subj="subject_4",
-#'                   regularInterval = 100)
+#' plist <- prepanel(otudata = otusample_diet, metadata = metadatasample_diet, 
+#'                   subj = "MCTs16", regularInterval = 1)
 #' horizonplot(plist)
 #'
 #' # If the data has large gaps of time without samples, interpolating data
@@ -750,14 +753,15 @@ prepanel <- function(otudata, metadata=NA, taxonomydata=NA,
 #' # data will be regularized separately on both sides of the break in two
 #' # different facets.
 #'
-#' # Set maximum time without samples to 200 days
-#' plist <- prepanel(otusample, metadatasample, taxonomysample, subj="subject_4",
-#'                   regularInterval = 100, maxGap = 200)
+#' # Set maximum time without samples to 75 days
+#' plist <- prepanel(otudata = otusample_baboon, metadata = metadatasample_baboon, 
+#'                   subj = "Baboon_388", regularInterval = 25, maxGap = 75)
 #' horizonplot(plist)
 #'
 #' # Remove facets with less than 5 samples
-#' plist <- prepanel(otusample, metadatasample, taxonomysample, subj="subject_4",
-#'                   regularInterval = 100, maxGap = 200, minSamplesPerFacet = 5)
+#' plist <- prepanel(otudata = otusample_baboon, metadata = metadatasample_baboon, 
+#'                   subj = "Baboon_388", regularInterval = 25, maxGap = 75, 
+#'                   minSamplesPerFacet = 5)
 #' horizonplot(plist)
 #'
 #' @import ggplot2
@@ -998,7 +1002,7 @@ horizonplot <- function(parameterList, aesthetics=horizonaes()) {
     geom_area(aes(x = as.numeric(day), y = value, fill=band), position="identity", color=col.outline) +
     scale_fill_manual(values=col.bands,breaks=names(col.bands)[c((2*nbands):(1+nbands),nbands:1)],labels=c(paste("+",nbands:1,sep=""),(-1):(-1*nbands))) +
     theme_bw() +
-    theme(axis.text.x=element_text(size=16), axis.text.y=element_blank(), axis.ticks.y=element_blank(), panel.grid=element_blank(), panel.border=element_rect(color=col.border), strip.text.y=element_text(angle=180), panel.spacing.y=unit(0, units="cm"), legend.position=legendPosition) +
+    theme(axis.text.x=element_text(size=16), axis.text.y=element_blank(), axis.ticks.y=element_blank(), panel.grid=element_blank(), panel.border=element_rect(color=col.border), strip.text.y.left=element_text(angle=0), panel.spacing.y=unit(0, units="cm"), legend.position=legendPosition) +
     scale_y_continuous(expand = c(0,0)) + scale_x_continuous(expand = c(0,0)) + # remove margins between plot and panel
     xlab(ifelse(is.na(timestamps), "Sample", "Day")) +
     ylab(element_blank())
@@ -1048,8 +1052,9 @@ horizonplot <- function(parameterList, aesthetics=horizonaes()) {
 #' horizon plot, but if you want to add other aesthetics not included in this
 #' function, you can do so by appending them to the horizon plot object using
 #' the \code{+} operator. e.g. to add a gray background in the plotting area:\cr
-#' \code{horizonplot(prepanel(otusample, metadatasample, taxonomysample,
-#' subj="subject_1")) + theme(panel.background = element_rect(fill="gray90"))}
+#' \code{horizonplot(prepanel(otudata = otusample_diet, 
+#' metadata = metadatasample_diet, taxonomydata = taxonomysample_diet, 
+#' subj = "MCTs01")) + theme(panel.background = element_rect(fill="gray90"))}
 #'
 #' @param title character. The text for the title.
 #' @param subtitle character. The text for the subtitle, displayed below the title.
@@ -1089,7 +1094,8 @@ horizonplot <- function(parameterList, aesthetics=horizonaes()) {
 #'   to apply the aesthetics.
 #'
 #' @examples
-#' plist <- prepanel(otusample, metadatasample, taxonomysample, subj = "subject_2")
+#' plist <- prepanel(otudata = otusample_diet, metadata = metadatasample_diet, 
+#' taxonomydata = taxonomysample_diet, subj = "MCTs01")
 #'
 #' # By default, the function is called with no arguments to use default aesthetics
 #' horizonplot(plist, horizonaes())

R/metadatasample_baboon-data.R

@@ -0,0 +1,22 @@
+#' Metadata on samples from OTU table of wild baboon data
+#'
+#' Metadata providing subject names and collection dates of samples from the
+#' OTU table.
+#'
+#' @docType data
+#'
+#' @usage data(metadatasample_baboon)
+#'
+#' @format A data frame with 276 rows and 7 variables:
+#' \describe{
+#'   \item{subject}{subject name}
+#'   \item{sample}{sample ID corresponding to a variable name from \code{otusample_baboon}}
+#'   \item{collection_date}{number of days into the study the sample was collected}
+#'   \item{sex}{if subject was male or female}
+#'   \item{season}{if sample was collected in the wet or dry season}
+#'   \item{rain_month_mm}{amount of rainfall in mm for month prior to sample collection}
+#'   \item{diet_PC1}{a measure of dietary composition for a sample}
+#' }
+#'
+#' @keywords datasets
+"metadatasample_baboon"

R/metadatasample_diet-data.R

@@ -0,0 +1,19 @@
+#' Metadata on samples from OTU (or other lowest taxonomic level) table of human diet data
+#'
+#' Metadata providing subject names and collection dates of samples from the
+#' OTU table.
+#'
+#' @docType data
+#'
+#' @usage data(metadatasample_diet)
+#'
+#' @format A data frame with 483 rows and 4 variables:
+#' \describe{
+#'   \item{subject}{subject name in character format}
+#'   \item{sample}{sample ID in character format corresponding to a variable name from \code{otusample_diet}}
+#'   \item{collection_date}{number of days in numeric format into the study the sample was collected}
+#'   \item{supplement}{metadata variable in character format indicating if subject was given EVOO or MCT as a dietary supplement on days 10-17}
+#' }
+#'
+#' @keywords datasets
+"metadatasample_diet"

R/otusample_baboon-data.R

@@ -0,0 +1,14 @@
+#' Sample OTU table
+#'
+#' Sample OTU-format table with 6 subjects. The first variable contains OTU IDs.
+#' Each subsequent column represents a unique sample collected at a specific time
+#' from one of 6 subjects' microbiomes. Entries represent number of reads per sample per OTU.
+#'
+#' @docType data
+#'
+#' @usage data(otusample_baboon)
+#'
+#' @format A data frame with 2922 rows and 277 variables.
+#'
+#' @keywords datasets
+"otusample_baboon"

R/otusample_diet-data.R

@@ -0,0 +1,16 @@
+#' Sample OTU table
+#'
+#' Sample OTU-format table with 34 subjects. Sequences are from metagenomic data, not 16S,
+#' so the first variable contains unique IDs assigned to each microbial sequence rather than OTUs. 
+#' Each subsequent column represents a unique sample collected at a specific time
+#' from one of 34 subjects' microbiomes. Entries represent number of reads per sample 
+#' per microbial taxon.
+#'
+#' @docType data
+#'
+#' @usage data(otusample_diet)
+#'
+#' @format A data frame with 4583 rows and 484 variables.
+#'
+#' @keywords datasets
+"otusample_diet"

R/taxonomysample_baboon-data.R

@@ -0,0 +1,16 @@
+#' Taxonomy information for OTUs
+#'
+#' Taxonomy information for each OTU ID listed in the sample OTU table. The first
+#' variable contains OTU IDs, as listed in \code{otusample_baboon}, and subsequent
+#' columns provide taxonomic clasification up to Genus, or the most specific
+#' level possible for a given taxon. Taxo IDs that are classified more broadly have
+#' \code{NA} values for narrower taxonomic levels that do not apply.
+#'
+#' @docType data
+#'
+#' @usage data(taxonomysample_baboon)
+#'
+#' @format A data frame with 2922 rows and 7 variables.
+#'
+#' @keywords datasets
+"taxonomysample_baboon"

R/taxonomysample_diet-data.R

@@ -0,0 +1,16 @@
+#' Taxonomy information for OTUs
+#'
+#' Taxonomy information for each taxon ID listed in the sample OTU table. The first
+#' variable contains taxon IDs, as listed in \code{otusample_diet}, and the subsequent
+#' column provides taxonomic clasification up to Genus, or the most specific
+#' level possible for a given taxon. Taxo IDs that are classified more broadly have
+#' \code{NA} values for narrower taxonomic levels that do not apply.
+#'
+#' @docType data
+#'
+#' @usage data(taxonomysample_diet)
+#'
+#' @format A data frame with 4583 rows and 2 variables.
+#'
+#' @keywords datasets
+"taxonomysample_diet"

README.md

@@ -0,0 +1,14 @@
+# BiomeHorizon
+
+This package provides a toolset for visualizing longitudinal microbiome data with a horizon plot. A horizon plot provides a compact method to display change in the distribution of microbial taxa over time. This method is valuable for highlighting changes in individual taxa, but more importantly, emphasizes broad trends among groups of taxa. This package can also be used to visualize other types of longitudinal data.
+
+Documentation available in the package, plus our [online tutorial](https://blekhmanlab.github.io/biomehorizon/).
+
+## Installation
+
+```r
+install.packages("devtools")
+
+devtools::install_github("blekhmanlab/biomehorizon")
+library(biomehorizon)
+```