Merge pull request #153 from ACCLAB/dev

v2023.9.12 along with favicon updates

Author: maiyishan

.Rbuildignore

@@ -12,3 +12,4 @@
 ^dabestr.Rmd$
 ^cran-comments\.md$
 ^revdep$
+^CRAN-SUBMISSION$

.github/workflows/R-CMD-check.yaml

@@ -2,7 +2,7 @@
 # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
 on:
   push:
-    branches: [dev, master]
+    branches: [master]
   pull_request:
     branches: [dev, master]
 

.gitignore

@@ -14,4 +14,5 @@ dabestr.Rmd
 .RProfile
 docs
 inst/doc
-figures
+/figures
+CRAN-SUBMISSION

CODE_OF_CONDUCT.md

@@ -55,7 +55,7 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at joseshowh@gmail.com. All
+reported by contacting the project team at maiyishan@u.duke.nus.edu. All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
 obligated to maintain confidentiality with regard to the reporter of an incident.

CONTRIBUTING.md

@@ -1,18 +1,53 @@
 # Contributing to dabestr
 
-## Did you find a bug?
-- Ensure the bug was not already reported by searching in [Issues](https://github.com/ACCLAB/dabestr/issues). Check that the bug hasn't been addressed in a closed issue.
+The guide is divided into three main pieces:
 
-- If the bug isn't being addressed, open a new one. Be sure to include a title and clear description, and a [minimally reproducible code sample](http://adv-r.had.co.nz/Reproducibility.html) demonstrating the expected behavior that is not occurring. 
+1. Filing a bug in an issue.
+1. Filing a feature request in an issue.
+1. Suggesting a change via a pull request.
 
-## Did you write a patch that fixes a bug?
-- Open a new GitHub pull request with the patch.
+Please note that dabestr is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms.
 
-- Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
+## Issues
 
-## Do you intend to add a new feature or change an existing one?
-- Suggest your change by opening an issue, and adding an Enhancement tag. 
-- If the maintainers and the community are in favour, create a fork and start writing code.
+Ensure the bug was not already reported by searching in [Issues](https://github.com/ACCLAB/dabestr/issues). Be sure to also check that the bug hasn't been addressed in a closed issue.
 
+If the bug isn't being addressed, open a new one. 
+
+Be sure to include a title and clear description, and a [minimally reproducible code sample](http://adv-r.had.co.nz/Reproducibility.html) demonstrating the expected behavior that is not occurring. 
+
+## Feature Requests
+
+You may suggest by opening an issue and adding an Enhancement tag.
+
+## Pull requests
+
+To contribute a change to dabestr, you follow these steps:
+
+1. Create a fork and make your changes.
+1. Issue a PR to the dev branch of dabestr.
+1. Discuss the PR.
+1. Iterate until either we accept the PR or decide it's not a good fit for dabestr.
+
+Each of these steps are described in more detail below.
+
+If you're not familiar with git or github, please start by reading http://r-pkgs.had.co.nz/git.html
+
+### Guidelines
+1. **Clarity**. Ensure PR description clearly describes the problem and the solution. Include the relevant issue number if applicable.
+1. **Use dabestr coding style**. dabestr is currently following the [official tidyverse style](http://style.tidyverse.org/). You may choose to do so using the `styler` package by running the following on the code before submitting:
+
+```r
+# install.packages("styler")
+styler::style_pkg()
+```
+3. If you're adding new parameters or a new function, you'll also need to document them with [roxygen](https://github.com/klutometis/roxygen). Make sure to re-run `devtools::document()` on the code before submitting.
+3. If fixing a bug or adding a new feature, please add a [testthat](https://github.com/r-lib/testthat) unit test.
+
+All PRs require review and approval from at least one member of the dabestr development team before merge. 
+
+Lastly, dabestr is a **community** tool for estimation statistics and analysis. We look forward to more robust and more elegant data visualizations from you all!
+
+## Attribution
+This Contributing guide is adapted from [ggplot2](https://ggplot2.tidyverse.org)'s [CONTRIBUTING.md](https://github.com/tidyverse/ggplot2/blob/main/CONTRIBUTING.md?plain=1).
 
-dabestr is a community tool for estimation statistics and analysis. We look forward to more robust and more elegant data visualizations from you all!

DESCRIPTION

@@ -3,14 +3,14 @@ Type: Package
 Title: Data Analysis using Bootstrap-Coupled Estimation
 Version: 2023.9.12
 Authors@R: c(
+  person("Joses W.", "Ho", email = "joseshowh@gmail.com", role = "aut",
+         comment = c(ORCID = "0000-0002-9186-6322")),
   person("Kah Seng", "Lian", email = "kahseng@u.nus.edu", role = c("aut")),
   person("Zhuoyu", "Wang", email = "wzhuoyu21@u.nus,edu", role = "aut"),
   person("Jun Yang", "Liao", email = "name@example.com", role = "aut"),
-  person("Joses W.", "Ho", email = "joseshowh@gmail.com", role = "aut",
-         comment = c(ORCID = "0000-0002-9186-6322")),
+  person("Felicia", "Low", role = "aut", email = "lowminhuifelicia@gmail.com"),
   person("Tayfun", "Tumkaya", role = "aut",
          comment = c(ORCID = "0000-0001-8425-3360")),
-  person("Felicia", "Low", role = "aut", email = "lowminhuifelicia@gmail.com"),
   person("Yishan", "Mai", email = "maiyishan@u.duke.nus.edu", role = c("cre", "ctb"),
          comment = c(ORCID = "0000-0002-7199-380X")),
   person("Sangyu", "Xu", role = "ctb",

LICENSE.md

@@ -179,7 +179,7 @@ recommend that a file or class name and description of purpose be included on
 the same “printed page” as the copyright notice for easier identification within
 third-party archives.
 
-    Copyright [yyyy] [name of copyright owner]
+    Copyright 2023 dabestr authors
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.

R/002_df_for_plots.R

@@ -1,32 +1,17 @@
-#' Helper functions that generate dfs for tuftelines plot
-#'
-#' @noRd
-#'
+#' Generates the dataframe requires for the tufte lines plot component in raw plots. 
+#' 
+#' This function returns a dataframe with summary statistics, such as mean, standard
+#' deviation and quantiles (depending on the effect size) based on the input dataset. 
+#' 
 #' @param raw_data The tidy dataset passed to [load()] that was cleaned and altered for plotting.
 #' @param enquo_x Quosure of x as initially passed to [load()].
 #' @param enquo_y Quosure of y as initially passed to [load()].
 #' @param proportional Boolean value as initially passed to [load()].
-#' @param float_contrast Default TRUE. If TRUE, a Gardner-Altman plot will be produced.
-#' If FALSE, a Cumming estimation plot will be produced.
-#' @param enquo_id_col Quosure of id_col as initially passed to [load()].
-#' @param idx The list of control-test groupings as initially passed to [load()].
-#' @param tufte_lines_df Dataset for the creation of tufte lines.
-#' @param proportional_data List of calculations related to the plotting of proportion plots.
-#' @param scale_factor_sig Decimal value ranging from 0 to 1 which determines the significance of the scale factor.
-#' @param bar_width Numeric value determining the width of the bar in the sankey diagram or proportion plots.
-#' @param gap Numeric value determining the space between the bars in the sankey diagram or proportion plots.
-#' @param sankey Boolean value determining if the flows between the bar charts will be plotted.
-#' @param flow Boolean value determining whether the bars will be plotted in pairs.
-#' @param N The number of rows in the proportional dataset.
-#' @param proportion_success The proportion or ratio of values that are 1.
-#' @param boots Boot result obtained from boot.ci
-#' @param x_idx_position Numeric value determining the position of the plots on the x-axis.
+#' @param gap Integer value specifying the amount of gap for each tufte line.
+#' @param effsize_type String value specifying type of effect size.
 #'
-#' @details
-#' Contains functions `df_for_tufte`, `create_dfs_for_sankey`, `create_dfs_for_xaxis_redraw`, `create_dfs_for_proportion_bar` for generation of dfs.
-#'
-#' @return
-#' Various dfs which is required for the plotting functions to obtain a complete dabest plot.
+#' @returns a dataframe for plotting of the tufte lines plot component.
+#' @noRd
 create_df_for_tufte <- function(raw_data, enquo_x, enquo_y, proportional, gap, effsize_type) {
   tufte_lines_df <- raw_data %>%
     dplyr::group_by(!!enquo_x) %>%
@@ -67,8 +52,19 @@ create_df_for_tufte <- function(raw_data, enquo_x, enquo_y, proportional, gap, e
 
   return(tufte_lines_df)
 }
-
-# Function for creation of df for flow = FALSE plot
+#' Generates df for tufte lines plot component for raw plot WITH flow = FALSE.
+#' 
+#' This function rearranges and duplicates rows in a given dataframe (containing
+#' summary statistics) in the order of the unlisted given list of vectors.   
+#'
+#' @param idx List of vectors of control-test groupings that determines the arrangement
+#' of the final dataframe output.
+#' @param tufte_lines_df dataframe for plotting of the tufte lines plot component as 
+#' generated by [create_df_for_tufte()].
+#' @param enquo_x Quosure of x as initially passed to [load()].
+#' 
+#' @returns dataframe
+#' @noRd
 create_dfs_for_nonflow_tufte_lines <- function(idx,
                                                tufte_lines_df,
                                                enquo_x) {
@@ -84,7 +80,29 @@ create_dfs_for_nonflow_tufte_lines <- function(idx,
   return(new_tufte_lines_df)
 }
 
-# Function for creation of df for sankey plot
+#' Generates df for sankey plot component for raw plot WITH flow = TRUE
+#' 
+#' This function generates data frames necessary for generating 
+#' sankey diagrams for visualizing flows and proportions of categorical data. 
+#' 
+#' 
+#' @param float_contrast Boolean value determining if a Gardner-Altman plot or Cumming estimation plot will be produced.
+#' @param raw_data The tidy dataset passed to [load()] that was cleaned and altered for plotting.
+#' @param proportional_data List of calculations related to the plotting of proportion plots.
+#' @param enquo_x Quosure of x as initially passed to [load()].
+#' @param enquo_y Quosure of y as initially passed to [load()].
+#' @param enquo_id_col Quosure of id_col as initially passed to [load()].
+#' @param idx List of vectors of control-test groupings that determines the arrangement
+#' of the final dataframe output.
+#' @param scale_factor_sig Numeric value determining the significance of the scale factor. 
+#' @param bar_width Numeric value determining the width of the bar in the sankey diagram.
+#' @param gap Integer value specifying the amount of gap for each tufte line.
+#' @param sankey Boolean value determining if the flows between the bar charts will be plotted.
+#' @param flow Boolean value determining whether the bars will be plotted in pairs.
+#' @param N Total number of observations or data points in the dataset.
+#'
+#' @returns dataframe
+#' @noRd
 create_dfs_for_sankey <- function(
     float_contrast = FALSE,
     raw_data,
@@ -330,7 +348,17 @@ create_dfs_for_sankey <- function(
   return(dfs_for_sankeys)
 }
 
-# Function for creation of df for xaxis redraw for float_contrast FALSE plot
+#' Generates df for xaxis redraw for float_contrast = FALSE plot
+#' 
+#' This function generates data frames that 
+#' define the positions of lines and ticks on an x-axis for when float_contrast = FALSE
+#' to produce a Cumming estimation plot.
+#' 
+#' @param idx List of vectors of control-test groupings that determines the arrangement
+#' of the final dataframe output.
+#'
+#' @returns dataframe
+#' @noRd
 create_dfs_for_xaxis_redraw <- function(idx) {
   x_axis_pointer <- 0
   xaxis_line_x_vector <- c()
@@ -363,6 +391,16 @@ create_dfs_for_xaxis_redraw <- function(idx) {
   return(dfs_for_xaxis_redraw)
 }
 
+#' Generates df for proportion bar component 
+#' 
+#' This function generates data frames to 
+#' represent bars with proportional data in a graphical display.
+#' 
+#' @param bar_width Numeric value determining the width of the bar in the sankey diagram.
+#' @param gap Integer value specifying the amount of gap for each tufte line.
+#'
+#' @returns dataframe
+#' @noRd
 create_dfs_for_proportion_bar <- function(proportion_success, bar_width = 0.3, gap = 0) {
   df_for_proportion_bar <- data.frame(
     x_failure = NA,
@@ -405,6 +443,18 @@ create_dfs_for_proportion_bar <- function(proportion_success, bar_width = 0.3, g
   return(df_for_proportion_bar)
 }
 
+#' Generates df for baseline violin plot WITH flow = TRUE
+#'
+#' This function generates data frames to represent 
+#' data points for plotting violin plots
+#'
+#' @param boots Boot result obtained from boot.ci
+#' @param x_idx_position Numeric value determining the position of the plots on the x-axis.
+#' @param float_contrast Boolean value determining if a Gardner-Altman plot or Cumming estimation plot will be produced.
+#' @param flow Boolean value determining whether the bars will be plotted in pairs.
+#'
+#' @return dataframe
+#' @noRd
 create_dfs_for_baseline_ec_violin <- function(boots, x_idx_position, float_contrast, flow = TRUE) {
   df_for_violin <- data.frame(
     x = NA,

R/002_plot_api.R

@@ -1,29 +1,19 @@
-#' Functions responsible for generation of raw_plot and delta_plot.
+#' Generates a ggplot object containing plot components for the rawplot component 
+#' of an estimation plot.
 #'
-#' @noRd
+#' This function takes in a dabest_effectsize_obj object and applies the [create_rawplot_components()]
+#' function on the object. Plot components for the rawplot are then produced and returned in the
+#' form of a ggplot object.
 #'
 #' @param dabest_effectsize_obj A dabest_effectsize_obj created by loading in a
 #' dabest_obj along with other specified parameters with the [effect_size()] function.
-#' @param float_contrast Boolean value determining if a Gardner-Altman plot or Cumming estimation plot will be produced.
+#' @param float_contrast Boolean. If TRUE, a Gardner-Altman plot will be produced.
+#' If FALSE, a Cumming estimation plot will be produced.
 #' @param plot_kwargs Adjustment parameters to control and adjust the appearance of the plot.
 #' (list of all possible adjustment parameters can be found under [plot_kwargs])
 #'
-#' @details
-#' Contains main plotting functions `plot_raw` and `plot_delta` for plotting of the rawdata and effectsize parts.
-#'
-#' @examples
-#' # Loading of the dataset
-#' data(twogroup_data)
-#'
-#' # Preparing the data to be plotted
-#' dabest_obj <- load(non_proportional_data, x = Group, y = Measurement, idx = c("Control 1", "Test 1"))
-#' dabest_obj.mean_diff <- mean_diff(dabest_obj)
-#'
-#' # Plotting of dabest_obj.mean_diff (rawplot only)
-#' plot_raw(dabest_obj.mean_diff, TRUE)
-#'
-#' # Plotting of dabest_obj.mean_diff (deltaplot only)
-#' plot_delta(dabest_obj.mean_diff, True)
+#' @return ggplot object containing plot components for the rawplot.
+#' @noRd
 plot_raw <- function(dabest_effectsize_obj, float_contrast, plot_kwargs) {
   enquo_x <- dabest_effectsize_obj$enquo_x
   enquo_y <- dabest_effectsize_obj$enquo_y
@@ -421,8 +411,22 @@ plot_raw <- function(dabest_effectsize_obj, float_contrast, plot_kwargs) {
 
   return(raw_plot)
 }
-
-# Delta plot function
+#' Generates a ggplot object containing plot components for the deltaplot component
+#' of an estimation plot.
+#'
+#' This function takes in a dabest_effectsize_obj object and applies the [create_deltaplot_components()]
+#' function on the object. Plot components for the deltaplot are then produced and returned in the
+#' form of a ggplot object.
+#'
+#' @param dabest_effectsize_obj A dabest_effectsize_obj created by loading in a
+#' dabest_obj along with other specified parameters with the [effect_size()] function.
+#' @param float_contrast Boolean. If TRUE, a Gardner-Altman plot will be produced.
+#' If FALSE, a Cumming estimation plot will be produced.
+#' @param plot_kwargs Adjustment parameters to control and adjust the appearance of the plot.
+#' (list of all possible adjustment parameters can be found under [plot_kwargs])
+#'
+#' @return ggplot object containing plot components for the deltaplot.
+#' @noRd
 plot_delta <- function(dabest_effectsize_obj, float_contrast, plot_kwargs) {
   idx <- dabest_effectsize_obj$idx
   separated_idx <- idx