Cyurdado update readme

.github/pull_request_template.md

@@ -0,0 +1,18 @@
+<!-- Provide a general summary of your changes in the Title above. -->
+
+## 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

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, <br>stats::sd, two_samp_<br>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::<br>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) |
+
+<!-- * `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
+| 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, <br>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
+<!-- * `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 -->
 
-* `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 |
+
+<!-- * `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. -->
+
+## 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