diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..24f5565 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,18 @@ + + +## Description + +Describe your changes in detail. + +Give a short background, and outline important questions or details for the reviewer. + +## Related Issues + +Provide links to any related GitHub issues. + +## Checklist + +- [ ] This PR includes unit tests +- [ ] This PR establishes a new function or updates parameters in an existing function + - [ ] The roxygen skeleton for this function has been updated using `devtools::document` +- [ ] I have updated NEWS.md to describe the proposed changes diff --git a/README.Rmd b/README.Rmd index 026058f..c893acd 100644 --- a/README.Rmd +++ b/README.Rmd @@ -49,45 +49,90 @@ Below is an overview of the currently available functions in VISCfunctions. 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. +#### Functions Overview + +| Function | Description | Dependencies | VISC use-case | Key Inputs | Key Outputs | +|-------------------------|------------------|-----------------------------------------------|---------------|------------|-------------| +| `two_sample_bin_test()` | Comparisons of a grouping variable for unpaired data | Exact::exact.test, stats::fisher.test, stats::chisq.test, stats::mcnemar.test | Barnard, Fishers's Exact, Chi-square, or McNemar tests in PT reports | X: vector (2 levels), Y: vector (2 levels), Method: default Barnard | p-value for comparing x at the different levels of y | +| `two_sample_cont_test()` | continuous variable compared to binary variable | stats::t.test (paired or unpaired), coin::wilcoxsign_test | Used within pairwise_test_cont| X: Numeric vector, Y: vector (2 levels), type of test, paired, hypothesis | p-value for comparing x at the different levels of y | +| `cor_test()` | a wrapper for stats::cor.test, function, 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. | stats::cor.test, coin::spearman_test | Perform a test to determine if the value of the association between two samples equals zero | Two numeric vectors (can include NA values) amongst which correlation test needs to be computed. | P-value from 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. +| Function | Description | Dependencies | VISC use-case | Key Inputs | Key Outputs | +|-------------------------|------------------|-----------------------------------------------|---------------|------------|-------------| +| `pairwise_test_bin()` | Make pairwise comparisons of a binary variable | Wilson_ci | Barnard, Fishers's Exact, Chi-square, or McNemar tests in PT reports | X: numeric or logical vector, Group: grouping variable, Method: default Barnard, num_needed_for_test: required sample size per group to perform test, conf_level: confidence interval | Dataframe with columns: Comparison, ResponseStats, ResponseTest, PerfectSeperation | +| `pairwise_test_cont()` | Takes a continuous variable and performs pairwise testing (t-test or wilcox test) | stats::na.omit, stats::median,
stats::sd, two_samp_
cont_test | Group-wise statistical testing on magnitudes, for a t.test (paired or unpaired), Wilcox Rank-Sum, or Wilcox Signed-Rank test in PT reports | X: Numeric vector, Group, type of test, paired, hypothesis, sample size | Returns a data frame with all possible pairwise comparisons | +| `cor_test_pairs()` | calculates correlation estimate (Spearman, Pearson, or Kendall) and p-value between categorical variable levels (in a pairwise manner) | cor_test() | calculate the Spearman, Pearson, or Kendall correlation estimate and p-value between the different levels of a categorical variable | A vector of numeric values (can include NA values), A categorical vector which contains the levels to compare (default Pearson), A vector which contains the id information | data.frame of summary statistics | + Estimate binomial confidence intervals for a binary vector: -* `binom_ci()` + +| Function | Description | Dependencies | VISC use-case | Key Inputs | Key Outputs | +|-------------------------|------------------|-----------------------------------------------|---------------|------------|-------------| +| `binom_ci()` | Estimate binomial confidence intervals for a binary vector |binom::binom.confint | Calculate response rate 95% CI (replaces wilson_ci)| Vector of ones and zeros (or T/F) and method (default Wilson)| dataframe of summary statistics | + +Note that `wilson_ci()` has been superseded by the use of `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 +| Function | Description | Dependencies | VISC use-case | Key Inputs | Key Outputs | +|-------------------------|------------------|-----------------------------------------------|---------------|------------|-------------| +| `paste_tbl_grp()` | Paste together information (statistical summaries) from two groups |round_away_0, stat_paste | Output tables with group comparison summaries| (group) Wide formatted dataframe | Long dataframe based on combining summaries for two groups | +| `pretty_pvalues()` | Takes a vector of p-values, rounds them to a specified digit amount, allows options for emphasizing p-values < the defined significance level, and returns a character for missing |round_away_0, kableExtra::
cell_spec() | Presenting p values in table outputs, with highlights for significant values | Numeric vector | Character vector of pretty p values | +| `stat_paste()` | Takes in values and outputs single, double, or triple statistical summaries | round_away_0 |mean, mean (sd), median [25th, 75th], median (min, max)| 1, 2, or 3 vectors of numbers or characters | k text outputs, where k = length of the largest input vector | +| `escape()` | Prohibits LaTeX escape characters, when you need to include them in output | NA |any output that has a special text character | Character vector | Same character vector, with ‘\\’ pasted before escape chars (each vector element) | +| `collapse_group_row()` | replacing repeated rows in a data.frame into NA for nice printing | NA |Remove repeats by group / visit in a table dataset before output | Dataframe | Same dataframe, with repeated values set to NA | +| `round_away_0 ` | Unlike R round (which rounds towards an even number), this function rounds away from zero and allows retention of trailing zeros | NA |Generally any time we need to round, additionally when we need to retain significant digits | Numeric vector | Numeric or character vector (if trailing_zeros=TRUE) | + + + + + + + + + + + ## 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 +| Function | Description | Dependencies | VISC use-case | Key Inputs | Key Outputs | +|-------------------------|------------------|-----------------------------------------------|---------------|------------|-------------| +| `create_step_curve()` | Creates data.frame of survival probabilities and "number at risk". Can use to plot step lines (KM or MB curves) | survival::Surv,
survival::survfit | Used in mb_results() | x: time values to create x-axis in step curves. For MB "time values" are net-MFI event: event status 0 = censor or 1=event, flip_surv: reverse survival estimates calculated (Default = FALSE). flip_top_x: value to set x for top point for plotting. Only used if flip_surv = TRUE. Default is Inf.| Creates intermediary df (cols: time, surv, n.risk, n.event, n.censor) | +| `mb_results()` | Creates a data.frame to plot MB curves and AUC | create_step_curve, utils::head | Creates input to create magnitude-breadth (MB) curves | magnitude: values for step curve/AUC response: binary (0/1 or TRUE/FALSE), lower_trunc: lower truncation value (ex: 100), upper_trunc: the upper truncation value (ex: 22,000), x_transform: "log10" (default) or "raw" | Creates df for creation of AUC-MB curves (cols: id, magnitude, breadth, n_remaining, n_here, aucMB). Can be individual or combined for grouped input. | +| `trapz_sorted()` | A wrapper for trapz monotonically sorting values and computing area | pracma::trapz | |x: x-coordinates of points on x-axis, y: y-coordinates of function values, na.rm: boolean for remove NA from x & y or not. | integral of function with discrete points (single numeric value) | -## 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. +## Utility functions +| Function | Description | Dependencies | VISC use-case | Key Inputs | Key Outputs | +|-------------------------|------------------|-----------------------------------------------|---------------|------------|-------------| +| `get_full_name()` | looks up a username from Fred Hutch ID | | | ID to look full name up. If null (default) looks up ID of current user | character vector | +| `get_session_info()` | creates a a data frame with session information | my_session_info | Creating tables used at the end of reports, for reproducibility. Most of the information is based off of sessioninfo::session_info() | | dataframe | +| `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. | | used within `get_session_info()` | String containing @ followed by long git hash | String containing @ followed by short git hash | + + + + + + +## Example Datasets + +| Assay | Dataset |Description | +|-------------------------|------------------|---------------------| +| ICS | `exampleData_ICS`|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. | +| BAMA | `exampleData_BAMA`|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. | +| NAb | `exampleData_NAb`|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. | +| mAB | `CAVD812_mAB`|A subset dataset from the Farzan CAVD 812 Study, looking at eCD4 neutralization. | # Vignette diff --git a/README.md b/README.md index e04150a..f5624fe 100644 --- a/README.md +++ b/README.md @@ -42,57 +42,85 @@ VISCfunctions. 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. +#### Functions Overview + +| Function | Description | Dependencies | VISC use-case | Key Inputs | Key Outputs | +|----|----|----|----|----|----| +| `two_sample_bin_test()` | Comparisons of a grouping variable for unpaired data | Exact::exact.test, stats::fisher.test, stats::chisq.test, stats::mcnemar.test | Barnard, Fishers’s Exact, Chi-square, or McNemar tests in PT reports | X: vector (2 levels), Y: vector (2 levels), Method: default Barnard | p-value for comparing x at the different levels of y | +| `two_sample_cont_test()` | continuous variable compared to binary variable | stats::t.test (paired or unpaired), coin::wilcoxsign_test | Used within pairwise_test_cont | X: Numeric vector, Y: vector (2 levels), type of test, paired, hypothesis | p-value for comparing x at the different levels of y | +| `cor_test()` | a wrapper for stats::cor.test, function, 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. | stats::cor.test, coin::spearman_test | Perform a test to determine if the value of the association between two samples equals zero | Two numeric vectors (can include NA values) amongst which correlation test needs to be computed. | P-value from 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. +| Function | Description | Dependencies | VISC use-case | Key Inputs | Key Outputs | +|----|----|----|----|----|----| +| `pairwise_test_bin()` | Make pairwise comparisons of a binary variable | Wilson_ci | Barnard, Fishers’s Exact, Chi-square, or McNemar tests in PT reports | X: numeric or logical vector, Group: grouping variable, Method: default Barnard, num_needed_for_test: required sample size per group to perform test, conf_level: confidence interval | Dataframe with columns: Comparison, ResponseStats, ResponseTest, PerfectSeperation | +| `pairwise_test_cont()` | Takes a continuous variable and performs pairwise testing (t-test or wilcox test) | stats::na.omit, stats::median,
stats::sd, two_samp\_
cont_test | Group-wise statistical testing on magnitudes, for a t.test (paired or unpaired), Wilcox Rank-Sum, or Wilcox Signed-Rank test in PT reports | X: Numeric vector, Group, type of test, paired, hypothesis, sample size | Returns a data frame with all possible pairwise comparisons | +| `cor_test_pairs()` | calculates correlation estimate (Spearman, Pearson, or Kendall) and p-value between categorical variable levels (in a pairwise manner) | cor_test() | calculate the Spearman, Pearson, or Kendall correlation estimate and p-value between the different levels of a categorical variable | A vector of numeric values (can include NA values), A categorical vector which contains the levels to compare (default Pearson), A vector which contains the id information | data.frame of summary statistics | Estimate binomial confidence intervals for a binary vector: -- `binom_ci()` +| Function | Description | Dependencies | VISC use-case | Key Inputs | Key Outputs | +|----|----|----|----|----|----| +| `binom_ci()` | Estimate binomial confidence intervals for a binary vector | binom::binom.confint | Calculate response rate 95% CI (replaces wilson_ci) | Vector of ones and zeros (or T/F) and method (default Wilson) | dataframe of summary statistics | + +Note that `wilson_ci()` has been superseded by the use of `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 +| Function | Description | Dependencies | VISC use-case | Key Inputs | Key Outputs | +|----|----|----|----|----|----| +| `paste_tbl_grp()` | Paste together information (statistical summaries) from two groups | round_away_0, stat_paste | Output tables with group comparison summaries | (group) Wide formatted dataframe | Long dataframe based on combining summaries for two groups | +| `pretty_pvalues()` | Takes a vector of p-values, rounds them to a specified digit amount, allows options for emphasizing p-values \< the defined significance level, and returns a character for missing | round_away_0, kableExtra::
cell_spec() | Presenting p values in table outputs, with highlights for significant values | Numeric vector | Character vector of pretty p values | +| `stat_paste()` | Takes in values and outputs single, double, or triple statistical summaries | round_away_0 | mean, mean (sd), median \[25th, 75th\], median (min, max) | 1, 2, or 3 vectors of numbers or characters | k text outputs, where k = length of the largest input vector | +| `escape()` | Prohibits LaTeX escape characters, when you need to include them in output | NA | any output that has a special text character | Character vector | Same character vector, with ‘\\’ pasted before escape chars (each vector element) | +| `collapse_group_row()` | replacing repeated rows in a data.frame into NA for nice printing | NA | Remove repeats by group / visit in a table dataset before output | Dataframe | Same dataframe, with repeated values set to NA | +| `round_away_0` | Unlike R round (which rounds towards an even number), this function rounds away from zero and allows retention of trailing zeros | NA | Generally any time we need to round, additionally when we need to retain significant digits | Numeric vector | Numeric or character vector (if trailing_zeros=TRUE) | + + + + + + + + + + + ## 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 +| Function | Description | Dependencies | VISC use-case | Key Inputs | Key Outputs | +|----|----|----|----|----|----| +| `create_step_curve()` | Creates data.frame of survival probabilities and “number at risk”. Can use to plot step lines (KM or MB curves) | survival::Surv,
survival::survfit | Used in mb_results() | x: time values to create x-axis in step curves. For MB “time values” are net-MFI event: event status 0 = censor or 1=event, flip_surv: reverse survival estimates calculated (Default = FALSE). flip_top_x: value to set x for top point for plotting. Only used if flip_surv = TRUE. Default is Inf. | Creates intermediary df (cols: time, surv, n.risk, n.event, n.censor) | +| `mb_results()` | Creates a data.frame to plot MB curves and AUC | create_step_curve, utils::head | Creates input to create magnitude-breadth (MB) curves | magnitude: values for step curve/AUC response: binary (0/1 or TRUE/FALSE), lower_trunc: lower truncation value (ex: 100), upper_trunc: the upper truncation value (ex: 22,000), x_transform: “log10” (default) or “raw” | Creates df for creation of AUC-MB curves (cols: id, magnitude, breadth, n_remaining, n_here, aucMB). Can be individual or combined for grouped input. | +| `trapz_sorted()` | A wrapper for trapz monotonically sorting values and computing area | pracma::trapz | | x: x-coordinates of points on x-axis, y: y-coordinates of function values, na.rm: boolean for remove NA from x & y or not. | integral of function with discrete points (single numeric value) | + + + ## 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. +| Function | Description | Dependencies | VISC use-case | Key Inputs | Key Outputs | +|----|----|----|----|----|----| +| `get_full_name()` | looks up a username from Fred Hutch ID | | | ID to look full name up. If null (default) looks up ID of current user | character vector | +| `get_session_info()` | creates a a data frame with session information | my_session_info | Creating tables used at the end of reports, for reproducibility. Most of the information is based off of sessioninfo::session_info() | | dataframe | +| `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. | | used within `get_session_info()` | String containing @ followed by long git hash | String containing @ followed by short git hash | + + + + + + +## Example Datasets + +| Assay | Dataset | Description | +|----|----|----| +| ICS | `exampleData_ICS` | 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. | +| BAMA | `exampleData_BAMA` | 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. | +| NAb | `exampleData_NAb` | 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. | +| mAB | `CAVD812_mAB` | A subset dataset from the Farzan CAVD 812 Study, looking at eCD4 neutralization. | # Vignette diff --git a/vignettes/Overview.Rmd b/vignettes/Overview.Rmd index 4e53cbb..f40d6b3 100644 --- a/vignettes/Overview.Rmd +++ b/vignettes/Overview.Rmd @@ -86,6 +86,7 @@ can be broken down to the following sections: - round_away_0 - get_session_info - get_full_name + - shorten_git_hash - Example Datasets - exampleData_BAMA - exampleData_NAb @@ -167,7 +168,7 @@ There are currently three testing functions performing the appropriate statistical tests, depending on the data and options, returning a p value. There is also an estimate function for getting binary confidence intervals -(`binom_ci()`). +(`binom_ci()`). Note that `wilson_ci()` has been superseded by the use of `binom_ci()`. `trapz_sorted()` is used to create an estimate for the area under a curve while making sure the x-axis is sorted so that both the x-axis and the area are @@ -848,6 +849,9 @@ round_away_0(vals_to_round, digits = 2, trailing_zeros = TRUE) end of reports. The first table gives software session information and the second table gives software package version information. `get_full_name()` is a function used by `get_session_info()` to get the user's name, based on user's ID. +`shorten_git_hash()` is an internal function for the reproducibility table and used within `get_session_info()`. +It shortens the string to 7 digits. + ```{r} my_session_info <- get_session_info()