From e1085f247760d5f1e3df58be0b8e228371417e20 Mon Sep 17 00:00:00 2001
From: egouldo <egouldo@users.noreply.github.com>
Date: Thu, 5 Sep 2024 14:36:54 +1000
Subject: [PATCH] docs!: #146 `devtools::document()`

---
 NAMESPACE                        |  7 +++
 man/exclude_extreme_estimates.Rd | 85 ++++++++++++++++++++++++++++++++
 man/fit_multivar_MA.Rd           |  1 +
 3 files changed, 93 insertions(+)
 create mode 100644 man/exclude_extreme_estimates.Rd

diff --git a/NAMESPACE b/NAMESPACE
index 5ba378a..84e698a 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -131,6 +131,7 @@ importFrom(cli,cli_alert_warning)
 importFrom(cli,cli_bullets)
 importFrom(cli,cli_h1)
 importFrom(cli,cli_h2)
+importFrom(cli,cli_h3)
 importFrom(cli,cli_ol)
 importFrom(cli,cli_warn)
 importFrom(cli,style_italic)
@@ -214,10 +215,14 @@ importFrom(recipes,update_role)
 importFrom(rlang,"!!")
 importFrom(rlang,":=")
 importFrom(rlang,as_function)
+importFrom(rlang,as_quosures)
 importFrom(rlang,as_string)
 importFrom(rlang,caller_env)
+importFrom(rlang,current_env)
 importFrom(rlang,enquo)
+importFrom(rlang,enquos)
 importFrom(rlang,ensym)
+importFrom(rlang,env)
 importFrom(rlang,exec)
 importFrom(rlang,expr)
 importFrom(rlang,exprs)
@@ -229,6 +234,7 @@ importFrom(rlang,is_na)
 importFrom(rlang,is_null)
 importFrom(rlang,na_chr)
 importFrom(rlang,new_formula)
+importFrom(rlang,quo_set_env)
 importFrom(sae,bxcx)
 importFrom(see,geom_jitter2)
 importFrom(see,scale_fill_material_d)
@@ -255,6 +261,7 @@ importFrom(tidyr,unite)
 importFrom(tidyr,unnest)
 importFrom(tidyr,unnest_longer)
 importFrom(tidyselect,all_of)
+importFrom(tidyselect,any_of)
 importFrom(tidyselect,where)
 importFrom(timetk,step_box_cox)
 importFrom(workflows,add_model)
diff --git a/man/exclude_extreme_estimates.Rd b/man/exclude_extreme_estimates.Rd
new file mode 100644
index 0000000..ac66067
--- /dev/null
+++ b/man/exclude_extreme_estimates.Rd
@@ -0,0 +1,85 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/exclude_extreme_estimates.R
+\name{exclude_extreme_estimates}
+\alias{exclude_extreme_estimates}
+\title{Exclude extreme estimates above a threshold parameter sd}
+\usage{
+exclude_extreme_estimates(
+  data,
+  outcome_variable,
+  outcome_SE,
+  sd_threshold = numeric(1L),
+  param_table,
+  .fn = ...,
+  ...
+)
+}
+\arguments{
+\item{data}{A dataframe of analyst estimates}
+
+\item{outcome_variable}{the name of the variable in \code{data} containing the analyst estimates}
+
+\item{outcome_SE}{variable in \code{data} containing analyst SE estimates}
+
+\item{sd_threshold}{A numeric threshold multiplyer see details}
+
+\item{param_table}{A dataframe containing population parameters \code{mean} and \code{sd} for each \code{variable} in a given \code{dataset}}
+
+\item{.fn}{An optional function that will transform parameter estimates to the same scale as \code{outcome_variable} in \code{data}}
+
+\item{...}{Arguments supplied to \code{.fn}}
+}
+\value{
+A dataframe of analyst estimates with extreme estimates excluded
+}
+\description{
+Exclude extreme estimates above a threshold parameter sd
+}
+\details{
+This function is used to exclude extreme estimates from a dataset. The function
+calculates a threshold for exclusion based on the mean and standard deviation of
+the population parameter estimates in \code{param_table}. The threshold is calculated
+as the mean of the population parameter plus \code{sd_threshold} times the standard
+deviation of the population parameter. Estimates in \code{data} that are greater than
+this threshold are excluded from the output.
+
+If the user chooses to supply \code{.fn} and \code{...} arguments, the function will transform
+the population parameter estimates in \code{param_table} to the same scale as the
+\code{outcome_variable} in \code{data} using \code{.fn}, before calculating the threshold for exclusion.
+}
+\examples{
+# example code
+data <-   ManyEcoEvo_yi \%>\% 
+mutate(data = 
+         map_if(data, 
+                ~ filter(.x, 
+                         stringr::str_detect(response_variable_name, 
+                                             "average.proportion.of.plots.containing",
+                                             negate = TRUE)),
+                .p = dataset == "eucalyptus")) \%>\%   
+  mutate(
+    diversity_data =
+      map2(
+        .x = diversity_data,
+        .y = data,
+        .f = ~ semi_join(.x, .y, join_by(id_col)) \%>\% 
+          distinct()
+      )
+  ) \%>\% 
+  prepare_response_variables(
+    estimate_type = "yi",
+    param_table = 
+      ManyEcoEvo:::analysis_data_param_tables, 
+    dataset_standardise = "blue tit",
+    dataset_log_transform = "eucalyptus") \%>\%
+  generate_yi_subsets() \%>\% #TODO: must be run after prepare_response_variables??
+  apply_VZ_exclusions(
+    VZ_colname = list("eucalyptus" = "se_log", 
+                      "blue tit" = "VZ"), 
+    VZ_cutoff = 3) \%>\% 
+  filter(dataset == "eucalyptus", estimate_type == "y25")  \%>\% 
+  pluck("data", 1)
+sd_threshold = 3
+param_table <- ManyEcoEvo:::analysis_data_param_tables
+exclude_extreme_estimates(data, "mean_log", "se_log", 3, param_table, log_transform, estimate = mean, std.error = sd)
+}
diff --git a/man/fit_multivar_MA.Rd b/man/fit_multivar_MA.Rd
index f8bd750..4593a55 100644
--- a/man/fit_multivar_MA.Rd
+++ b/man/fit_multivar_MA.Rd
@@ -32,6 +32,7 @@ Expects the following columns in \code{data_tbl}:
 \item \code{box_cox_abs_deviation_score_estimate}: response variable, Box-Cox transformed deviation from the meta-analytic mean effect-size for each analysis
 \item \code{mixed_model}: binary variable indicating whether the analysis used a mixed effects model or not
 \item \code{ReviewerId}: reviewer identifier
+\item one of \code{study_id} or \code{id_col} to uniquely identify each analysis for checking that the threshold \code{N} is met.
 }
 }
 \seealso{