Update documentation for pkgdown site (and just in general)

R/collapse_group_row.R

@@ -2,6 +2,7 @@
 #'
 #' This function is for replacing repeated rows in a data.frame into NA for nice printing. This
 #' is not intended for use during processing.
+#' It is an alternative to `kableExtra::collapse_rows()` for long tables in latex.
 #'
 #' @param .data a data.frame
 #' @param ... Columns to use to identify which to rows to replace with NA's

R/data.R

@@ -1,4 +1,4 @@
-#' Example BAMA dataset
+#' Example dataset for BAMA (Binding Antibody Multiplex Assay)
 #'
 #' A dataset containing response (0/1) and magnitude (continuous) BAMA data for
 #' 7 antigens, 2 groups, and 3 visits. Can be used to run VISCfunctions examples.
@@ -16,7 +16,7 @@
 #' }
 "exampleData_BAMA"
 
-#' Example ICS dataset
+#' Example dataset for ICS (Intracellular Cytokine Staining) assay
 #'
 #' A dataset containing response (0/1) and magnitude (continuous) ICS data for
 #' 3 cell populations and 2 antigen stimulations. Can be used to run VISCfunctions examples.
@@ -44,7 +44,7 @@
 #' }
 "exampleData_ICS"
 
-#' Example NAb dataset
+#' Example dataset for NAb (Neutralizing Antibody) assay
 #'
 #' A dataset containing response (0/1) and magnitude (continuous) NAb data for
 #' 6 isolates, 4 groups, and 1 visit. Can be used to run VISCfunctions examples.
@@ -67,9 +67,10 @@
 #' }
 "exampleData_NAb"
 
-#' Example mAB dataset from DataSpace
+#' Example dataset for mAB (monoclonal antibody) data
 #'
-#' A subset dataset from the Farzan CAVD 812 Study, looking at eCD4 neutralization.
+#' A subset of data from the Farzan CAVD 812 Study, looking at eCD4 neutralization.
+#' Data is sourced from the CAVD DataSpace (CDS).
 #'
 #' @format A data frame with 480 rows and 4 variables:
 #' \describe{

R/pairwise_comparisons.R

@@ -1,7 +1,7 @@
 #'Pairwise Testing for a Continuous Variable
 #'
 #'Takes a continuous variable and performs pairwise testing (t-test or wilcox
-#'test)
+#'test, paired or unpaired) for all possible combinations of the group variable.
 #'
 #'@param x numeric vector (can include NA values).
 #'@param group categorical vector of group values.
@@ -31,7 +31,7 @@
 #'  missing values.
 #'@param verbose a logical variable indicating if warnings and messages should
 #'  be displayed.
-#'@return Returns a data frame with all possible pairwise comparisons:
+#'@return Returns a data frame covering all possible pairwise comparisons with the following columns:
 #' * `Comparison` - Comparisons made
 #' * `SampleSizes` - number of samples per group
 #' * `Median_Min_Max` - Median \[Min, Max\] per group
@@ -447,7 +447,7 @@ pairwise_test_cont <- function(
 #' @param ... other parameters to pass to Exact::exact.test when running
 #'   Barnard test
 #' @return Returns a data frame with all possible pairwise comparisons.
-#'   Variables include Comparison, ResponseStats (group stats; number positive /
+#'   Columns include Comparison, ResponseStats (group stats; number positive /
 #'  number = rate (Wilson CI Bounds)), ResponseTest (fisher/chisq p value),
 #'  PerfectSeparation (a logical flag indicating if one group if 0% and the
 #'  other 100%)
@@ -741,9 +741,9 @@ pairwise_test_bin <- function(x,
 #'   should be displayed.
 #' @param ... parameters passed to `stats::cor.test` or `coin:spearman_test`
 #'
-#' @return Returns a data frame of all possible pairwise correlations
+#' @return Returns a data frame covering all possible pairwise correlations
 #' with pair sizes greater than or equal to the minimum number of values
-#' in pair, as set by `n_distinct_value`:
+#' in pair, as set by `n_distinct_value`; columns are
 #' * `Correlation` - Comparisons made
 #' * `NPairs` - number of non-missing pairs considered
 #' * `Ties` - are ties present in either variable

R/pretty_output_functions.R

@@ -1,11 +1,11 @@
 #' Pasting Together Information for Two Groups
 #'
-#' Paste together information, often statistics, from two groups. There are three
+#' Paste together information, usually descriptive statistics, from two groups. There are three
 #' predefined combinations: mean(sd) and median\[min, max\] and median\[first quartile, third quartile\], but user may also
 #' paste any single measure together.
 #'
 #'
-#' @param data input dataset. User must use consistent naming throughout,
+#' @param data input dataset (wide). User must use consistent naming throughout,
 #' \strong{with an underscore} to separate the group names from the measures
 #' (i.e. `Group1_mean` and `Group2_mean`). There also must be two
 #' columns with column names that exactly match the input for `first_name`
@@ -37,7 +37,7 @@
 #' `alternative` included as a parameter so the direction can easily be seen in one-sided test. If "two.sided" is selected the value to be pasted between the two group names will be set to `sep_val`, where "greater" will use " > " and "less" with use " < " as the pasting value.
 #'
 #'
-#' @return data.frame with all the pasted values requested. Each name will have '_comparison' at the end of the names (i.e. mean_comparison, median_comparison, ...)
+#' @return Long data.frame with all the pasted values requested. Each name will have '_comparison' at the end of the names (i.e. mean_comparison, median_comparison, ...)
 #' @examples
 #'
 #' library(dplyr)
@@ -289,24 +289,24 @@ paste_tbl_grp <- function(
 
 
 
-#' Rounds and combines up to three numbers into table friendly presentation
+#' Rounds and combines up to three numbers into table-friendly presentation
 #'
 #' Takes in up to 3 numeric values, rounds each to a specified digit amount
 #' (if numeric), and then combines them accordingly.
 #'
-#' @param stat1 first statistic to be pasted.
-#' @param stat2 second statistic to be pasted (optional).
-#' @param stat3 third statistic to be pasted (optional).
+#' @param stat1 first statistic to be pasted (e.g., mean)
+#' @param stat2 optional second statistic to be pasted (e.g., sd/se, p-value, CI lower bound, minimum)
+#' @param stat3 optional third statistic to be pasted (e.g., CI upper bound, maximum, nth percentile).
 #' @param digits positive integer of length 1 between 0 (default) and 14,
-#' giving the amount of digits to round to.
-#' @param trailing_zeros logical indicating if trailing zeros should included
-#' (i.e. 0.100 instead of 0.1). Note is set to TRUE output is a character vector
+#' giving the amount of digits to round stat1, stat2, and stat3 to.
+#' @param trailing_zeros logical indicating if trailing zeros should be included
+#' (i.e. 0.100 instead of 0.1); default is TRUE
 #' @param bound_char the character to be used between stat1 and stat2/stat3.
 #' Available options are '(' (default), '[', '\{', and '|'.
 #' @param sep the string to be used between stat2 and stat3. The default is ', '.
-#' @param na_str_out the character to replace missing values with.
-#' @param suffix a character string to add at the end of each stat
-#' (i.e. `%` if doing response rates)
+#' @param na_str_out the character to replace missing values with (default is '---')
+#' @param suffix an optional character string to add at the end of each stat
+#' (e.g. `%` if doing response rates); default is NULL
 #'
 #' @return string of combined values
 #'
@@ -422,7 +422,7 @@ stat_paste = function(
 #' @param output_type output type, "latex" (default), "html" , "pandoc"
 #' (for Word document output), or "no_markup"
 #'
-#' @return Vector of transformed p-values for table output
+#' @return Character vector of transformed p-values for table output
 #'
 #' @details
 #'

R/reproducibility_tables.R

@@ -1,6 +1,4 @@
-#' Get Full Username from ID
-#'
-#' For a given ID looks up user name
+#' Look up a username from a Fred Hutch ID
 #'
 #' @param id ID to look full name up. If null (default) looks up ID of current
 #'   user
@@ -256,9 +254,9 @@ get_session_info <- function(libpath = FALSE){
 
 #' Shorten git hash
 #'
-#' Internal function for Reproducibility Tables. find '@' followed by 40 hex
-#' digits, and substitute with the '@' and the first 7 hex digits in ()-captured
-#' group.
+#' Internal function for reproducibility tables; used by get_session_info().
+#' Finds '@' followed by 40 hex digits, and substitutes with the '@' and the
+#' first 7 hex digits in ()-captured group.
 #'
 #' @param x String containing `@` followed by long git hash
 #' @return String containing `@` followed by short git hash

R/statistical_tests_and_estimates.R

@@ -1,6 +1,6 @@
 #' Rounding Using Round Away From 0 Method
 #'
-#' round_away_0 takes a numeric vector, rounds them to a specified digit amount using the round away from 0 method for ties (i.e. 1.5). This is the SAS method for rounding.
+#' round_away_0 is an alternative to `round()` to  to properly perform mathematical rounding. It takes a numeric vector, and rounds values to a specified digit amount using the round away from 0 method for ties (e.g., 1.5). This is the SAS method for rounding.
 #'
 #' @param x numeric vector (can include NA values).
 #' @param digits positive integer of length 1 between 0 (default) and 14, giving the amount of digits to round to.
@@ -71,7 +71,7 @@ round_away_0 <- function(x, digits = 0, trailing_zeros = FALSE){
 }
 
 
-#' Continuous Variable Compared to Binary Variable Test (VISC)
+#' Continuous (Response) Variable Compared across Binary (Group) Variable
 #'
 #' Either Wilcox or T-Test Performed, for unpaired or paired data
 #'
@@ -135,7 +135,7 @@ two_samp_cont_test <- function(x, y, method = c('wilcox', 't.test'), paired = FA
 
 
 
-#' Binary (Response) Variable Compared to Binary (Group) Variable Test (VISC)
+#' Binary (Response) Variable Compared across Binary (Group) Variable
 #'
 #' Either Barnard, Fisher's, or Chi-sq test performed for unpaired data and
 #'   McNemar's test for paired data
@@ -254,14 +254,15 @@ two_samp_bin_test <- function(x, y, method = c('barnard', 'fisher' ,'chi.sq' , '
 
 #' Correlation Test for Two Continuous Variables
 #'
-#' This function is a wrapper for [stats::cor.test] function, except if
-#' `method = "spearman"` is selected and there are ties in at least one
+#' This function performs a test to determine if the value of the association
+#' between two continuous variables equals zero. It is a wrapper for [stats::cor.test],
+#' except if `method = "spearman"` is selected and there are ties in at least one
 #' variable, in which case this is a wrapper for [coin::spearman_test]
 #' employing the approximate method.
 #'
 #'
-#' @param x numeric vector (can include NA values).
-#' @param y numeric vector (can include NA values).
+#' @param x numeric vector (can include NA values) representing variable 1
+#' @param y numeric vector (can include NA values) representing variable 2
 #' @param method a character string indicating which correlation coefficient
 #'   is to be used for the test. One of "pearson", "kendall", or "spearman",
 #'   can be abbreviated to "p", "k", or "s".
@@ -275,7 +276,7 @@ two_samp_bin_test <- function(x, y, method = c('barnard', 'fisher' ,'chi.sq' , '
 #' @param verbose a logical variable indicating if warnings and messages
 #'   should be displayed.
 #' @param ... parameters passed to [stats::cor.test] or [coin::spearman_test]
-#' @return correlation estimate p value.
+#' @return estimated p-value.
 #'
 #' @details
 #'
@@ -430,7 +431,7 @@ wilson_ci <- function(x, conf.level = .95){
 #'
 #' `r lifecycle::badge("stable")`
 #'
-#' Wrapper for [binom::binom.confint]
+#' Wrapper for [binom::binom.confint] that estimates binomial confidence intervals for a binary vector.
 #'
 #' @param x vector of type integer (0/1) or logical (TRUE/FALSE)
 #' @param conf.level confidence level (between 0 and 1). Default is 0.95.
@@ -441,14 +442,13 @@ wilson_ci <- function(x, conf.level = .95){
 #'
 #' See [binom::binom.confint] for method details
 #'
-#' @return data.frame with with mean (`mean`), and bounds of confidence interval (`lower`, `upper`)
-#' @return Returns a data frame with the following columns:
+#' @return Returns a data frame of summary statistics with the following columns:
 #' * `method` - method(s) selected
 #' * `x` - number of successes in the binomial experiment
 #' * `n` - number of independent trials in the binomial experiment
 #' * `mean` -  success proportion mean
-#' * `lower` - success proportion lower bound
-#' * `upper` - success proportion upper bound
+#' * `lower` - success proportion confidence internal lower bound
+#' * `upper` - success proportion confidence internal upper bound
 #'
 #' @examples
 #'

R/step_curves.R

@@ -6,8 +6,8 @@
 #' step line outcomes such as time-to-event (Kaplan-Meier curves) and magnitude
 #' breadth (MB) curves.
 #'
-#' @param x Time values used to create the x-axis in step curves (numeric
-#'   vector)
+#' @param x Values used to create the x-axis in step curves (numeric
+#'   vector) - typically time, or net-MFI for MB.
 #' @param event event status, 0=censor and 1=event (numeric vector). If NULL
 #'   assumes no censoring
 #' @param flip_surv logical indicating if reverse survival estimates should be