Merge pull request #106 from egouldo/102-roxygen2-doc

Roxygen / Pkgdown documentation overhaul

.Rbuildignore

@@ -5,10 +5,10 @@
 ^\.Rproj\.user$
 _targets.R
 _targets/
-
 ^_pkgdown\.yml$
 ^docs$
 ^pkgdown$
 ^\.github$
 ^doc$
 ^Meta$
+^data-raw/analyst_data/S2$

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: ManyEcoEvo
 Title: Meta-analyse data from 'Many-Analysts' style studies
-Version: 2.3.0.9000
+Version: 2.3.0.9003
 Authors@R: c(
     person("Elliot", "Gould", , "[email protected]", role = c("aut", "cre"),
            comment = c(ORCID = "https://orcid.org/0000-0002-6585-538X")),
@@ -20,7 +20,9 @@ URL: https://github.com/egouldo/ManyEcoEvo,
     https://egouldo.github.io/ManyEcoEvo/
 BugReports: https://github.com/egouldo/ManyEcoEvo/issues
 Depends: 
-    R (>= 2.10)
+    R (>= 2.10),
+    rmarkdown,
+    bookdown
 Imports:
     betapart,
     cli,
@@ -41,7 +43,6 @@ Imports:
     tibble,
     tidyr,
     tidyselect,
-    tidyselect,
     withr
 Suggests:
     broom.mixed,

NAMESPACE

@@ -111,9 +111,11 @@ import(ggbeeswarm)
 import(ggplot2)
 import(lme4)
 import(metafor)
+import(purrr)
 import(recipes)
 import(rlang)
 import(see)
+import(stringr)
 import(tidyr)
 importFrom(EnvStats,stat_n_text)
 importFrom(broom,tidy)
@@ -122,8 +124,8 @@ importFrom(cli,cli_abort)
 importFrom(cli,cli_alert_info)
 importFrom(cli,cli_alert_warning)
 importFrom(cli,cli_h2)
+importFrom(data.table,setnames)
 importFrom(dplyr,across)
-importFrom(dplyr,case_when)
 importFrom(dplyr,count)
 importFrom(dplyr,distinct)
 importFrom(dplyr,ends_with)
@@ -149,6 +151,7 @@ importFrom(metaviz,viz_funnel)
 importFrom(parameters,parameters)
 importFrom(performance,performance)
 importFrom(pointblank,col_vals_not_null)
+importFrom(pointblank,has_columns)
 importFrom(pointblank,stop_if_not)
 importFrom(pointblank,test_col_vals_gte)
 importFrom(purrr,keep)

R/assign_transformation_type.R

@@ -1,13 +1,16 @@
-#' Assign back-transformation type to be applied to analysis point-estimates
+#' Assign back-transformation type to be applied to analysts' point-estimates
 #'
 #' @param response_transformation Character vector of length 1L containing the analysis response transformation
 #' @param link_fun Character vector of length 1L containing the analysis link function
 #'
-#' @return A character vector of length 1L
+#' @return A character vector of length 1L containing the back-transformation type to be applied to the analysts' point-estimates. Is either "identity", "double_transformation", or the value of `link_fun` or `response_transformation`, or `NA`, if an appropriate transformation type cannot be assigned.
+#' @details 
+#' Based on the response transformation and link function, the function assigns the back-transformation type to be applied to the analysts' point-estimates. The function and assigns the identity transformation if the effects were reported on the link-scale and the estimates are already back-transformed the original response variable prior to modelling. When either of these cases is not true for a given analysis, the function returns the value of the `link_fun` or `response_transformation` argument. When an analysis has been reported on the link-scale and the analyst transformed the response variable prior to modelling, the function assigns the `"double-transformation"`  value for that analysis. When the `response_transformation` and `link_fun` arguments are missing, the function assigns the `"identity"` value to the analysis, assuming that `NA` values are equivalent to the identity transformation. 
 #' @export
-#' @importFrom dplyr case_when
-#' @importFrom rlang is_na
-#' @importFrom rlang na_chr
+#' @import dplyr
+#' @import rlang
+#' @family back-transformation functions
+#' @seealso [prepare_response_variables_yi(), standardise_response()]. To be called prior to [clean_response_transformation()].
 assign_transformation_type <- function(response_transformation = character(1L),
                                        link_fun = character(1L)) {
   # # Link-Fun: Set back.transformed to "identity"

R/back_transformations.R

@@ -1,17 +1,21 @@
 # --- Back-transformation Conversion Functions ---
-# convertion functions
-# we assume estimates are normally distributed
-# TODO Question - all natural log (no log10)
-
-#' Back transform beta estimates for models with log-link
-#'
-#' @param beta Analyst beta estimate or yi estimate
-#' @param se Standard error of analyst's beta estimate or yi estimate.
+#' Back-transform effect-sizes to response scale.
+#' @description
+#' Transforms effect-sizes and their standard errors to the response scale.
+#' 
+#' @details We assume analysts' estimates are normally distributed. Each function uses a normal distribution to simulate the a distribution of effect-sizes and their standard errors. Next this distribution is back-transformed to the desired response scale. The mean `m_est`, standard error `se_est`, and quantiles (`lower` and `upper`) of the back-transformed distribution are returned within a dataframe.
+#' @param beta Analyst beta estimate
+#' @param se Standard error of analyst's effect size estimate $\\beta$ 
+#' or out-of-sample prediction estimate $y\\_i$.
 #' @param sim numeric vector of length 1. number of simulations.
-#'
-#' @return data frame containing the mean estimate, its standard error, and quantiles
-#' @export
+#' @return data frame containing the mean estimate, its standard error, and quantiles.
 #' @family back transformation
+#' @name back
+NULL
+#> NULL
+
+#' @describeIn back Back transform beta estimates for models with log-link
+#' @export
 log_back <- function(beta, se, sim) {
   simulated <- rnorm(sim, beta, se)
   original <- exp(simulated) %>% # exponential = inverse of log
@@ -29,14 +33,8 @@ log_back <- function(beta, se, sim) {
   return(set)
 }
 
-#' Back transform beta estimates for models with logit-link
-#' @param beta Analyst beta estimate
-#' @param se Standard error of analyst's beta estimate.
-#' @param sim numeric vector of length 1. number of simulations.
-#'
-#' @return data frame containing the mean estimate, its standard error, and quantiles
+#' @describeIn back Back transform beta estimates for models with logit-link
 #' @export
-#' @family back transformation
 logit_back <- function(beta, se, sim) {
   simulated <- rnorm(sim, beta, se)
   original <- plogis(simulated) %>% # invlogit
@@ -54,14 +52,8 @@ logit_back <- function(beta, se, sim) {
   return(set)
 }
 
-#' Back transform beta estimates for models with probit-link
-#' @param beta Analyst beta estimate
-#' @param se Standard error of analyst's beta estimate.
-#' @param sim numeric vector of length 1. number of simulations.
-#'
-#' @return data frame containing the mean estimate, its standard error, and quantiles
+#' @describeIn back Back transform beta estimates for models with probit-link
 #' @export
-#' @family back transformation
 probit_back <- function(beta, se, sim) {
   simulated <- rnorm(sim, beta, se)
   original <- pnorm(simulated) %>% # inv-probit
@@ -79,14 +71,8 @@ probit_back <- function(beta, se, sim) {
   return(set)
 }
 
-#' Back transform beta estimates for models with $1/x$ link
-#' @param beta Analyst beta estimate
-#' @param se Standard error of analyst's beta estimate.
-#' @param sim numeric vector of length 1. number of simulations.
-#'
-#' @return data frame containing the mean estimate, its standard error, and quantiles
+#' @describeIn back Back transform beta estimates for models with $1/x$ link
 #' @export
-#' @family back transformation
 inverse_back <- function(beta, se, sim) {
   simulated <- rnorm(sim, beta, se)
   original <- 1 / simulated %>% # inverse
@@ -104,14 +90,8 @@ inverse_back <- function(beta, se, sim) {
   return(set)
 }
 
-#' Back transform beta estimates for models with $x^2$-link
-#' @param beta Analyst beta estimate
-#' @param se Standard error of analyst's beta estimate.
-#' @param sim numeric vector of length 1. number of simulations.
-#'
-#' @return data frame containing the mean estimate, its standard error, and quantiles
+#' @describeIn back Back transform beta estimates for models with $x^2$-link
 #' @export
-#' @family back transformation
 square_back <- function(beta, se, sim) {
   simulated <- rnorm(sim, beta, se)
   original <- sqrt(simulated) %>% # inverse of x^2
@@ -129,14 +109,8 @@ square_back <- function(beta, se, sim) {
   return(set)
 }
 
-#' Back transform beta estimates for models with $x^3$-link
-#' @param beta Analyst beta estimate
-#' @param se Standard error of analyst's beta estimate.
-#' @param sim numeric vector of length 1. number of simulations.
-#'
-#' @return data frame containing the mean estimate, its standard error, and quantiles
+#' @describeIn back Back transform beta estimates for models with $x^3$-link
 #' @export
-#' @family back transformation
 cube_back <- function(beta, se, sim) {
   simulated <- rnorm(sim, beta, se)
   original <- pracma::nthroot(simulated, n = 3) %>% # inverse of x^3, use non-base to allow for -ve numbers
@@ -154,14 +128,8 @@ cube_back <- function(beta, se, sim) {
   return(set)
 }
 
-#' Back transform beta estimates for models with identity-link
-#' @param beta Analyst beta estimate
-#' @param se Standard error of analyst's beta estimate.
-#' @param sim numeric vector of length 1. number of simulations.
-#'
-#' @return data frame containing the mean estimate, its standard error, and quantiles
+#' @describeIn back Back transform beta estimates for models with identity-link
 #' @export
-#' @family back transformation
 identity_back <- function(beta, se, sim) { # identity (typo) TODO
   simulated <- rnorm(sim, beta, se)
   original <- simulated %>% #  no transformation
@@ -180,15 +148,8 @@ identity_back <- function(beta, se, sim) { # identity (typo) TODO
 }
 
 
-#' Back transform beta estimates for models with power-link
-#' @param beta Analyst beta estimate. Numeric vector of length 1.
-#' @param se Standard error of analyst's beta estimate. Numeric vector of length 1.
-#' @param sim Number of simulations. Numeric vector of length 1.
-#' @param n Numeric vector of length 1 describing power which values were raised to in transformation.
-#'
-#' @return data frame containing the mean estimate, its standard error, and quantiles
+#' @describeIn back Back transform beta estimates for models with power-link
 #' @export
-#' @family back transformation
 power_back <- function(beta, se, sim, n) {
   simulated <- rnorm(sim, beta, se)
   original <- pracma::nthroot(simulated, n = n) %>% # inverse of x^n, use non-base to allow for -ve numbers
@@ -206,15 +167,9 @@ power_back <- function(beta, se, sim, n) {
   return(set)
 }
 
-#' Back transform beta estimates or out-of-sample predictions from models whose response variable has been divided by some number
-#' @param beta Analyst beta estimate. Numeric vector of length 1.
-#' @param se Standard error of analyst's beta estimate. Numeric vector of length 1.
-#' @param sim Number of simulations. Numeric vector of length 1.
-#' @param n Numeric vector of length 1 describing the value of the divisor.
-#'
-#' @return data frame containing the mean estimate, its standard error, and quantiles
+#' @describeIn back Back transform beta estimates or out-of-sample predictions from models whose response variable has been divided by some number, `n`.
+#' @param n Denominator used by analyst to divide the response variable.
 #' @export
-#' @family back transformation
 divide_back <- function(beta, se, sim, n) {
   simulated <- rnorm(sim, beta, se)
   original <- simulated * n %>%
@@ -243,14 +198,8 @@ divide_back <- function(beta, se, sim, n) {
   return(set)
 }
 
-#' Back transform beta estimates or out-of-sample predictions from models whose response variable has been transformed by the square root
-#' @param beta Analyst beta estimate. Numeric vector of length 1.
-#' @param se Standard error of analyst's beta estimate. Numeric vector of length 1.
-#' @param sim Number of simulations. Numeric vector of length 1.
-#'
-#' @return data frame containing the mean estimate, its standard error, and quantiles
+#' @describeIn back Back transform beta estimates or out-of-sample predictions from models whose response variable has been transformed by the square root
 #' @export
-#' @family back transformation
 square_root_back <- function(beta, se, sim) {
   simulated <- rnorm(sim, beta, se)
   original <- simulated^2 %>%

R/clean_response_transformation.R

@@ -13,12 +13,17 @@
 #' used by the analyst. The `cleaned_transformation` values are the cleaned response transformation values that are equal to the required `transformation` values in [conversion()]. 
 #' The user can supply an alternate table of transformations depending on what is required for the back-transformation functions.
 #' @family back-transformation functions
+#' @seealso To be called after to [assign_transformation_type()]
+#' @examples
+#' clean_response_transformation("power2", ManyEcoEvo:::transformation_tbl) 
+#' clean_response_transformation("log", ManyEcoEvo:::transformation_tbl)
+#' clean_response_transformation("new_transformation", ManyEcoEvo:::transformation_tbl ) # Returns NA if not found
 clean_response_transformation <- function(response_transformation, 
                                           transformation_tbl = ManyEcoEvo:::transformation_tbl) {
   original_data <- tibble(transformation_orig = response_transformation)
 
   out <- original_data %>%
-    left_join(transformation_tbl) %>%
+    left_join(transformation_tbl, by = join_by(transformation_orig)) %>%
     select(cleaned_transformation) %>% # TODO WHAT ABOUT MISSING NON-STANDARD TRANSFORMATIONS??
     flatten_chr()
 

R/compute_MA_inputs.R

@@ -2,7 +2,7 @@
 #' @description Computes the sorensen diversity indices and joins it to the prepared data in preparation for meta-analysing all subsets of data with `meta_analyse_datasets()`.
 #'
 #' @param ManyEcoEvo A dataframe grouped by the character columns `dataset`, `estimate_type`, `exclusion_set`. Each group corresponds to a subset of the full `dataset`, and has the subset analyst data  stored in `data`, with its corresponding subset `diversity_data`.
-#' @param estimate_type
+#' @param estimate_type character string, one of "Zr", "yi", "y25", "y50", "y75".
 #' @details The name of the subset is derived from the funs generated by `subset_fns_yi` and/or `subset_fns_Zr`.
 #'
 #' Computes sorensen diversity indices `diversity_indices` for each subset of data returning them in the list-columns `diversity_indices` and joins them to the subset analyst `data`, returning it in the list-column `effects_analysis`.

R/compute_metaanalysis_inputs.R

@@ -8,7 +8,7 @@
 compute_metaanalysis_inputs <- function(.data, estimate_type = character(1L)) {
   # TODO insert checks that appropriate columns exist
   match.arg(estimate_type, choices = c("Zr", "yi", "y25", "y50", "y75"), several.ok = FALSE)
-  cli::cli_h1(glue::glue("Computing meta-analysis inputs", "for estimate type ", "{estimate_type}"))
+  cli::cli_h1(glue::glue("Computing meta-analysis inputs", " for estimate type ", "{estimate_type}"))
 
   if (estimate_type == "Zr") {
     # Convert Effect Sizes to Zr -------
@@ -40,13 +40,13 @@ compute_metaanalysis_inputs <- function(.data, estimate_type = character(1L)) {
       mutate(
         back_transformed_data =
           pmap(
-            .l = list(
+            .l = list( #TODO bug, missing argument
               augmented_data,
               link_function,
               response_transformation_description
             ),
             .f = ~ if (!rlang::is_na(..1) | !rlang::is_na(..2)) {
-              convert_predictions(
+              convert_predictions( #TODO bug, missing argument
                 augmented_data = ..1,
                 link_fun = ..2,
                 response_transformation = ..3

R/conversion.R

@@ -1,5 +1,5 @@
-#' Conditionally apply back-transformation
-#' @description Conditionally apply back-transformation functions depending on the value of `transformation`
+#' Apply back-transformation to beta estimates
+#' @description Conditionally apply back-transformation functions depending on the value of `transformation`.
 #'
 #' @param beta Beta estimate, numeric vector of length 1.
 #' @param se Standard error of the `beta` estimate, numeric vector of length 1
@@ -21,6 +21,11 @@
 #' * "powerX", where `X` is a numeric
 #' * "divided.by.X", where `X` is a numeric
 #' @export
+#' @import dplyr
+#' @import purrr
+#' @import cli
+#' @import rlang
+#' @import stringr
 conversion <- function(beta, se, transformation, sim = 10000) {
   # Ensure Correct Number of Arguments Supplied
   na_args <- purrr::discard(c(beta, se, transformation), is.na) %>%

R/convert_predictions.R

@@ -4,6 +4,12 @@
 #' @return A tibble of out of sample predictions on the response variable scale of the response variable used by the analyst
 #' @family analysis-values
 #' @export
+#' @import dplyr
+#' @import purrr
+#' @import rlang
+#' @import cli
+#' @importFrom data.table setnames
+#' @importFrom pointblank has_columns
 convert_predictions <- function(augmented_data,
                                 transformation_type,
                                 response_transformation,
@@ -93,7 +99,6 @@ convert_predictions <- function(augmented_data,
         out <- rlang::na_cpl
       }
 
-
       vconvert_double_transformation(
         beta = beta_vals,
         se = augmented_data$se.fit,

R/exclude_extreme_VZ.R

@@ -1,6 +1,6 @@
 #' Exclude extreme values of VZ from a dataframe of standardised predictions
 #'
-#' @param df
+#' @param df A dataframe containing the columns `Z` and `VZ`
 #' @param VZ_cutoff A numeric vector of length 1, values equal to or greater than this value of VZ will be filtered out of `df`.
 #'
 #' @return A dataframe with observations removed where the value is less than that of `VZ\_cutoff`.

R/get_diversity_data.R

@@ -1,6 +1,6 @@
 #' Get Diversity Data
 #'
-#' @param raw_data
+#' @param raw_data A tibble of raw data
 #' @param dataset character string of either "eucalyptus" or "blue tit"
 #' @param variables character vector of any length containing names of variables to get diversity data for
 #'

R/prepare_response_variables_yi.R

@@ -41,7 +41,7 @@ prepare_response_variables_yi <- function(ManyEcoEvo,
 
 #' Back Transform Response Variables - yi
 #'
-#' @param data
+#' @param dat A dataframe of out of sample predictions analyst submission data
 #' @param estimate_type The type of estimate to be standardised. Character vector of length 1, whose value may be  "yi", "y25", "y50", "y75".
 #' @param param_table A table of estimated 'population' parameters for each variable in the analysis datasets.
 #' @param dataset One of either "blue tit" or "eucalyptus"