Merge pull request #96 from adrientaudiere/dev

docs: Better descriptions

.github/workflows/pkgdown.yaml

@@ -1,8 +1,8 @@
 # Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
 # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
 on:
-#  release:
-#    types: [published]
+  release:
+    types: [published]
 
 name: pkgdown
 

R/Deseq2_edgeR.R

@@ -1,9 +1,13 @@
 ################################################################################
 #' Plot edgeR results for a phyloseq or a edgeR object.
 #'
+#' @description 
+#' 
 #' <a href="https://adrientaudiere.github.io/MiscMetabar/articles/Rules.html#lifecycle">
 #' <img src="https://img.shields.io/badge/lifecycle-maturing-blue" alt="lifecycle-maturing"></a>
 #'
+#' Graphical representation of edgeR result.
+#' 
 #' @inheritParams clean_pq
 #' @param contrast (required):This argument specifies what comparison
 #'   to extract from the object to build a results table.
@@ -121,10 +125,13 @@ plot_edgeR_pq <-
 # Plot the result of a DESeq2 test
 ################################################################################
 #' Plot DESeq2 results for a phyloseq or a DESeq2 object.
+#' 
 #' @description
 #'
 #' <a href="https://adrientaudiere.github.io/MiscMetabar/articles/Rules.html#lifecycle">
 #' <img src="https://img.shields.io/badge/lifecycle-experimental-orange" alt="lifecycle-experimental"></a>
+#' 
+#' Graphical representation of DESeq2 analysis.
 #'
 #' @param data (required) a \code{\link{phyloseq-class}} or a
 #' \code{\link[DESeq2]{DESeqDataSet-class}} object.

R/alpha_div_test.R

@@ -105,11 +105,11 @@ hill_tuckey_pq <- function(
 #' Test multiple times effect of factor on Hill diversity
 #'   with different rarefaction even depth
 #'
-#' @description
-#'
+#' @description 
 #' <a href="https://adrientaudiere.github.io/MiscMetabar/articles/Rules.html#lifecycle">
 #' <img src="https://img.shields.io/badge/lifecycle-experimental-orange" alt="lifecycle-experimental"></a>
-#'
+#' 
+#' This reduce the risk of a random drawing of a exceptional situation of an unique rarefaction. 
 #' @inheritParams clean_pq
 #' @param fact (required) Name of the factor in `physeq@sam_data` used to plot
 #'    different lines
@@ -135,7 +135,7 @@ hill_tuckey_pq <- function(
 #'   - "robust"
 #'   - "bayes"
 #'
-#' @param ... Others arguments passed on to [ggstatsplot::ggbetweenstats()] function
+#' @param ... Other arguments passed on to [ggstatsplot::ggbetweenstats()] function
 #' @seealso [ggstatsplot::ggbetweenstats()], [hill_pq()]
 #' @return A list of 6 components :
 #'
@@ -271,11 +271,13 @@ hill_test_rarperm_pq <- function(physeq,
 
 ################################################################################
 #' Automated model selection and multimodel inference with (G)LMs for phyloseq
-#' @description
 #'
+#' @description 
 #' <a href="https://adrientaudiere.github.io/MiscMetabar/articles/Rules.html#lifecycle">
 #' <img src="https://img.shields.io/badge/lifecycle-experimental-orange" alt="lifecycle-experimental"></a>
 #'
+#' See [glmulti::glmulti()] for more information.
+#' 
 #' @inheritParams clean_pq
 #' @param formula (required) a formula for [glmulti::glmulti()]
 #'   Variables must be present in the `physeq@sam_data` slot or be one
@@ -301,7 +303,7 @@ hill_test_rarperm_pq <- function(physeq,
 #'   with covariates and no interactions. If "d", a simple summary of the candidate set
 #'   is printed, including the number of candidate models.
 #' @param crit The Information Criterion to be used. Default is the small-sample corrected AIC (aicc). This should be a function that accepts a fitted model as first argument. Other provided functions are the classic AIC, the Bayes IC (bic), and QAIC/QAICc (qaic and qaicc).
-#' @param ... Others arguments passed on to [glmulti::glmulti()] function
+#' @param ... Other arguments passed on to [glmulti::glmulti()] function
 #'
 #' @return A data.frame summarizing the glmulti results with columns
 #'

R/beta_div_test.R

@@ -17,7 +17,7 @@
 #'   Need to be in \code{physeq@sam_data}
 #' @param nperm (int) The number of permutations to perform.
 #' @param return_plot (logical) Do we return only the result
-#'   of the test or do we plot the result?
+#'   of the test, or do we plot the result?
 #' @param title The title of the Graph.
 #' @param na_remove (logical, default FALSE) If set to TRUE, remove samples with
 #'   NA in the variables set in formula.
@@ -116,7 +116,7 @@ graph_test_pq <- function(physeq,
 #' @param na_remove (logical, default FALSE) If set to TRUE, remove samples with
 #'   NA in the variables set in formula.
 #' @param correction_for_sample_size (logical, default FALSE) If set to TRUE,
-#'   the sample size (number of sequences by samples) is add to formula in
+#'   the sample size (number of sequences by samples) is added to formula in
 #'   the form `y~Library_Size + Biological_Effect` following recommendation of
 #'   [Weiss et al. 2017](https://microbiomejournal.biomedcentral.com/articles/10.1186/s40168-017-0237-y).
 #'   `correction_for_sample_size` overcome `rarefy_nb_seqs` if both are TRUE.
@@ -220,21 +220,25 @@ adonis_pq <- function(physeq,
 ################################################################################
 #' Permanova (adonis) on permutations of rarefaction even depth
 #'
-#' @description
-#'
+#' @description 
+#' 
 #' <a href="https://adrientaudiere.github.io/MiscMetabar/articles/Rules.html#lifecycle">
 #' <img src="https://img.shields.io/badge/lifecycle-experimental-orange" alt="lifecycle-experimental"></a>
 #'
+#' Permanova are computed on a given number of rarefaction with different 
+#' seed.number. This reduce the risk of a random drawing of a exceptional 
+#' situation of an unique rarefaction. 
+#' 
 #' @inheritParams adonis_pq
-#' @param nperm (int) The number of permutations to perform.
+#' @param nperm (int, default = 99) The number of permutations to perform.
 #' @param progress_bar (logical, default TRUE) Do we print progress during
 #'   the calculation.
 #' @param quantile_prob (float, `[0:1]`) the value to compute the quantile.
-#'   Minimum quantile is compute using 1-quantile_prob.
+#'   Minimum quantile is computed using 1-quantile_prob.
 #' @param sample.size (int) A single integer value equal to the number of
 #'   reads being simulated, also known as the depth. See
 #'   [phyloseq::rarefy_even_depth()].
-#' @param ... Other params for be passed on to [adonis_pq()] function
+#' @param ... Other params to be passed on to [adonis_pq()] function
 #'
 #' @return A list of three dataframe representing the mean, the minimum quantile
 #'  and the maximum quantile value for adonis results. See [adonis_pq()].
@@ -344,7 +348,7 @@ adonis_rarperm_pq <- function(physeq,
 #' @inheritParams clean_pq
 #'
 #' @param p_adjust_method (chr, default "BH"): the method used to adjust p-value
-#' @param ... Others arguments passed on to [adespatial::beta.div()] function
+#' @param ... Other arguments passed on to [adespatial::beta.div()] function
 #'
 #' @return An object of class `beta.div` see [adespatial::beta.div()] function
 #'   for more information
@@ -395,11 +399,11 @@ LCBD_pq <- function(physeq,
 #' @param p_adjust_method (chr, default "BH"): the method used to adjust p-value
 #' @param pval (int, default 0.05): the value to determine the significance of
 #'   LCBD
-#' @param sam_variables A vector of variables names present in the `sam_data`
+#' @param sam_variables A vector of variable names present in the `sam_data`
 #'   slot to plot alongside the LCBD value
 #' @param only_plot_significant (logical, default TRUE) Do we plot all LCBD
 #'   values or only the significant ones
-#' @param ... Others arguments passed on to [adespatial::beta.div()] function
+#' @param ... Other arguments passed on to [adespatial::beta.div()] function
 #'
 #' @return A ggplot2 object build with the package patchwork
 #' @export
@@ -548,7 +552,7 @@ plot_LCBD_pq <- function(physeq,
 #' @param min_SCBD (default 0.01) the minimum SCBD value
 #'   to plot the taxa
 
-#' @param ... Others arguments passed on to [adespatial::beta.div()] function
+#' @param ... Other arguments passed on to [adespatial::beta.div()] function
 #'
 #' @return A ggplot2 object build with the package patchwork
 #' @export
@@ -617,7 +621,7 @@ plot_SCBD_pq <- function(physeq,
 #' @param pval (int, default 0.05): the value to determine the significance of
 #'   LCBD
 #' @param control see `?indicspecies::multipatt()`
-#' @param ... Others arguments passed on to [indicspecies::multipatt()] function
+#' @param ... Other arguments passed on to [indicspecies::multipatt()] function
 #'
 #' @return A ggplot2 object
 #' @export
@@ -770,11 +774,13 @@ ancombc_pq <- function(physeq, fact, levels_fact = NULL, tax_level = "Class", ..
 
 ################################################################################
 #' Filter ancombc_pq results
-#' @description
 #'
+#' @description 
 #' <a href="https://adrientaudiere.github.io/MiscMetabar/articles/Rules.html#lifecycle">
 #' <img src="https://img.shields.io/badge/lifecycle-experimental-orange" alt="lifecycle-experimental"></a>
 #'
+#' Internally used in [plot_ancombc_pq()].
+#' 
 #' @param ancombc_res (required) the result of the ancombc_pq function
 #'   For the moment only bimodal factors are possible.
 #' @param filter_passed (logical, default TRUE) Do we filter using the column
@@ -850,11 +856,13 @@ signif_ancombc <- function(ancombc_res,
 
 ################################################################################
 #' Plot ANCOMBC2 result for phyloseq object
-#' @description
 #'
+#' @description 
 #' <a href="https://adrientaudiere.github.io/MiscMetabar/articles/Rules.html#lifecycle">
 #' <img src="https://img.shields.io/badge/lifecycle-experimental-orange" alt="lifecycle-experimental"></a>
 #'
+#' Graphical representation of ANCOMBC2 result.
+#' 
 #' @inheritParams clean_pq
 #' @param ancombc_res (required) the result of the ancombc_pq function
 #'   For the moment only bimodal factors are possible.
@@ -866,7 +874,7 @@ signif_ancombc <- function(ancombc_res,
 #'   (has q less than alpha)
 #' @param min_abs_lfc (integer, default 0) Minimum absolute value to filter
 #'   results based on Log Fold Change. For ex. a value of 1 filter out taxa
-#'   for which the abundance in a given level of the modality is not at least
+#'   for which the abundance in a given level of the modalty is not at least
 #'   the double of the abundance in the other level.
 #' @param tax_col The taxonomic level (must be present in `tax_table` slot)
 #'   to color the points
@@ -1017,7 +1025,6 @@ plot_ancombc_pq <-
 ################################################################################
 #' Show taxa which are present in only one given level of a modality
 #'
-#' @description
 #'
 #' <a href="https://adrientaudiere.github.io/MiscMetabar/articles/Rules.html#lifecycle">
 #' <img src="https://img.shields.io/badge/lifecycle-experimental-orange" alt="lifecycle-experimental"></a>
@@ -1073,11 +1080,13 @@ taxa_only_in_one_level <- function(physeq,
 ################################################################################
 #' Distribution of sequences across a factor for one taxon
 #'
-#' @description
-#'
+#' @description 
+#' 
 #' <a href="https://adrientaudiere.github.io/MiscMetabar/articles/Rules.html#lifecycle">
 #' <img src="https://img.shields.io/badge/lifecycle-experimental-orange" alt="lifecycle-experimental"></a>
 #'
+#' Focus on one taxon and one factor. 
+#' 
 #' @inheritParams clean_pq
 #' @param fact (required) Name of the factor in `physeq@sam_data` used to plot
 #'    different lines

R/blast.R

@@ -2,9 +2,13 @@
 #' Blast some sequence against `refseq` slot of a \code{\link{phyloseq-class}}
 #'   object.
 #'
+#' @description 
+#' 
 #' <a href="https://adrientaudiere.github.io/MiscMetabar/articles/Rules.html#lifecycle">
 #' <img src="https://img.shields.io/badge/lifecycle-maturing-blue" alt="lifecycle-maturing"></a>
-#'
+#' 
+#' Use the blast software.
+#' 
 #' @param physeq (required): a \code{\link{phyloseq-class}} object obtained
 #'   using the `phyloseq` package.
 #' @param seq2search (required) path to a fasta file defining the sequences
@@ -180,9 +184,13 @@ blast_to_phyloseq <- function(physeq,
 #' Blast all sequence of `refseq` slot of a \code{\link{phyloseq-class}}
 #'   object against a custom database.
 #'
+#' @description 
+#' 
 #' <a href="https://adrientaudiere.github.io/MiscMetabar/articles/Rules.html#lifecycle">
 #' <img src="https://img.shields.io/badge/lifecycle-experimental-orange" alt="lifecycle-experimental"></a>
 #'
+#' Use the blast software.
+#' 
 #' @inheritParams blast_to_phyloseq
 #' @param fasta_for_db path to a fasta file to make the blast database
 #' @param database path to a blast database
@@ -335,9 +343,13 @@ blast_pq <- function(physeq,
 ################################################################################
 #' Filter undesirable taxa using blast against a custom database.
 #'
+#' @description 
+#' 
 #' <a href="https://adrientaudiere.github.io/MiscMetabar/articles/Rules.html#lifecycle">
 #' <img src="https://img.shields.io/badge/lifecycle-experimental-orange" alt="lifecycle-experimental"></a>
 #'
+#' Use the blast software.
+#' 
 #' @inheritParams blast_to_phyloseq
 #' @param fasta_for_db path to a fasta file to make the blast database
 #' @param database path to a blast database
@@ -423,9 +435,12 @@ filter_asv_blast <- function(physeq,
 #' Blast some sequence against sequences from of a \code{\link{derep-class}}
 #'   object.
 #'
+#' @description 
 #' <a href="https://adrientaudiere.github.io/MiscMetabar/articles/Rules.html#lifecycle">
 #' <img src="https://img.shields.io/badge/lifecycle-experimental-orange" alt="lifecycle-experimental"></a>
 #'
+#' Use the blast software.
+#' 
 #' @inheritParams blast_to_phyloseq
 #' @param derep The result of `dada2::derepFastq()`. A list of `derep-class`
 #'   object.

R/controls.R

@@ -1,10 +1,14 @@
 ################################################################################
-#' Search for exact matching of sequences using complement,
-#' reverse and reverse-complement
+#' Search for exact matching of sequences
 #'
+#' @description 
+#' 
 #' <a href="https://adrientaudiere.github.io/MiscMetabar/articles/Rules.html#lifecycle">
 #' <img src="https://img.shields.io/badge/lifecycle-experimental-orange" alt="lifecycle-experimental"></a>
 #'
+#' Search for exact matching of sequences using complement,
+#' reverse and reverse-complement
+#' 
 #' @inheritParams clean_pq
 #' @param seq2search A DNAStringSet object of sequences to search for.
 #' @return A list of data-frames for each input sequences with the name,
@@ -49,7 +53,6 @@ search_exact_seq_pq <- function(physeq, seq2search) {
 ################################################################################
 #' Calculate ecological distance among positive controls vs
 #'   distance for all samples
-
 #' @description
 #'
 #' <a href="https://adrientaudiere.github.io/MiscMetabar/articles/Rules.html#lifecycle">
@@ -124,17 +127,23 @@ dist_pos_control <- function(physeq, samples_names, method = "bray") {
 
 
 ################################################################################
-#' Subset taxa using a taxa control (e.g. truffle root tips) through 3 methods.
+#' Subset taxa using a taxa control or distribution based method
 #'
+#' @description 
 #' <a href="https://adrientaudiere.github.io/MiscMetabar/articles/Rules.html#lifecycle">
 #' <img src="https://img.shields.io/badge/lifecycle-experimental-orange" alt="lifecycle-experimental"></a>
+#' 
+#' There is 3 main methods : discard taxa (i) using a control taxa (e.g. truffle root tips), 
+#' (ii) using a mixture models to detect bimodality in pseudo-abundance distribution or 
+#' (iii) using a minimum difference threshold pseudo-abundance. Each cutoff is defined at 
+#' the sample level.
 #'
 #' @aliases subset_taxa_tax_control
 #' @inheritParams clean_pq
 #' @param taxa_distri (required) a vector of length equal to the number of
-#'   samples with the number of sequences per samples for the taxa control
+#'   samples with the number of sequences per sample for the taxa control
 #' @param method (default: "mean") a method to calculate the cut-off value.
-#'   There is 6 available methods:
+#'   There are 6 available methods:
 #'   1. `cutoff_seq`: discard taxa with less than the number of sequence
 #'           than taxa control,
 #'   2. `cutoff_mixt`: using mixture models,