Merge pull request #152 from sunroofgod/dev

Update favicon and dev documentation

Author: sunroofgod

R/002_df_for_plots.R

@@ -80,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,
@@ -326,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()
@@ -359,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,
@@ -401,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

R/002_plot_components.R

@@ -2,7 +2,19 @@
 #
 # Contains functions `create_rawplot_components`, `create_deltaplot_components` and `create_violinplot_components`.
 
-# Function for creation of list of TRUE/FALSE for raw plot components that will be built
+#' Generates list of TRUE/FALSE for raw plot components that will be built
+#'
+#' This function generates a list of booleans determining whether certain 
+#' plot components will be constructed for the rawplot.
+#'
+#' @param proportional Boolean value as initially passed to [load()].
+#' @param is_paired Boolean value determining if it is a paired plot.
+#' @param float_contrast Boolean value determining which plot will be produced. If TRUE, a 
+#' Gardner-Altman plot will be produced.If FALSE, a Cumming estimation plot will be produced.
+#'
+#' @return List of booleans for raw plot components
+#'
+#' @noRd
 create_rawplot_components <- function(proportional,
                                       is_paired,
                                       float_contrast) {
@@ -49,7 +61,25 @@ create_rawplot_components <- function(proportional,
   return(plot_component)
 }
 
-# Function for creation of list of TRUE/FALSE for delta plot components that will be built
+#' Generates list of TRUE/FALSE for delta plot components that will be built
+#'
+#' This function generates a list of booleans determining whether certain 
+#' plot components will be constructed for the deltaplot.
+#' 
+#' @param proportional Boolean value as initially passed to [load()].
+#' @param is_paired Boolean value determining if it is a paired plot.
+#' @param float_contrast Boolean value determining which plot will be produced. If TRUE, a 
+#' Gardner-Altman plot will be produced.If FALSE, a Cumming estimation plot will be produced.
+#' @param is_colour Boolean value determining if there is a colour column for the plot.
+#' @param delta2 Boolean value determining if delta-delta analysis for
+#' 2 by 2 experimental designs is conducted.
+#' @param show_zero_dot Boolean value determining if there is a dot on
+#' the zero line of the effect size for the control-control group.
+#' @param flow Boolean value determining whether the bars will be plotted in pairs.
+#' @param show_baseline_ec Boolean value determining whether the baseline curve is shown.
+#'
+#' @return List of booleans for delta plot components 
+#' @noRd
 create_deltaplot_components <- function(proportional,
                                         is_paired,
                                         float_contrast,
@@ -92,7 +122,23 @@ create_deltaplot_components <- function(proportional,
   return(plot_component)
 }
 
-# Function for creation of list of values of the violin plot components that will be built
+#' Generates list of values for the violin plot components that will be built
+#'
+#' This function generates the data and metadata necessary to create a 
+#' violin plot with specific characteristics
+#'
+#' @param boots Boot result obtained from boot.ci
+#' @param idx List of vectors of control-test groupings that determines the arrangement
+#' of the final dataframe output.
+#' @param float_contrast Boolean value determining if a Gardner-Altman plot or 
+#' Cumming estimation plot will be produced.
+#' @param delta_y_max Max y limits for the delta-delta plot
+#' @param delta_y_min Min y limits for the delta-delta plot
+#' @param flow Boolean value determining whether the bars will be plotted in pairs.
+#' @param zero_dot Boolean value determining if the zero dot will be constructed.
+#'
+#' @return List of components essential for the violinplot.
+#' @noRd
 create_violinplot_components <- function(boots,
                                          idx,
                                          float_contrast,