sbalci/ClinicoPathJamoviModule

---
name:  jjwithinstats
title: Box-Violin Plots to Compare Within Groups
menuGroup: JJStatsPlot
menuSubgroup: 'Categorical vs Continuous'
menuSubtitle: Repeated Continuous Measurements
version: '1.0.0'
jas: '1.2'



description:
    # main: |
    #     'Wrapper Function for ggstatsplot::ggwithinstats and
    #     ggstatsplot::grouped_ggwithinstats to generate Violin Plots.'
    R:
        dontrun: true
        usage: |
            # example will be added

options:
    - name: data
      type: Data
      description:
          R: >
            The data as a data frame.

    - name: dep1
      title: First Measurement
      type: Variable
      suggested: [ continuous ]
      permitted: [ numeric ]

    - name: dep2
      title: Second Measurement
      type: Variable
      suggested: [ continuous ]
      permitted: [ numeric ]

    - name: dep3
      title: Third Measurement (Optional)
      type: Variable
      suggested: [ continuous ]
      permitted: [ numeric ]

    - name: dep4
      title: Fourth Measurement (Optional)
      type: Variable
      suggested: [ continuous ]
      permitted: [ numeric ]

    - name: pointpath
      title: Show Point Path
      type: Bool
      default: false

    - name: centralitypath
      title: Centrality Path
      type: Bool
      default: false


    - name: centralityplotting
      title: Show Centrality
      type: Bool
      default: false

    - name: centralitytype
      title: 'Centrality Type'
      type: List
      options:
        - title: mean (parameteric)
          name: parameteric
        - title: median (nonparametric)
          name: nonparametric
        - title: robust (trimmed mean)
          name: robust
        - title: bayes (MAP estimator)
          name: bayes 
      default: parameteric


    - name: typestatistics
      title: 'Type of Statistic'
      type: List
      options:
        - title: Parametric
          name: parametric
        - title: Nonparametric
          name: nonparametric
        - title: Robust
          name: robust
        - title: Bayes
          name: bayes
      default: parametric

    - name: pairwisecomparisons
      title: Pairwise Comparisons
      type: Bool
      default: false

    - name: pairwisedisplay
      title: 'Pairwise Display'
      type: List
      options:
        - title: significant
          name: significant
        - title: non-significant
          name: non-significant
        - title: everything
          name: everything
      default: significant

    - name: padjustmethod
      title: 'Adjustment Method'
      type: List
      options:
        - title: holm
          name: holm
        - title: hochberg
          name: hochberg
        - title: hommel
          name: hommel
        - title: bonferroni
          name: bonferroni
        - title: BH
          name: BH
        - title: BY
          name: BY
        - title: fdr
          name: fdr
        - title: none
          name: none
      default: holm

    - name: effsizetype
      title: 'Effect Size Needed for Parametric Tests'
      type: List
      options:
        - title: biased
          name: biased
        - title: unbiased
          name: unbiased
        - title: eta
          name: eta
        - title: omega
          name: omega
      default: biased

    - name: violin
      title: Violin Plot
      type: Bool
      default: true

    - name: boxplot
      title: Box Plot
      type: Bool
      default: true

    - name: point
      title: Points
      type: Bool
      default: true

    - name: mytitle
      title: Title
      type: String
      default: 'Within Group Comparison'

    - name: xtitle
      title: X-Title
      type: String
      default: ''

    - name: ytitle
      title: Y-Title
      type: String
      default: ''

    - name: originaltheme
      title: Add GGStatsPlot Layer
      type: Bool
      default: false

    - name: resultssubtitle
      title: Statistical Results
      type: Bool
      default: true
...

# ggwithinstats(
#   data,
#   x,
#   y,
#   type = "parametric",
#   pairwise.comparisons = TRUE,
#   pairwise.display = "significant",
#   p.adjust.method = "holm",
#   effsize.type = "unbiased",
#   bf.prior = 0.707,
#   bf.message = TRUE,
#   results.subtitle = TRUE,
#   xlab = NULL,
#   ylab = NULL,
#   caption = NULL,
#   title = NULL,
#   subtitle = NULL,
#   sample.size.label = TRUE,
#   k = 2L,
#   conf.level = 0.95,
#   nboot = 100L,
#   tr = 0.1,
#   mean.plotting = TRUE,
#   mean.ci = FALSE,
#   mean.point.args = list(size = 5, color = "darkred"),
#   mean.label.args = list(size = 3),
#   point.path = TRUE,
#   point.path.args = list(alpha = 0.5, linetype = "dashed"),
#   mean.path = TRUE,
#   mean.path.args = list(color = "red", size = 1, alpha = 0.5),
#   notch = FALSE,
#   notchwidth = 0.5,
#   outlier.tagging = FALSE,
#   outlier.label = NULL,
#   outlier.coef = 1.5,
#   outlier.label.args = list(),
#   outlier.point.args = list(),
#   violin.args = list(width = 0.5, alpha = 0.2),
#   ggsignif.args = list(textsize = 3, tip_length = 0.01),
#   ggtheme = ggplot2::theme_bw(),
#   ggstatsplot.layer = TRUE,
#   package = "RColorBrewer",
#   palette = "Dark2",
#   ggplot.component = NULL,
#   output = "plot",
#   ...
# )




# bf.prior
# A number between 0.5 and 2 (default 0.707), the prior width to use in calculating Bayes factors.
#
# bf.message
# Logical that decides whether to display Bayes Factor in favor of the null hypothesis. This argument is relevant only for parametric test (Default: TRUE).
#
# results.subtitle
# Decides whether the results of statistical tests are to be displayed as a subtitle (Default: TRUE). If set to FALSE, only the plot will be returned.
#
# xlab
# Labels for x and y axis variables. If NULL (default), variable names for x and y will be used.
#
# ylab
# Labels for x and y axis variables. If NULL (default), variable names for x and y will be used.
#
# caption
# The text for the plot caption.

# subtitle
# The text for the plot subtitle. Will work only if results.subtitle = FALSE.
#
# sample.size.label
# Logical that decides whether sample size information should be displayed for each level of the grouping variable x (Default: TRUE).
#
# k
# Number of digits after decimal point (should be an integer) (Default: k = 2L).
#
# conf.level
# Scalar between 0 and 1. If unspecified, the defaults return 95% confidence/credible intervals (0.95).
#
# nboot
# Number of bootstrap samples for computing confidence interval for the effect size (Default: 100).
#
# tr
# Trim level for the mean when carrying out robust tests. If you get error stating "Standard error cannot be computed because of Winsorized variance of 0 (e.g., due to ties). Try to decrease the trimming level.", try to play around with the value of tr, which is by default set to 0.1. Lowering the value might help.

# mean.ci
# Logical that decides whether 95% confidence interval for mean is to be displayed (Default: FALSE).
#
# mean.point.args
# A list of additional aesthetic arguments to be passed to ggplot2::geom_point and ggrepel::geom_label_repel geoms involved mean value plotting.
#
# mean.label.args
# A list of additional aesthetic arguments to be passed to ggplot2::geom_point and ggrepel::geom_label_repel geoms involved mean value plotting.
#
# point.path, mean.path
# Logical that decides whether individual data points and means, respectively, should be connected using geom_path. Both default to TRUE. Note that point.path argument is relevant only when there are two groups (i.e., in case of a t-test). In case of large number of data points, it is advisable to set point.path = FALSE as these lines can overwhelm the plot.
#
# mean.path.args, point.path.args
# A list of additional aesthetic arguments passed on to geom_path connecting raw data points and mean points.
#
# notch
# A logical. If FALSE (default), a standard box plot will be displayed. If TRUE, a notched box plot will be used. Notches are used to compare groups; if the notches of two boxes do not overlap, this suggests that the medians are significantly different. In a notched box plot, the notches extend 1.58 * IQR / sqrt(n). This gives a roughly 95% confidence interval for comparing medians. IQR: Inter-Quartile Range.
#
# notchwidth
# For a notched box plot, width of the notch relative to the body (default 0.5).
#
# outlier.tagging
# Decides whether outliers should be tagged (Default: FALSE).
#
# outlier.label
# Label to put on the outliers that have been tagged. This can't be the same as x argument.
#
# outlier.coef
# Coefficient for outlier detection using Tukey's method. With Tukey's method, outliers are below (1st Quartile) or above (3rd Quartile) outlier.coef times the Inter-Quartile Range (IQR) (Default: 1.5).
#
# outlier.label.args
# A list of additional aesthetic arguments to be passed to ggplot2::geom_point and ggrepel::geom_label_repel geoms involved outlier value plotting.
#
# outlier.point.args
# A list of additional aesthetic arguments to be passed to ggplot2::geom_point and ggrepel::geom_label_repel geoms involved outlier value plotting.
#
# violin.args
# A list of additional aesthetic arguments to be passed to the geom_violin.
#
# ggsignif.args
# A list of additional aesthetic arguments to be passed to ggsignif::geom_signif.
#
# ggtheme
# A function, ggplot2 theme name. Default value is ggplot2::theme_bw(). Any of the ggplot2 themes, or themes from extension packages are allowed (e.g., ggthemes::theme_fivethirtyeight(), hrbrthemes::theme_ipsum_ps(), etc.).
#
# ggstatsplot.layer
# Logical that decides whether theme_ggstatsplot theme elements are to be displayed along with the selected ggtheme (Default: TRUE). theme_ggstatsplot is an opinionated theme layer that override some aspects of the selected ggtheme.
#
# package
# Name of the package from which the given palette is to be extracted. The available palettes and packages can be checked by running View(paletteer::palettes_d_names).
#
# palette
# Name of the package from which the given palette is to be extracted. The available palettes and packages can be checked by running View(paletteer::palettes_d_names).
#
# ggplot.component
# A ggplot component to be added to the plot prepared by ggstatsplot. This argument is primarily helpful for grouped_ variant of the current function. Default is NULL. The argument should be entered as a function.
#
# output
# Character that describes what is to be returned: can be "plot" (default) or "subtitle" or "caption". Setting this to "subtitle" will return the expression containing statistical results. If you have set results.subtitle = FALSE, then this will return a NULL. Setting this to "caption" will return the expression containing details about Bayes Factor analysis, but valid only when type = "parametric" and bf.message = TRUE, otherwise this will return a NULL. For functions ggpiestats and ggbarstats, setting output = "proptest" will return a dataframe containing results from proportion tests.


# grouped_ggwithinstats(
#   data,
#   x,
#   y,
#   grouping.var,
#   outlier.label = NULL,
#   title.prefix = NULL,
#   output = "plot",
#   ...,
#   plotgrid.args = list(),
#   title.text = NULL,
#   title.args = list(size = 16, fontface = "bold"),
#   caption.text = NULL,
#   caption.args = list(size = 10),
#   sub.text = NULL,
#   sub.args = list(size = 12)
# )
# Arguments
# data
# A dataframe (or a tibble) from which variables specified are to be taken. A matrix or tables will not be accepted.
#
# x
# The grouping variable from the dataframe data.
#
# y
# The response (a.k.a. outcome or dependent) variable from the dataframe data.
#
# grouping.var
# A single grouping variable (can be entered either as a bare name x or as a string "x").
#
# outlier.label
# Label to put on the outliers that have been tagged. This can't be the same as x argument.
#
# title.prefix
# Character string specifying the prefix text for the fixed plot title (name of each factor level) (Default: NULL). If NULL, the variable name entered for grouping.var will be used.
#
# output
# Character that describes what is to be returned: can be "plot" (default) or "subtitle" or "caption". Setting this to "subtitle" will return the expression containing statistical results. If you have set results.subtitle = FALSE, then this will return a NULL. Setting this to "caption" will return the expression containing details about Bayes Factor analysis, but valid only when type = "parametric" and bf.message = TRUE, otherwise this will return a NULL. For functions ggpiestats and ggbarstats, setting output = "proptest" will return a dataframe containing results from proportion tests.
#
# ...
# Arguments passed on to ggwithinstats
#
# point.path
# Logical that decides whether individual data points and means, respectively, should be connected using geom_path. Both default to TRUE. Note that point.path argument is relevant only when there are two groups (i.e., in case of a t-test). In case of large number of data points, it is advisable to set point.path = FALSE as these lines can overwhelm the plot.
#
# mean.path
# Logical that decides whether individual data points and means, respectively, should be connected using geom_path. Both default to TRUE. Note that point.path argument is relevant only when there are two groups (i.e., in case of a t-test). In case of large number of data points, it is advisable to set point.path = FALSE as these lines can overwhelm the plot.
#
# mean.path.args
# A list of additional aesthetic arguments passed on to geom_path connecting raw data points and mean points.
#
# point.path.args
# A list of additional aesthetic arguments passed on to geom_path connecting raw data points and mean points.
#
# type
# Type of statistic expected ("parametric" or "nonparametric" or "robust" or "bayes").Corresponding abbreviations are also accepted: "p" (for parametric), "np" (nonparametric), "r" (robust), or "bf"resp.
#
# pairwise.comparisons
# Logical that decides whether pairwise comparisons are to be displayed (default: TRUE). Please note that only significant comparisons will be shown by default. To change this behavior, select appropriate option with pairwise.display argument. The pairwise comparison dataframes are prepared using the pairwiseComparisons::pairwise_comparisons function. For more details about pairwise comparisons, see the documentation for that function.
#
# pairwise.display
# Decides which pairwise comparisons to display. Available options are "significant" (abbreviation accepted: "s") or "non-significant" (abbreviation accepted: "ns") or "everything"/"all". The default is "significant". You can use this argument to make sure that your plot is not uber-cluttered when you have multiple groups being compared and scores of pairwise comparisons being displayed.
#
# p.adjust.method
# Adjustment method for p-values for multiple comparisons. Possible methods are: "holm" (default), "hochberg", "hommel", "bonferroni", "BH", "BY", "fdr", "none".
#
# effsize.type
# Type of effect size needed for parametric tests. The argument can be "biased" (equivalent to "d" for Cohen's d for t-test; "eta" for partial eta-squared for anova) or "unbiased" (equivalent to "g" Hedge's g for t-test; "omega" for partial omega-squared for anova)).
#
# bf.prior
# A number between 0.5 and 2 (default 0.707), the prior width to use in calculating Bayes factors.
#
# bf.message
# Logical that decides whether to display Bayes Factor in favor of the null hypothesis. This argument is relevant only for parametric test (Default: TRUE).
#
# results.subtitle
# Decides whether the results of statistical tests are to be displayed as a subtitle (Default: TRUE). If set to FALSE, only the plot will be returned.
#
# xlab
# Labels for x and y axis variables. If NULL (default), variable names for x and y will be used.
#
# ylab
# Labels for x and y axis variables. If NULL (default), variable names for x and y will be used.
#
# caption
# The text for the plot caption.
#
# subtitle
# The text for the plot subtitle. Will work only if results.subtitle = FALSE.
#
# sample.size.label
# Logical that decides whether sample size information should be displayed for each level of the grouping variable x (Default: TRUE).
#
# k
# Number of digits after decimal point (should be an integer) (Default: k = 2L).
#
# conf.level
# Scalar between 0 and 1. If unspecified, the defaults return 95% confidence/credible intervals (0.95).
#
# nboot
# Number of bootstrap samples for computing confidence interval for the effect size (Default: 100).
#
# tr
# Trim level for the mean when carrying out robust tests. If you get error stating "Standard error cannot be computed because of Winsorized variance of 0 (e.g., due to ties). Try to decrease the trimming level.", try to play around with the value of tr, which is by default set to 0.1. Lowering the value might help.
#
# mean.plotting
# Logical that decides whether mean is to be highlighted and its value to be displayed (Default: TRUE).
#
# mean.ci
# Logical that decides whether 95% confidence interval for mean is to be displayed (Default: FALSE).
#
# mean.point.args
# A list of additional aesthetic arguments to be passed to ggplot2::geom_point and ggrepel::geom_label_repel geoms involved mean value plotting.
#
# mean.label.args
# A list of additional aesthetic arguments to be passed to ggplot2::geom_point and ggrepel::geom_label_repel geoms involved mean value plotting.
#
# notch
# A logical. If FALSE (default), a standard box plot will be displayed. If TRUE, a notched box plot will be used. Notches are used to compare groups; if the notches of two boxes do not overlap, this suggests that the medians are significantly different. In a notched box plot, the notches extend 1.58 * IQR / sqrt(n). This gives a roughly 95% confidence interval for comparing medians. IQR: Inter-Quartile Range.
#
# notchwidth
# For a notched box plot, width of the notch relative to the body (default 0.5).
#
# outlier.tagging
# Decides whether outliers should be tagged (Default: FALSE).
#
# outlier.coef
# Coefficient for outlier detection using Tukey's method. With Tukey's method, outliers are below (1st Quartile) or above (3rd Quartile) outlier.coef times the Inter-Quartile Range (IQR) (Default: 1.5).
#
# outlier.label.args
# A list of additional aesthetic arguments to be passed to ggplot2::geom_point and ggrepel::geom_label_repel geoms involved outlier value plotting.
#
# outlier.point.args
# A list of additional aesthetic arguments to be passed to ggplot2::geom_point and ggrepel::geom_label_repel geoms involved outlier value plotting.
#
# violin.args
# A list of additional aesthetic arguments to be passed to the geom_violin.
#
# ggsignif.args
# A list of additional aesthetic arguments to be passed to ggsignif::geom_signif.
#
# ggtheme
# A function, ggplot2 theme name. Default value is ggplot2::theme_bw(). Any of the ggplot2 themes, or themes from extension packages are allowed (e.g., ggthemes::theme_fivethirtyeight(), hrbrthemes::theme_ipsum_ps(), etc.).
#
# ggstatsplot.layer
# Logical that decides whether theme_ggstatsplot theme elements are to be displayed along with the selected ggtheme (Default: TRUE). theme_ggstatsplot is an opinionated theme layer that override some aspects of the selected ggtheme.
#
# package
# Name of the package from which the given palette is to be extracted. The available palettes and packages can be checked by running View(paletteer::palettes_d_names).
#
# palette
# Name of the package from which the given palette is to be extracted. The available palettes and packages can be checked by running View(paletteer::palettes_d_names).
#
# ggplot.component
# A ggplot component to be added to the plot prepared by ggstatsplot. This argument is primarily helpful for grouped_ variant of the current function. Default is NULL. The argument should be entered as a function.
#
# plotgrid.args
# A list of additional arguments to cowplot::plot_grid.
#
# title.text
# String or plotmath expression to be drawn as title for the combined plot.
#
# title.args
# A list of additional arguments provided to title, caption and sub, resp.
#
# caption.text
# String or plotmath expression to be drawn as the caption for the combined plot.
#
# caption.args
# A list of additional arguments provided to title, caption and sub, resp.
#
# sub.text
# The label with which the combined plot should be annotated. Can be a plotmath expression.
#
# sub.args
# A list of additional arguments provided to title, caption and sub, resp.