diff --git a/R/collapse_group_row.R b/R/collapse_group_row.R index 451342c..42f1884 100644 --- a/R/collapse_group_row.R +++ b/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 diff --git a/R/data.R b/R/data.R index b8460c5..5a62fb7 100644 --- a/R/data.R +++ b/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{ diff --git a/R/pairwise_comparisons.R b/R/pairwise_comparisons.R index 62af1d2..e0617ed 100644 --- a/R/pairwise_comparisons.R +++ b/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 diff --git a/R/pretty_output_functions.R b/R/pretty_output_functions.R index c9041c6..f9d9847 100644 --- a/R/pretty_output_functions.R +++ b/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 #' diff --git a/R/reproducibility_tables.R b/R/reproducibility_tables.R index c070a08..9b64651 100644 --- a/R/reproducibility_tables.R +++ b/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 diff --git a/R/statistical_tests_and_estimates.R b/R/statistical_tests_and_estimates.R index 3f814f6..4c54690 100644 --- a/R/statistical_tests_and_estimates.R +++ b/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 #' diff --git a/R/step_curves.R b/R/step_curves.R index 426088b..d46f96b 100644 --- a/R/step_curves.R +++ b/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 diff --git a/R/trapz_sorted.R b/R/trapz_sorted.R index 21da307..8405784 100644 --- a/R/trapz_sorted.R +++ b/R/trapz_sorted.R @@ -1,81 +1,81 @@ -#' Sorted Trapezoidal Integration -#' -#' This function is a wrapper for the `trapz` function. It sorts the x and y values -#' so that it is monotonically increasing along the x values. Then computes the -#' area of a function with values `y` and points `x`. There is an optional -#' parameter to remove any NA values so that integration can proceed by -#' omitting the `x` and `y` values where the NA occurred. -#' -#' @param x A vector of numeric values representing the x-axis over which to integrate. -#' @param y A vector of numeric values representing the y-axis. -#' @param na.rm A logical indicating whether to remove NA values from both x and y values. -#' @return Approximated integral of the function, discretized through the points -#' x, y, from \code{min(x)} to \code{max(x)}. -#' -#' @details -#'The points (x, 0) and (x, y) are taken as vertices of a polygon. The area is -#'computed using the trapezoid rule for approximation the definite integral of -#'the function. -#' -#' @examples -#' set.seed(93) -#' -#' # Calculate the area under the sine curve from 0 to pi: -#' n <- 101 -#' x <- seq(0, pi, len = n) -#' y <- sin(x) -#' trapz_sorted(x, y) -#' -#' # Calculate area under the curve for unsorted data: -#' x <- sample(1:n, n, replace = FALSE) -#' y <- runif(n, 0, 33) -#' trapz_sorted(x, y) -#' -#' # Calculate the area without NA removal -#' x[10] <- NA -#' y[3] <- NA -#' # Will fail to produce a result -#' trapz_sorted(x, y, na.rm=FALSE) -#' trapz_sorted(x, y, na.rm=TRUE) -#' -#' -#' -#' @export -#' -trapz_sorted <- function(x, y, na.rm = TRUE){ - # Input Checking - .check_numeric_input(x, allow_dup = FALSE) - .check_numeric_input(y) - m <- length(x) - if (length(y) != m) stop("Arguments 'x', 'y' must be vectors of the same length.") - if (na.rm == TRUE) { - # Sort by increasing values, NA are removed from x - x <- x[order(x, decreasing = FALSE, method = "auto", na.last = NA)] - y <- y[order(x, decreasing = FALSE, method = "auto", na.last = NA)] - # NA removed from y - x <- x[!is.na(y)] - y <- y[!is.na(y)] - } else{ - # Warn that data points will be removed if NA - if (anyNA(x)) warning("NA values are present in the 'x' values. Returns NA.") - if (anyNA(y)) warning("NA values are present in the 'y' values. Returns NA.") - # Sort by increasing values, NA are not removed - x <- x[order(x, decreasing = FALSE, method = "auto")] - y <- y[order(x, decreasing = FALSE, method = "auto")] - } - # Check for length of x and y after NA removal - m <- length(x) - if (m < 2) { - warning("There are less than 2 observations with non-missing values of both 'x' and 'y', so NA returned.") - return(NA) - } else { - # Integrate - xp <- c(x, x[m:1]) - yp <- c(numeric(m), y[m:1]) - n <- 2 * m - p1 <- sum(xp[1:(n - 1)] * yp[2:n]) + xp[n] * yp[1] - p2 <- sum(xp[2:n] * yp[1:(n - 1)]) + xp[1] * yp[n] - return(0.5 * (p1 - p2)) - } -} - +#' Sorted Trapezoidal Integration +#' +#' This function is a wrapper for the `pracma::trapz` function. It sorts the x and y values +#' so that it is monotonically increasing along the x values. Then computes the +#' area of a function with values `y` and points `x`. There is an optional +#' parameter to remove any NA values so that integration can proceed by +#' omitting the `x` and `y` values where the NA occurred. +#' +#' @param x A vector of numeric values representing the x-axis over which to integrate. +#' @param y A vector of numeric values representing the y-axis. +#' @param na.rm A logical indicating whether to remove NA values from both x and y values. +#' @return Numeric value of approximated integral of the function, discretized through the points +#' x, y, from \code{min(x)} to \code{max(x)}. +#' +#' @details +#'The points (x, 0) and (x, y) are taken as vertices of a polygon. The area is +#'computed using the trapezoid rule for approximation the definite integral of +#'the function. +#' +#' @examples +#' set.seed(93) +#' +#' # Calculate the area under the sine curve from 0 to pi: +#' n <- 101 +#' x <- seq(0, pi, len = n) +#' y <- sin(x) +#' trapz_sorted(x, y) +#' +#' # Calculate area under the curve for unsorted data: +#' x <- sample(1:n, n, replace = FALSE) +#' y <- runif(n, 0, 33) +#' trapz_sorted(x, y) +#' +#' # Calculate the area without NA removal +#' x[10] <- NA +#' y[3] <- NA +#' # Will fail to produce a result +#' trapz_sorted(x, y, na.rm=FALSE) +#' trapz_sorted(x, y, na.rm=TRUE) +#' +#' +#' +#' @export +#' +trapz_sorted <- function(x, y, na.rm = TRUE){ + # Input Checking + .check_numeric_input(x, allow_dup = FALSE) + .check_numeric_input(y) + m <- length(x) + if (length(y) != m) stop("Arguments 'x', 'y' must be vectors of the same length.") + if (na.rm == TRUE) { + # Sort by increasing values, NA are removed from x + x <- x[order(x, decreasing = FALSE, method = "auto", na.last = NA)] + y <- y[order(x, decreasing = FALSE, method = "auto", na.last = NA)] + # NA removed from y + x <- x[!is.na(y)] + y <- y[!is.na(y)] + } else{ + # Warn that data points will be removed if NA + if (anyNA(x)) warning("NA values are present in the 'x' values. Returns NA.") + if (anyNA(y)) warning("NA values are present in the 'y' values. Returns NA.") + # Sort by increasing values, NA are not removed + x <- x[order(x, decreasing = FALSE, method = "auto")] + y <- y[order(x, decreasing = FALSE, method = "auto")] + } + # Check for length of x and y after NA removal + m <- length(x) + if (m < 2) { + warning("There are less than 2 observations with non-missing values of both 'x' and 'y', so NA returned.") + return(NA) + } else { + # Integrate + xp <- c(x, x[m:1]) + yp <- c(numeric(m), y[m:1]) + n <- 2 * m + p1 <- sum(xp[1:(n - 1)] * yp[2:n]) + xp[n] * yp[1] + p2 <- sum(xp[2:n] * yp[1:(n - 1)]) + xp[1] * yp[n] + return(0.5 * (p1 - p2)) + } +} + diff --git a/README.Rmd b/README.Rmd deleted file mode 100644 index 6ad3809..0000000 --- a/README.Rmd +++ /dev/null @@ -1,98 +0,0 @@ ---- -output: github_document ---- - - - [![R build status](https://github.com/FredHutch/VISCfunctions/workflows/R-CMD-check/badge.svg)](https://github.com/FredHutch/VISCfunctions/actions) -[![Codecov test coverage](https://codecov.io/gh/FredHutch/VISCfunctions/graph/badge.svg)](https://app.codecov.io/gh/FredHutch/VISCfunctions) - [![License:MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) - - - -```{r setup, include = FALSE} -knitr::opts_chunk$set( - collapse = TRUE, - comment = "#>", - fig.path = "man/figures/README-", - out.width = "100%" -) -``` - -# VISCfunctions - -The package provides functions for common tasks for creating statistical reports at Vaccine Immunology Statistical Center (VISC). The goal of VISCfunctions is to: - -* provide standard statistical testing and estimating functions -* help format output for PDF and Word reports -* provide frequently used utility functions - -for VISC statisticians and programmers at Fred Hutch. - -# Installation - -The package is available on the Fred Hutch organization GitHub page. - -```{r eval=FALSE} -remotes::install_github("FredHutch/VISCfunctions") - -# Use the build_vignettes parameter to access the vignette -# (Note that this may auto-upgrade dependencies - this behavior can be controlled with the `upgrade` argument) -remotes::install_github("FredHutch/VISCfunctions", dependencies = TRUE, build_vignettes = TRUE) -vignette("Overview") -``` - -# Overview - -Below is an overview of the currently available functions in VISCfunctions. - -## Statistical testing and estimates - -Compare two groups, return a p-value: - -* `two_sample_bin_test()` for a Barnard, Fisher's Exact, Chi-Square or McNemar test. -* `two_samp_cont_test()` for a t.test (paired or unpaired), Wilcox Rank-Sum, or Wilcox Signed-Rank test. -* `cor_test()` for a Spearman, Pearson, or Kendall correlation test. - -Make all pairwise comparisons of a grouping variable (or any categorical variable), return descriptive statistics and p-values: - -* `pairwise_test_bin()` for a Barnard, Fisher's Exact, Chi-Square or McNemar test. -* `pairwise_test_cont()` for a t.test (paired or unpaired), Wilcox Rank-Sum, or Wilcox Signed-Rank test. -* `cor_test_pairs()` for a Spearman, Pearson, or Kendall correlation test. - -Estimate binomial confidence intervals for a binary vector: - -* `binom_ci()` - -## Formatting output - -* `paste_tbl_grp()` to paste together information (usually descriptive statistics) from two groups. -* `pretty_pvalues()` to round and format p-values. -* `stat_paste()` to combine and format values, such as: - + Mean (sd) - + Median [min, max] - + Estimate (SE of Estimate) - + Estimate (95% CI Lower Bound, Upper Bound) - + Estimate/Statistic (p value) -* `escape()` to protect control characters in a string for use in a latex table or caption -* `collapse_group_row()` as an alternative to `kableExtra::collapse_rows()` for long tables in latex - -## Survival and Magnitude Breadth - -* `create_step_curve()` to create survival probabilities and generate a risk table -* `mb_results()` to create step curve info for magnitude breadth (MB) plots and AUC-MB - -## Utility functions - -* `round_away_0()` is an alternative to the `round()` function to properly perform mathematical rounding. -* `escape()` is used to inserts a "\\" in front of values, which is needed for Latex. -* `get_full_name()` looks up a username from Fred Hutch ID. -* `get_session_info()` creates a a data frame with session information. - - -# Vignette - -For more information, browse the vignette (`browseVignettes("VISCfunctions")`). - -# Contribute to this package - -See our [contributing guide](CONTRIBUTING.md) to learn more about how you can contribute to this package. diff --git a/README.md b/README.md index dae75a4..69e00c0 100644 --- a/README.md +++ b/README.md @@ -6,23 +6,26 @@ status](https://github.com/FredHutch/VISCfunctions/workflows/R-CMD-check/badge.s [![Codecov test coverage](https://codecov.io/gh/FredHutch/VISCfunctions/graph/badge.svg)](https://app.codecov.io/gh/FredHutch/VISCfunctions) [![License:MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + # VISCfunctions -The package provides functions for common tasks for creating statistical -reports at Vaccine Immunology Statistical Center (VISC). The goal of -VISCfunctions is to: - -- provide standard statistical testing and estimating functions -- help format output for PDF and Word reports -- provide frequently used utility functions +VISCfunctions is an open-source R package that helps automate and +standardize common tasks that are part of the process of analysis at the +Vaccine & Immunology Statistical Center (VISC) at Fred Hutch. The scope +of VISCfunctions is to aid VISC statisticians and programmers by +providing: -for VISC statisticians and programmers at Fred Hutch. +- standard statistical testing and estimating functions +- standard figure and table formatting functions +- utility functions for formatting PDF and Word output +- utility functions that aid with transparency and reproducibility +- example datasets for common lab assays -# Installation +## Installation -The package is available on the Fred Hutch organization GitHub page. +The package is available through the Fred Hutch GitHub organization: ``` r remotes::install_github("FredHutch/VISCfunctions") @@ -30,76 +33,23 @@ remotes::install_github("FredHutch/VISCfunctions") # Use the build_vignettes parameter to access the vignette # (Note that this may auto-upgrade dependencies - this behavior can be controlled with the `upgrade` argument) remotes::install_github("FredHutch/VISCfunctions", dependencies = TRUE, build_vignettes = TRUE) -vignette("Overview") ``` -# Overview - -Below is an overview of the currently available functions in -VISCfunctions. - -## Statistical testing and estimates - -Compare two groups, return a p-value: - -- `two_sample_bin_test()` for a Barnard, Fisher’s Exact, Chi-Square or - McNemar test. -- `two_samp_cont_test()` for a t.test (paired or unpaired), Wilcox - Rank-Sum, or Wilcox Signed-Rank test. -- `cor_test()` for a Spearman, Pearson, or Kendall correlation test. - -Make all pairwise comparisons of a grouping variable (or any categorical -variable), return descriptive statistics and p-values: - -- `pairwise_test_bin()` for a Barnard, Fisher’s Exact, Chi-Square or - McNemar test. -- `pairwise_test_cont()` for a t.test (paired or unpaired), Wilcox - Rank-Sum, or Wilcox Signed-Rank test. -- `cor_test_pairs()` for a Spearman, Pearson, or Kendall correlation - test. - -Estimate binomial confidence intervals for a binary vector: +Documentation can be viewed at + and also through standard R +syntax such as: -- `binom_ci()` - -## Formatting output - -- `paste_tbl_grp()` to paste together information (usually descriptive - statistics) from two groups. -- `pretty_pvalues()` to round and format p-values. -- `stat_paste()` to combine and format values, such as: - - Mean (sd) - - Median \[min, max\] - - Estimate (SE of Estimate) - - Estimate (95% CI Lower Bound, Upper Bound) - - Estimate/Statistic (p value) -- `escape()` to protect control characters in a string for use in a - latex table or caption -- `collapse_group_row()` as an alternative to - `kableExtra::collapse_rows()` for long tables in latex - -## Survival and Magnitude Breadth - -- `create_step_curve()` to create survival probabilities and generate a - risk table -- `mb_results()` to create step curve info for magnitude breadth (MB) - plots and AUC-MB - -## Utility functions - -- `round_away_0()` is an alternative to the `round()` function to - properly perform mathematical rounding. -- `escape()` is used to inserts a “\\” in front of values, which is - needed for Latex. -- `get_full_name()` looks up a username from Fred Hutch ID. -- `get_session_info()` creates a a data frame with session information. - -# Vignette +``` r +library(VISCfunctions) +browseVignettes("VISCfunctions") +vignette("Overview") +help(two_samp_bin_test) # or ?two_sample_bin_test; similarly for other functions +``` -For more information, browse the vignette -(`browseVignettes("VISCfunctions")`). +## Contribute to this package -# Contribute to this package +You can file an issue or feature request on GitHub: + -See our [contributing guide](CONTRIBUTING.md) to learn more about how you -can contribute to this package. +See our [contributing guide](CONTRIBUTING.md) to learn more about how +you can contribute. diff --git a/_pkgdown.yml b/_pkgdown.yml index 2062931..9f869a3 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -2,3 +2,60 @@ url: https://fredhutch.github.io/VISCfunctions/ template: bootstrap: 5 +navbar: + structure: + left: + - home + - reference + - vignettes # instead of default "articles" + - news # instead of default "changelog" + components: + vignettes: + text: "Vignettes" + href: articles/index.html + news: + text: "News" + href: news/index.html + + +reference: + - title: "General Statistical Tests" + desc: "Formal hypothesis testing and p-value computations" + contents: + - two_samp_bin_test + - two_samp_cont_test + - cor_test + - pairwise_test_bin + - pairwise_test_cont + - cor_test_pairs + - binom_ci + - wilson_ci + + - title: "Survival and Magnitude Breadth" + contents: + - create_step_curve + - mb_results + - trapz_sorted + + - title: "Figure, Table, PDF/Word Output Formatting" + contents: + - collapse_group_row + - escape + - paste_tbl_grp + - pretty_pvalues + - round_away_0 + - stat_paste + + - title: "Transparency and Reproducibility" + contents: + - get_full_name + - get_session_info + - shorten_git_hash + + - title: "Example Datasets" + contents: + - exampleData_BAMA + - exampleData_ICS + - exampleData_NAb + - CAVD812_mAB + - G001_Bcell_flow_seq_PBMC diff --git a/man/CAVD812_mAB.Rd b/man/CAVD812_mAB.Rd index 5d671f3..017a259 100644 --- a/man/CAVD812_mAB.Rd +++ b/man/CAVD812_mAB.Rd @@ -3,7 +3,7 @@ \docType{data} \name{CAVD812_mAB} \alias{CAVD812_mAB} -\title{Example mAB dataset from DataSpace} +\title{Example dataset for mAB (monoclonal antibody) data} \format{ A data frame with 480 rows and 4 variables: \describe{ @@ -20,6 +20,7 @@ A data frame with 480 rows and 4 variables: CAVD812_mAB } \description{ -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). } \keyword{datasets} diff --git a/man/VISCfunctions-package.Rd b/man/VISCfunctions-package.Rd index cd6f1ec..bbc5bde 100644 --- a/man/VISCfunctions-package.Rd +++ b/man/VISCfunctions-package.Rd @@ -5,7 +5,7 @@ \alias{VISCfunctions-package} \title{VISCfunctions: VISCfunctions} \description{ -Statistical, data processing, and annotation functions for VISC. +Statistical, data processing, and annotation functions for VISC statisticians and programmers. } \seealso{ Useful links: diff --git a/man/VISCfunctions.Rd b/man/VISCfunctions.Rd index ddcd9d7..f11efd9 100644 --- a/man/VISCfunctions.Rd +++ b/man/VISCfunctions.Rd @@ -5,7 +5,7 @@ \alias{VISCfunctions} \title{VISCfunctions: VISC STP/SRA functions} \description{ -Statistical, data processing, and annotation functions for VISC. +Statistical, data processing, and annotation functions for VISC statisticians and programmers. } \seealso{ Useful links: diff --git a/man/binom_ci.Rd b/man/binom_ci.Rd index faad482..343d838 100644 --- a/man/binom_ci.Rd +++ b/man/binom_ci.Rd @@ -16,22 +16,20 @@ binom_ci(x, conf.level = 0.95, methods = "wilson", ...) \item{...}{Additional arguments to be passed to \link[binom:binom.bayes]{binom::binom.bayes}} } \value{ -data.frame with with mean (\code{mean}), and bounds of confidence interval (\code{lower}, \code{upper}) - -Returns a data frame with the following columns: +Returns a data frame of summary statistics with the following columns: \itemize{ \item \code{method} - method(s) selected \item \code{x} - number of successes in the binomial experiment \item \code{n} - number of independent trials in the binomial experiment \item \code{mean} - success proportion mean -\item \code{lower} - success proportion lower bound -\item \code{upper} - success proportion upper bound +\item \code{lower} - success proportion confidence internal lower bound +\item \code{upper} - success proportion confidence internal upper bound } } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Wrapper for \link[binom:binom.confint]{binom::binom.confint} +Wrapper for \link[binom:binom.confint]{binom::binom.confint} that estimates binomial confidence intervals for a binary vector. } \details{ See \link[binom:binom.confint]{binom::binom.confint} for method details diff --git a/man/collapse_group_row.Rd b/man/collapse_group_row.Rd index 3a05ff8..a41ce1e 100644 --- a/man/collapse_group_row.Rd +++ b/man/collapse_group_row.Rd @@ -19,6 +19,7 @@ a data.frame where repeated rows in the columns identified by ... are replaced w \description{ 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 \code{kableExtra::collapse_rows()} for long tables in latex. } \examples{ sample_df <- data.frame( diff --git a/man/cor_test.Rd b/man/cor_test.Rd index d6243b5..43bd098 100644 --- a/man/cor_test.Rd +++ b/man/cor_test.Rd @@ -16,9 +16,9 @@ cor_test( ) } \arguments{ -\item{x}{numeric vector (can include NA values).} +\item{x}{numeric vector (can include NA values) representing variable 1} -\item{y}{numeric vector (can include NA values).} +\item{y}{numeric vector (can include NA values) representing variable 2} \item{method}{a character string indicating which correlation coefficient is to be used for the test. One of "pearson", "kendall", or "spearman", @@ -40,11 +40,12 @@ should be displayed.} \item{...}{parameters passed to \link[stats:cor.test]{stats::cor.test} or \link[coin:CorrelationTests]{coin::spearman_test}} } \value{ -correlation estimate p value. +estimated p-value. } \description{ -This function is a wrapper for \link[stats:cor.test]{stats::cor.test} function, except if -\code{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 \link[stats:cor.test]{stats::cor.test}, +except if \code{method = "spearman"} is selected and there are ties in at least one variable, in which case this is a wrapper for \link[coin:CorrelationTests]{coin::spearman_test} employing the approximate method. } diff --git a/man/cor_test_pairs.Rd b/man/cor_test_pairs.Rd index cc38f7b..57f0b4c 100644 --- a/man/cor_test_pairs.Rd +++ b/man/cor_test_pairs.Rd @@ -57,9 +57,9 @@ should be displayed.} \item{...}{parameters passed to \code{stats::cor.test} or \code{coin:spearman_test}} } \value{ -Returns a data frame of all possible pairwise correlations +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 \code{n_distinct_value}: +in pair, as set by \code{n_distinct_value}; columns are \itemize{ \item \code{Correlation} - Comparisons made \item \code{NPairs} - number of non-missing pairs considered diff --git a/man/create_step_curve.Rd b/man/create_step_curve.Rd index 3e9febd..e48e118 100644 --- a/man/create_step_curve.Rd +++ b/man/create_step_curve.Rd @@ -7,8 +7,8 @@ create_step_curve(x, event = NULL, flip_surv = FALSE, flip_top_x = Inf) } \arguments{ -\item{x}{Time values used to create the x-axis in step curves (numeric -vector)} +\item{x}{Values used to create the x-axis in step curves (numeric +vector) - typically time, or net-MFI for MB.} \item{event}{event status, 0=censor and 1=event (numeric vector). If NULL assumes no censoring} diff --git a/man/exampleData_BAMA.Rd b/man/exampleData_BAMA.Rd index e142402..b4787cc 100644 --- a/man/exampleData_BAMA.Rd +++ b/man/exampleData_BAMA.Rd @@ -3,7 +3,7 @@ \docType{data} \name{exampleData_BAMA} \alias{exampleData_BAMA} -\title{Example BAMA dataset} +\title{Example dataset for BAMA (Binding Antibody Multiplex Assay)} \format{ A data frame with 252 rows and 6 variables: \describe{ diff --git a/man/exampleData_ICS.Rd b/man/exampleData_ICS.Rd index 6b0b136..598275c 100644 --- a/man/exampleData_ICS.Rd +++ b/man/exampleData_ICS.Rd @@ -3,7 +3,7 @@ \docType{data} \name{exampleData_ICS} \alias{exampleData_ICS} -\title{Example ICS dataset} +\title{Example dataset for ICS (Intracellular Cytokine Staining) assay} \format{ A data frame with 306 rows and 15 variables: \describe{ diff --git a/man/exampleData_NAb.Rd b/man/exampleData_NAb.Rd index 1fa48cc..1a75456 100644 --- a/man/exampleData_NAb.Rd +++ b/man/exampleData_NAb.Rd @@ -3,7 +3,7 @@ \docType{data} \name{exampleData_NAb} \alias{exampleData_NAb} -\title{Example NAb dataset} +\title{Example dataset for NAb (Neutralizing Antibody) assay} \format{ A data frame with 210 rows and 9 variables: \describe{ diff --git a/man/get_full_name.Rd b/man/get_full_name.Rd index b0d083c..ea2520b 100644 --- a/man/get_full_name.Rd +++ b/man/get_full_name.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/reproducibility_tables.R \name{get_full_name} \alias{get_full_name} -\title{Get Full Username from ID} +\title{Look up a username from a Fred Hutch ID} \usage{ get_full_name(id = NULL) } @@ -14,7 +14,7 @@ user} First and Last name associated with ID } \description{ -For a given ID looks up user name +Look up a username from a Fred Hutch ID } \details{ If \code{id} null, uses system "USERNAME" variable for Windows and "USER" diff --git a/man/pairwise_test_bin.Rd b/man/pairwise_test_bin.Rd index cca4305..a488c81 100644 --- a/man/pairwise_test_bin.Rd +++ b/man/pairwise_test_bin.Rd @@ -77,7 +77,7 @@ Barnard test} } \value{ 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\%) diff --git a/man/pairwise_test_cont.Rd b/man/pairwise_test_cont.Rd index c7c2df3..e55d473 100644 --- a/man/pairwise_test_cont.Rd +++ b/man/pairwise_test_cont.Rd @@ -65,7 +65,7 @@ missing values.} be displayed.} } \value{ -Returns a data frame with all possible pairwise comparisons: +Returns a data frame covering all possible pairwise comparisons with the following columns: \itemize{ \item \code{Comparison} - Comparisons made \item \code{SampleSizes} - number of samples per group @@ -85,7 +85,7 @@ separation). } \description{ 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. } \details{ Runs \code{wilcox_test()} in the coin package, with "exact" distribution. diff --git a/man/paste_tbl_grp.Rd b/man/paste_tbl_grp.Rd index c86d46d..ecf40ea 100644 --- a/man/paste_tbl_grp.Rd +++ b/man/paste_tbl_grp.Rd @@ -19,7 +19,7 @@ paste_tbl_grp( ) } \arguments{ -\item{data}{input dataset. User must use consistent naming throughout, +\item{data}{input dataset (wide). User must use consistent naming throughout, \strong{with an underscore} to separate the group names from the measures (i.e. \code{Group1_mean} and \code{Group2_mean}). There also must be two columns with column names that exactly match the input for \code{first_name} @@ -56,10 +56,10 @@ determine the character to be pasted between the group names \item{verbose}{a logical variable indicating if warnings and messages should be displayed. Default FALSE.} } \value{ -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, ...) +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, ...) } \description{ -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. } diff --git a/man/pretty_pvalues.Rd b/man/pretty_pvalues.Rd index 8d1c5ad..a883a35 100644 --- a/man/pretty_pvalues.Rd +++ b/man/pretty_pvalues.Rd @@ -46,7 +46,7 @@ with trailing zeros to the defined number of digits (i.e. 0.100 instead of 0.1 i (for Word document output), or "no_markup"} } \value{ -Vector of transformed p-values for table output +Character vector of transformed p-values for table output } \description{ pretty_pvalues() takes a vector of p-values, rounds them to a specified diff --git a/man/round_away_0.Rd b/man/round_away_0.Rd index df58519..3ec1511 100644 --- a/man/round_away_0.Rd +++ b/man/round_away_0.Rd @@ -17,7 +17,7 @@ round_away_0(x, digits = 0, trailing_zeros = FALSE) if \code{trailing_zeros = TRUE} returns a character vector of rounded values with trailing zeros, otherwise returns a numeric vector of rounded values. } \description{ -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 \code{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. } \details{ \code{round_away_0} is not designed for use at precision levels <= 1e-15 diff --git a/man/shorten_git_hash.Rd b/man/shorten_git_hash.Rd index fe223ff..6bd1912 100644 --- a/man/shorten_git_hash.Rd +++ b/man/shorten_git_hash.Rd @@ -13,7 +13,7 @@ shorten_git_hash(x) String containing \code{@} followed by short git hash } \description{ -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. } diff --git a/man/stat_paste.Rd b/man/stat_paste.Rd index 1ebaa47..02a9712 100644 --- a/man/stat_paste.Rd +++ b/man/stat_paste.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/pretty_output_functions.R \name{stat_paste} \alias{stat_paste} -\title{Rounds and combines up to three numbers into table friendly presentation} +\title{Rounds and combines up to three numbers into table-friendly presentation} \usage{ stat_paste( stat1, @@ -17,27 +17,27 @@ stat_paste( ) } \arguments{ -\item{stat1}{first statistic to be pasted.} +\item{stat1}{first statistic to be pasted (e.g., mean)} -\item{stat2}{second statistic to be pasted (optional).} +\item{stat2}{optional second statistic to be pasted (e.g., sd/se, p-value, CI lower bound, minimum)} -\item{stat3}{third statistic to be pasted (optional).} +\item{stat3}{optional third statistic to be pasted (e.g., CI upper bound, maximum, nth percentile).} \item{digits}{positive integer of length 1 between 0 (default) and 14, -giving the amount of digits to round to.} +giving the amount of digits to round stat1, stat2, and stat3 to.} -\item{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} +\item{trailing_zeros}{logical indicating if trailing zeros should be included +(i.e. 0.100 instead of 0.1); default is TRUE} \item{bound_char}{the character to be used between stat1 and stat2/stat3. Available options are '(' (default), '[', '\{', and '|'.} \item{sep}{the string to be used between stat2 and stat3. The default is ', '.} -\item{na_str_out}{the character to replace missing values with.} +\item{na_str_out}{the character to replace missing values with (default is '---')} -\item{suffix}{a character string to add at the end of each stat -(i.e. \verb{\%} if doing response rates)} +\item{suffix}{an optional character string to add at the end of each stat +(e.g. \verb{\%} if doing response rates); default is NULL} } \value{ string of combined values diff --git a/man/trapz_sorted.Rd b/man/trapz_sorted.Rd index 5d599c7..f5981ab 100644 --- a/man/trapz_sorted.Rd +++ b/man/trapz_sorted.Rd @@ -14,11 +14,11 @@ trapz_sorted(x, y, na.rm = TRUE) \item{na.rm}{A logical indicating whether to remove NA values from both x and y values.} } \value{ -Approximated integral of the function, discretized through the points +Numeric value of approximated integral of the function, discretized through the points x, y, from \code{min(x)} to \code{max(x)}. } \description{ -This function is a wrapper for the \code{trapz} function. It sorts the x and y values +This function is a wrapper for the \code{pracma::trapz} function. It sorts the x and y values so that it is monotonically increasing along the x values. Then computes the area of a function with values \code{y} and points \code{x}. There is an optional parameter to remove any NA values so that integration can proceed by diff --git a/man/two_samp_bin_test.Rd b/man/two_samp_bin_test.Rd index a254047..b3c424f 100644 --- a/man/two_samp_bin_test.Rd +++ b/man/two_samp_bin_test.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/statistical_tests_and_estimates.R \name{two_samp_bin_test} \alias{two_samp_bin_test} -\title{Binary (Response) Variable Compared to Binary (Group) Variable Test (VISC)} +\title{Binary (Response) Variable Compared across Binary (Group) Variable} \usage{ two_samp_bin_test( x, diff --git a/man/two_samp_cont_test.Rd b/man/two_samp_cont_test.Rd index 2f58915..eb156f4 100644 --- a/man/two_samp_cont_test.Rd +++ b/man/two_samp_cont_test.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/statistical_tests_and_estimates.R \name{two_samp_cont_test} \alias{two_samp_cont_test} -\title{Continuous Variable Compared to Binary Variable Test (VISC)} +\title{Continuous (Response) Variable Compared across Binary (Group) Variable} \usage{ two_samp_cont_test( x,