Documentation and website updates

.Rbuildignore

@@ -1,4 +1,5 @@
 ^_pkgdown\.yml$
 ^.*\.Rproj$
 ^\.Rproj\.user$
-^docs$
+^docs$
+^test$

.gitignore

@@ -220,3 +220,5 @@ pip-log.txt
 
 ampvis2.Rproj
 
+
+test/

R/amp_alphadiv.R

@@ -4,7 +4,7 @@
 #'
 #' @usage amp_alphadiv(data, measure, rarefy)
 #'
-#' @param data (\emph{required}) Data list as loaded with \code{amp_load()}.
+#' @param data (\emph{required}) Data list as loaded with \code{\link{amp_load}}.
 #' @param measure Alpha-diversity measure(s) to be included if not all. A vector of one or more of: 
 #' \itemize{
 #'   \item \code{"observed"}

R/amp_boxplot.R

@@ -4,7 +4,7 @@
 #'
 #' @usage amp_boxplot(data)
 #'
-#' @param data (\emph{required}) Data list as loaded with \code{amp_load()}.
+#' @param data (\emph{required}) Data list as loaded with \code{\link{amp_load}}.
 #' @param group_by Group the samples by a variable in the metadata.
 #' @param order_group A vector to order the groups by.
 #' @param order_y A vector to order the y-axis by.

R/amp_core.R

@@ -4,7 +4,7 @@
 #'
 #' @usage amp_core(data)
 #'
-#' @param data (\emph{required}) Data list as loaded with \code{amp_load()}.
+#' @param data (\emph{required}) Data list as loaded with \code{\link{amp_load}}.
 #' @param group_by Group the samples by a variable in the metadata. (\emph{default:} \code{"Sample"})
 #' @param tax_aggregate The taxonomic level to aggregate the OTUs. (\emph{default:} \code{"OTU"})
 #' @param tax_empty How to show OTUs without taxonomic information. One of the following:

R/amp_export_fasta.R

@@ -4,7 +4,7 @@
 #'
 #' @usage amp_export_fasta(data)
 #'
-#' @param data (\emph{required}) Data list as loaded with \code{amp_load()}.
+#' @param data (\emph{required}) Data list as loaded with \code{\link{amp_load}}.
 #' @param filename File name of the exported FASTA file. (\emph{default:} \code{"exported_sequences.fa"})
 #' @param tax (\emph{logical}) Add taxonomic strings to the output or not. (\emph{default:} \code{TRUE})
 #' 

R/amp_export_otutable.R

@@ -4,7 +4,7 @@
 #'
 #' @usage amp_export_otutable(data)
 #'
-#' @param data (\emph{required}) Data list as loaded with \code{amp_load()}.
+#' @param data (\emph{required}) Data list as loaded with \code{\link{amp_load}}.
 #' @param filename File name of the exported OTU-table WITHOUT extension. (\emph{default:} \code{"exported_otutable"})
 #' @param md5 (\emph{logical}) Compute md5 sum of the data (the whole object, not just otutable) and append to the filename. (\emph{default:} \code{FALSE})
 #' @param sep Separator passed directly to \code{\link{write.table}}. (\emph{default:} \code{"\t"})

R/amp_frequency.R

@@ -4,7 +4,7 @@
 #'
 #' @usage amp_frequency(data)
 #'
-#' @param data (\emph{required}) Data list as loaded with \code{amp_load()}.
+#' @param data (\emph{required}) Data list as loaded with \code{\link{amp_load}}.
 #' @param group_by Group the samples by a variable in the metadata. (\emph{default:} \code{"Sample"})
 #' @param tax_aggregate The taxonomic level to aggregate the OTUs. (\emph{default:} \code{"OTU"})
 #' @param tax_empty How to show OTUs without taxonomic information. One of the following:

R/amp_function.R

@@ -4,7 +4,7 @@
 #'
 #' @usage amp_function(heatmap)
 #'
-#' @param heatmap (required) A heatmap as generated by \code{amp_heatmap()}.
+#' @param heatmap (required) A heatmap as generated by \code{\link{amp_heatmap}}.
 #' @param function_data A data frame with functional information about genus-level OTUs. If none provided, the \code{data("MiF")} dataset will be used.
 #' @param adjust_bottom Adjust the whitespace at the bottom of the plot in mm. (\emph{default:} \code{10})
 #' @param adjust_top Adjust the whitespace at the top of the plot in mm. (\emph{default:} \code{0})

R/amp_heatmap.R

@@ -4,7 +4,7 @@
 #'
 #' @usage amp_heatmap(data, group_by = "")
 #'
-#' @param data (\emph{required}) Data list as loaded with \code{amp_load()}.
+#' @param data (\emph{required}) Data list as loaded with \code{\link{amp_load}}.
 #' @param group_by (\emph{recommended}) Group the samples by a categorical variable in the metadata. If \code{NULL} then all samples are shown.
 #' @param facet_by Facet the samples by a categorical variable in the metadata. 
 #' @param scale_by Scale the abundances by a variable in the metadata.
@@ -39,6 +39,26 @@
 #' 
 #' @export
 #' 
+#' @details 
+#' None yet.
+#' 
+#' @section Normalising data for use in heatmaps:
+#' By default the raw read counts in the abundance matrix are normalised (transformed to percentages) by \code{\link{amp_heatmap}} automatically. This means that the relative abundances shown will be calculated based on the remaining taxa after the subset, not including the removed taxa, if any. To circumvent this, set \code{normalise = TRUE} when subsetting with the \code{\link{amp_subset_taxa}} and \code{\link{amp_subset_samples}} functions and then set \code{raw = TRUE} when using \code{\link{amp_heatmap}}, see the example below.
+#' 
+#' \preformatted{
+#' data("MiDAS")
+#' subsettedData <- amp_subset_samples(MiDAS,
+#'                                     Plant \%in\% c("Aalborg West", "Aalborg East"),
+#'                                     normalise = TRUE
+#'                                     )
+#' amp_heatmap(subsettedData,
+#'             group_by = "Plant",
+#'             tax_aggregate = "Phylum",
+#'             tax_add = "Genus",
+#'             raw = TRUE
+#'             )
+#' }
+#' 
 #' @examples 
 #' #Load example data
 #' data("AalborgWWTPs")

R/amp_load.R

@@ -1,6 +1,6 @@
 #' Load data for ampvis functions
 #'
-#' This function reads an OTU-table and corresponding sample metadata, and returns a list for use in all ampvis functions. It is therefore required to load data with \code{amp_load()} before any other ampvis functions can be used.
+#' This function reads an OTU-table and corresponding sample metadata, and returns a list for use in all ampvis functions. It is therefore required to load data with \code{\link{amp_load}} before any other ampvis functions can be used.
 #'
 #' @usage amp_load(otutable = dataframe, metadata = dataframe)
 #'
@@ -14,7 +14,7 @@
 #' @import dplyr
 #' @export
 #' 
-#' @details The \code{amp_load()} function validates and corrects the provided data frames in different ways to make it suitable for the rest of the ampvis functions. It is important that the provided data frames match the requirements as described in the following sections to work properly.
+#' @details The \code{\link{amp_load}} function validates and corrects the provided data frames in different ways to make it suitable for the rest of the ampvis functions. It is important that the provided data frames match the requirements as described in the following sections to work properly.
 #' 
 #' @section The OTU-table:
 #' The OTU-table contains information about the OTUs, their assigned taxonomy and their read counts in each sample. The provided OTU-table must be a data frame with the following requirements:
@@ -40,7 +40,7 @@
 #' 
 #' If for example a column is named "Year" and the entries are simply entered as numbers (2011, 2012, 2013 etc), then R will automatically consider these as numerical values (\code{as.numeric()}) and therefore the column as a continuous variable, while it is a categorical variable and should be loaded \code{as.factor()} or \code{as.character()} instead. This has consequences for the analysis as R treats them differently. Therefore either use the \code{colClasses = } argument when loading a csv file or \code{col_types = } when loading an excel file, or manually adjust the column classes afterwards with fx \code{metadata$Year <- as.character(metadata$Year)}.
 #' 
-#' The \code{amp_load()} function will automatically use the sample IDs in the first column as rownames, but it is important to also have an actual column with sample IDs, so it is possible to fx group by that column during analysis. Any unmatched samples between the otutable and metadata will be removed. 
+#' The \code{\link{amp_load}} function will automatically use the sample IDs in the first column as rownames, but it is important to also have an actual column with sample IDs, so it is possible to fx group by that column during analysis. Any unmatched samples between the otutable and metadata will be removed. 
 #' 
 #' A minimal example is available with \code{data("example_metadata")}.
 #' 

R/amp_ordinate.R

@@ -4,7 +4,7 @@
 #'
 #' @usage amp_ordinate(data, type = "", transform = "", distmeasure = "", constrain = "")
 #'
-#' @param data (\emph{required}) Data list as loaded with \code{amp_load()}.
+#' @param data (\emph{required}) Data list as loaded with \code{\link{amp_load}}.
 #' @param filter_species Remove low abundant OTU's across all samples below this threshold in percent. Setting this to 0 may drastically increase computation time. (\emph{default}: \code{0.1})
 #' @param type (\emph{required}) Type of ordination method. One of:
 #' \itemize{
@@ -67,7 +67,7 @@
 #' @return A ggplot2 object. If \code{detailed_output = TRUE} a list with a ggplot2 object and additional data.
 #'
 #' @details 
-#' The \code{amp_ordinate()} function is mainly based on two packages; \code{\link[vegan]{vegan-package}}, which performs the actual ordination, and \code{\link[ggplot2]{ggplot2-package}} to generate the plot.
+#' The \code{\code{amp_ordinate}} function is mainly based on two packages; \code{\link[vegan]{vegan-package}}, which performs the actual ordination, and \code{\link[ggplot2]{ggplot2-package}} to generate the plot.
 #' 
 #' @export
 #' 

R/amp_otu_network.R

@@ -4,7 +4,7 @@
 #'
 #' @usage amp_otu_network(data)
 #'
-#' @param data (\emph{required}) Data list as loaded with \code{amp_load()}.
+#' @param data (\emph{required}) Data list as loaded with \code{\link{amp_load}}.
 #' @param color_by A metadata variable to color the samples by.
 #' @param tax_aggregate The taxonomic level to aggregate the OTUs. (\emph{default:} \code{"Phylum"})
 #' @param tax_add Additional taxonomic level(s) to display, e.g. \code{"Phylum"}. (\emph{default:} \code{"none"})

R/amp_rankabundance.R

@@ -4,7 +4,7 @@
 #'
 #' @usage amp_rankabundance(data)
 #'
-#' @param data (\emph{required}) Data list as loaded with \code{amp_load()}.
+#' @param data (\emph{required}) Data list as loaded with \code{\link{amp_load}}.
 #' @param group_by Group the samples by a variable in the metadata.
 #' @param order_group A vector to order the groups by.
 #' @param tax_aggregate The taxonomic level to aggregate the OTUs. (\emph{default:} \code{"Genus"})

R/amp_rarecurve.R

@@ -4,7 +4,7 @@
 #'
 #' @usage amp_rarecurve(data)
 #'
-#' @param data (\emph{required}) Data list as loaded with \code{amp_load()}.
+#' @param data (\emph{required}) Data list as loaded with \code{\link{amp_load}}.
 #' @param stepsize Step size for the curves. Lower is prettier but takes more time to generate. (\emph{default:} \code{1000})
 #' @param color_by Color curves by a variable in the metadata. 
 #' 

R/amp_rename.R

@@ -4,7 +4,7 @@
 #'
 #' @usage amp_rename(data)
 #'
-#' @param data (\emph{required}) Data list as loaded with \code{amp_load()}.
+#' @param data (\emph{required}) Data list as loaded with \code{\link{amp_load}}.
 #' @param tax_empty How to show OTUs without taxonomic information. One of the following:
 #' \itemize{
 #'    \item \code{"remove"}: Remove OTUs without taxonomic information.

R/amp_subset_samples.R

@@ -4,7 +4,7 @@
 #'
 #' @usage amp_subset_samples(data, ...)
 #'
-#' @param data (\emph{required}) Data list as loaded with \code{amp_load()}.
+#' @param data (\emph{required}) Data list as loaded with \code{\link{amp_load}}.
 #' @param minreads Minimum number of reads pr. sample. (\emph{default:} \code{1})
 #' @param ... Logical expression indicating elements or rows to keep in the metadata. Missing values are taken as false. Directly passed to \code{subset()}. 
 #' @param normalise (\emph{logical}) Normalise the read abundances to the total amount of reads (percentages) \emph{BEFORE} the subset. (\emph{default:} \code{FALSE})
@@ -17,6 +17,23 @@
 #' 
 #' @details The subset is performed on the metadata by \code{subset()} and the abundance- and taxonomy tables are then adjusted accordingly.
 #' 
+#' @section Normalising data for use in heatmaps:
+#' By default the raw read counts in the abundance matrix are normalised (transformed to percentages) by \code{\link{amp_heatmap}} automatically. This means that the relative abundances shown will be calculated based on the remaining taxa after the subset, not including the removed taxa, if any. To circumvent this, set \code{normalise = TRUE} when subsetting with the \code{\link{amp_subset_taxa}} and \code{\link{amp_subset_samples}} functions and then set \code{raw = TRUE} when using \code{\link{amp_heatmap}}, see the example below.
+#' 
+#' \preformatted{
+#' data("MiDAS")
+#' subsettedData <- amp_subset_samples(MiDAS,
+#'                                     Plant \%in\% c("Aalborg West", "Aalborg East"),
+#'                                     normalise = TRUE
+#'                                     )
+#' amp_heatmap(subsettedData,
+#'             group_by = "Plant",
+#'             tax_aggregate = "Phylum",
+#'             tax_add = "Genus",
+#'             raw = TRUE
+#'             )
+#' }
+#' 
 #' @examples 
 #' #Load example data
 #' data("MiDAS")
@@ -39,6 +56,9 @@
 #' #Summary
 #' MiDASsubset2
 #' 
+#' @seealso 
+#' \code{\link{amp_subset_taxa}}, \code{\link{amp_heatmap}}
+#' 
 #' @author Kasper Skytte Andersen \email{kasperskytteandersen@gmail.com}
 #' @author Mads Albertsen \email{MadsAlbertsen85@@gmail.com}
 

R/amp_subset_taxa.R

@@ -4,14 +4,50 @@
 #'
 #' @usage amp_subset_taxa(data, tax_vector)
 #'
-#' @param data (\emph{required}) Data list as loaded with \code{amp_load()}.
+#' @param data (\emph{required}) Data list as loaded with \code{\link{amp_load}}.
 #' @param tax_vector (required) A vector with taxonomic groups, e.g. \code{c("p__Chloroflexi","p__Actinobacteria")}.
 #' @param normalise (\emph{logical}) Normalise the read abundances to the total amount of reads (percentages) \emph{BEFORE} the subset. (\emph{default:} \code{FALSE})
 #' 
 #' @return A list with 3 dataframes (4 if reference sequences are provided).
 #' @import ape
 #' @export
 #' 
+#' @details 
+#' The subset of taxa is done by providing a vector of taxa names, where all other taxa are then removed. The taxa names in the vector will be matched in all columns in the taxonomy table.
+#' 
+#' @section Normalising data for use in heatmaps:
+#' By default the raw read counts in the abundance matrix are normalised (transformed to percentages) by \code{\link{amp_heatmap}} automatically. This means that the relative abundances shown will be calculated based on the remaining taxa after the subset, not including the removed taxa, if any. To circumvent this, set \code{normalise = TRUE} when subsetting with the \code{\link{amp_subset_taxa}} and \code{\link{amp_subset_samples}} functions and then set \code{raw = TRUE} when using \code{\link{amp_heatmap}}, see the example below.
+#' 
+#' \preformatted{
+#' data("AalborgWWTPs")
+#' subsettedData <- amp_subset_taxa(AalborgWWTPs,
+#'                                  tax_vector = c("p__Chloroflexi", "p__Actinobacteria"),
+#'                                  normalise = TRUE
+#'                                  )
+#' amp_heatmap(subsettedData,
+#'             group_by = "Plant",
+#'             tax_aggregate = "Phylum",
+#'             tax_add = "Genus",
+#'             raw = TRUE
+#'             )
+#' }
+#' 
+#' @examples 
+#' #Load example data
+#' data("MiDAS")
+#' 
+#' #Show a short summary about the data by simply typing the name of the object in the console
+#' MiDAS
+#' 
+#' #Remove all taxa except the phyla Chloroflexi and Actinobacteria
+#' MiDASsubset <- amp_subset_taxa(MiDAS, tax_vector = c("p__Chloroflexi", "p__Actinobacteria"))
+#' 
+#' #Summary
+#' MiDASsubset
+#' 
+#' @seealso 
+#' \code{\link{amp_subset_samples}}, \code{\link{amp_heatmap}}
+#' 
 #' @author Kasper Skytte Andersen \email{kasperskytteandersen@gmail.com}
 #' @author Mads Albertsen \email{MadsAlbertsen85@@gmail.com}
 #' @author Rasmus Hansen Kirkegaard \email{rhk@bio.aau.dk}

R/amp_timeseries.R

@@ -4,7 +4,7 @@
 #' 
 #' @usage amp_timeseries(data, time_variable = "")
 #' 
-#' @param data (\emph{required}) Data list as loaded with \code{amp_load()}.
+#' @param data (\emph{required}) Data list as loaded with \code{\link{amp_load}}.
 #' @param time_variable (required) The name of the column in the metadata containing the time variables, e.g. \code{"Date"}. Must be directly compatible with \code{\link{as.Date()}} and preferably of the form \code{"yyyy-mm-dd"} or \code{"\%Y-\%m-\%d"}.
 #' @param group_by Group the samples by a variable in the metadata.
 #' @param split Split the plot into subplots of each taxa. (\emph{default:} \code{FALSE}) 

R/amp_venn.R

@@ -4,7 +4,7 @@
 #'
 #' @usage amp_venn(data)
 #'
-#' @param data (\emph{required}) Data list as loaded with \code{amp_load()}.
+#' @param data (\emph{required}) Data list as loaded with \code{\link{amp_load}}.
 #' @param group_by Group the data based on a sample variable.
 #' @param cut_a Abundance cutoff in percent. (\emph{default:} \code{0.1})
 #' @param cut_f Frequency cutoff in percent. (\emph{default:} \code{80})

R/print.ampvis2.R

@@ -1,6 +1,6 @@
 #' Prints ampvis2 object summary. Internal function.
 #'
-#' @param data (\emph{required}) Data list as loaded with \code{amp_load()}.
+#' @param data (\emph{required}) Data list as loaded with \code{\link{amp_load}}.
 #'
 #' @return Text output in console
 #' @export

_pkgdown.yml

@@ -14,10 +14,10 @@ reference:
     desc: Functions for loading, exporting and subsetting the data.
     contents:
     - amp_load
-    - amp_export_fasta
-    - amp_export_otutable
     - amp_subset_samples
     - amp_subset_taxa
+    - amp_export_fasta
+    - amp_export_otutable
   - title: Plotting functions
     desc: Functions for visualising amplicon data.
     contents:
@@ -33,8 +33,18 @@ reference:
     - amp_rankabundance
     - amp_alphadiv
     - amp_venn
+
 navbar:
   title: "ampvis2"
+  left:
+    - text: "Home"
+      href: index.html
+    - text: "Get Started"
+      href: articles/ampvis2.html
+    - text: "Functions"
+      href: reference/index.html
+    - text: "FAQ"
+      href: articles/faq.html
   right:
-  - icon: fa-github
+  - icon: fa-github fa-lg
     href: https://github.com/MadsAlbertsen/ampvis2