Added tutorial for group_summaries (gapped lines) and added more kwargs and clarified naming conventions.

Author: JAnns98

dabest/_effsize_objects.py

@@ -993,7 +993,6 @@ def plot(
         show_delta2=True,
         show_mini_meta=True,
         group_summaries=None,
-        group_summaries_offset=0.1,
         fig_size=None,
         dpi=100,
         ax=None,
@@ -1003,7 +1002,7 @@ def plot(
         slopegraph_kwargs=None,
         sankey_kwargs=None,
         reflines_kwargs=None,
-        group_summary_kwargs=None,
+        group_summaries_kwargs=None,
         legend_kwargs=None,
         title=None,
         fontsize_title=16,
@@ -1035,6 +1034,9 @@ def plot(
         gridkey_show_es=True,
         gridkey_delimiters=[';', '>', '_'],
         gridkey_kwargs=None,
+
+        es_marker_kwargs=None,
+        es_errorbar_kwargs=None,
     ):
         """
         Creates an estimation plot for the effect size of interest.
@@ -1113,9 +1115,6 @@ def plot(
             notched line beside each group. If 'median_quantiles', then the
             median and 25th and 75th percentiles of each group is plotted
             instead. If 'None', the summaries are not shown.
-        group_summaries_offset : float, default 0.1
-            If group summaries are displayed, they will be offset from the raw
-            data swarmplot groups by this value.
         fig_size : tuple, default None
             The desired dimensions of the figure as a (length, width) tuple.
         dpi : int, default 100
@@ -1150,12 +1149,13 @@ def plot(
             command here, as a dict. If None, the following keywords are
             passed to Axes.hlines : {'linestyle':'solid', 'linewidth':0.75,
             'zorder':2, 'color' : default y-tick color}.
-        group_summary_kwargs : dict, default None
+        group_summaries_kwargs : dict, default None
             Pass any keyword arguments accepted by the matplotlib.lines.Line2D
             command here, as a dict. This will change the appearance of the
             vertical summary lines for each group, if `group_summaries` is not
             'None'. If None, the following keywords are passed to
-            matplotlib.lines.Line2D : {'lw':2, 'alpha':1, 'zorder':3, 'gap_width_percent':1.5}.
+            matplotlib.lines.Line2D : {'lw':2, 'alpha':1, 'zorder':3, 
+            'gap_width_percent':1.5, 'offset':0.1, 'color':None}.
         legend_kwargs : dict, default None
             Pass any keyword arguments accepted by the matplotlib Axes
             `legend` command here, as a dict. If None, the following keywords
@@ -1234,6 +1234,12 @@ def plot(
                 'marker': "\u25CF",                 # Marker for the gridkey dots.
             }
 
+        es_marker_kwargs: dict, default None
+            Pass relevant keyword arguments to the effectsize marker plotting. If none, the following keywords are passed:
+            {'marker': 'o', 'size': plot_kwargs['es_marker_size'], 'color': 'black', 'alpha': 1, 'zorder': 1}
+        es_errorbar_kwargs: dict, default None
+            Pass relevant keyword arguments to the effectsize errorbar plotting. If none, the following keywords are passed:
+            {'color': 'black', 'lw': 2, 'linestyle': '-', 'alpha': 1,'zorder': 1,}
 
         Returns
         -------

dabest/misc_tools.py

@@ -166,13 +166,12 @@ def get_params(effectsize_df, plot_kwargs):
         float_contrast = False
 
     # Contrast Axes kwargs
-    es_marker_size = plot_kwargs["es_marker_size"]
     halfviolin_alpha = plot_kwargs["halfviolin_alpha"]
     ci_type = plot_kwargs["ci_type"]
 
     return (dabest_obj, plot_data, xvar, yvar, is_paired, effect_size, proportional, all_plot_groups, idx, 
             show_delta2, show_mini_meta, float_contrast, show_pairs, effect_size_type, group_summaries, err_color, horizontal,
-            results, es_marker_size, halfviolin_alpha, ci_type, x1_level, experiment_label)
+            results, halfviolin_alpha, ci_type, x1_level, experiment_label)
 
 def get_kwargs(plot_kwargs, ytick_color):
     """
@@ -233,6 +232,7 @@ def get_kwargs(plot_kwargs, ytick_color):
         "vert": True,
         "showextrema": False,
         "showmedians": False,
+        
     }
     if plot_kwargs["violinplot_kwargs"] is None:
         violinplot_kwargs = default_violinplot_kwargs
@@ -292,17 +292,19 @@ def get_kwargs(plot_kwargs, ytick_color):
             "group_summaries must be one of" " these: {}.".format(gs_default)
         )
 
-    default_group_summary_kwargs = {
+    default_group_summaries_kwargs = {
                         "zorder": 3, 
                         "lw": 2, 
                         "alpha": 1,
                         'gap_width_percent': 1.5,
+                        'offset': 0.1,
+                        'color': None
     }
-    if plot_kwargs["group_summary_kwargs"] is None:
-        group_summary_kwargs = default_group_summary_kwargs
+    if plot_kwargs["group_summaries_kwargs"] is None:
+        group_summaries_kwargs = default_group_summaries_kwargs
     else:
-        group_summary_kwargs = merge_two_dicts(
-            default_group_summary_kwargs, plot_kwargs["group_summary_kwargs"]
+        group_summaries_kwargs = merge_two_dicts(
+            default_group_summaries_kwargs, plot_kwargs["group_summaries_kwargs"]
         )
 
     # Redraw axes kwargs.
@@ -404,10 +406,37 @@ def get_kwargs(plot_kwargs, ytick_color):
     else:
         gridkey_kwargs = merge_two_dicts(default_gridkey_kwargs, plot_kwargs["gridkey_kwargs"])
 
+    # Effect size marker kwargs
+    default_es_marker_kwargs = {
+                'marker': 'o',
+                'markersize': plot_kwargs['es_marker_size'],
+                'color': ytick_color,
+                'alpha': 1,
+                'zorder': 1,
+    }
+    if plot_kwargs['es_marker_kwargs'] is None:
+        es_marker_kwargs = default_es_marker_kwargs
+    else:
+        es_marker_kwargs = merge_two_dicts(default_es_marker_kwargs, plot_kwargs['es_marker_kwargs'])
+
+    # Effect size error bar kwargs
+    default_es_errorbar_kwargs = {
+                'color': ytick_color,
+                'lw': 2,
+                'linestyle': '-',
+                'alpha': 1,
+                'zorder': 1,
+    }
+    if plot_kwargs['es_errorbar_kwargs'] is None:
+        es_errorbar_kwargs = default_es_errorbar_kwargs
+    else:
+        es_errorbar_kwargs = merge_two_dicts(default_es_errorbar_kwargs, plot_kwargs['es_errorbar_kwargs'])
+
     # Return the kwargs.
     return (swarmplot_kwargs, barplot_kwargs, sankey_kwargs, violinplot_kwargs, slopegraph_kwargs, 
-            reflines_kwargs, legend_kwargs, group_summary_kwargs, redraw_axes_kwargs, delta_dot_kwargs,
-            delta_text_kwargs, summary_bars_kwargs, swarm_bars_kwargs, contrast_bars_kwargs, table_kwargs, gridkey_kwargs)
+            reflines_kwargs, legend_kwargs, group_summaries_kwargs, redraw_axes_kwargs, delta_dot_kwargs,
+            delta_text_kwargs, summary_bars_kwargs, swarm_bars_kwargs, contrast_bars_kwargs, table_kwargs, gridkey_kwargs,
+            es_marker_kwargs, es_errorbar_kwargs)
 
 
 def get_color_palette(plot_kwargs, plot_data, xvar, show_pairs, idx, all_plot_groups):
@@ -1539,7 +1568,7 @@ def Redraw_Spines(rawdata_axes, contrast_axes, redraw_axes_kwargs, float_contras
 
 def extract_group_summaries(proportional, err_color, rawdata_axes, asymmetric_side, horizontal, 
                             bootstraps_color_by_group, plot_palette_raw, all_plot_groups,
-                            n_groups, color_col, ytick_color, plot_kwargs):
+                            n_groups, color_col, ytick_color, group_summaries_kwargs):
 
     from .plot_tools import get_swarm_spans
 
@@ -1582,7 +1611,11 @@ def extract_group_summaries(proportional, err_color, rawdata_axes, asymmetric_si
             xspans = xspans[:len(all_plot_groups)]
 
         group_summaries_method = "gapped_lines"
-        group_summaries_offset = xspans + np.array(plot_kwargs["group_summaries_offset"])
+        group_summaries_offset = xspans + np.array(group_summaries_kwargs["offset"])
         group_summaries_line_color = line_colors
 
+    if group_summaries_kwargs['color'] is not None:
+        group_summaries_line_color = group_summaries_kwargs.pop("color")
+    group_summaries_kwargs.pop("offset")
+
     return group_summaries_method, group_summaries_offset, group_summaries_line_color

dabest/plot_tools.py

@@ -1370,8 +1370,8 @@ def slopegraph_plotter(dabest_obj, plot_data, xvar, yvar, color_col, plot_palett
 
 def plot_minimeta_or_deltadelta_violins(show_mini_meta, effectsize_df, ci_type, rawdata_axes,
                                         contrast_axes, violinplot_kwargs, halfviolin_alpha, ytick_color, 
-                                        es_marker_size, group_summary_kwargs, contrast_xtick_labels, effect_size,
-                                        show_delta2, plot_kwargs, horizontal):
+                                        contrast_xtick_labels, effect_size, show_delta2, plot_kwargs, 
+                                        horizontal, es_marker_kwargs, es_errorbar_kwargs):
     """
     Add mini meta-analysis or delta-delta violin plots to the contrast plot.
 
@@ -1395,8 +1395,6 @@ def plot_minimeta_or_deltadelta_violins(show_mini_meta, effectsize_df, ci_type,
         Color of the yticks.
     es_marker_size : int
         Size of the effect size marker.
-    group_summary_kwargs : dict
-        Keyword arguments for the group summary.
     contrast_xtick_labels : list
         List of xtick labels for the contrast plot.
     effect_size : str
@@ -1407,7 +1405,13 @@ def plot_minimeta_or_deltadelta_violins(show_mini_meta, effectsize_df, ci_type,
         Keyword arguments for the plot.
     horizontal : bool
         If the plot is horizontal.
+    es_marker_kwargs: dict
+        Keyword arguments for the effectsize marker.
+    es_errorbar_kwargs: dict
+        Keyword arguments for the effectsize errorbar.
     """
+
+    # Plot the curve
     if show_mini_meta:
         mini_meta_delta = effectsize_df.mini_meta_delta
         data = mini_meta_delta.bootstraps_weighted_delta
@@ -1449,17 +1453,15 @@ def plot_minimeta_or_deltadelta_violins(show_mini_meta, effectsize_df, ci_type,
     contrast_axes.plot(
         effsize_x,
         effsize_y,
-        marker="o",
-        color=ytick_color,
-        markersize=es_marker_size,
+        # color=ytick_color,
+        **es_marker_kwargs
     )
     # Plot the confidence interval.
     contrast_axes.plot(
         ci_x,
         ci_y,
-        linestyle="-",
-        color=ytick_color,
-        linewidth=group_summary_kwargs["lw"],
+        # color=ytick_color,
+        **es_errorbar_kwargs
     )
 
     if horizontal:
@@ -1505,8 +1507,8 @@ def plot_minimeta_or_deltadelta_violins(show_mini_meta, effectsize_df, ci_type,
 
 
 def effect_size_curve_plotter(ticks_to_plot, results, ci_type, contrast_axes, violinplot_kwargs, halfviolin_alpha, 
-                              ytick_color, es_marker_size, group_summary_kwargs, bootstraps_color_by_group, plot_palette_contrast,
-                              horizontal):
+                              ytick_color, bootstraps_color_by_group, plot_palette_contrast,
+                              horizontal, es_marker_kwargs, es_errorbar_kwargs):
     """
     Add effect size curves to the contrast plot.
 
@@ -1528,16 +1530,19 @@ def effect_size_curve_plotter(ticks_to_plot, results, ci_type, contrast_axes, vi
         Color of the yticks.
     es_marker_size : int
         Size of the effect size marker.
-    group_summary_kwargs : dict
-        Keyword arguments for the group summary.
     bootstraps_color_by_group : bool
         Whether to color the bootstraps by group.
     plot_palette_contrast : dict
         Dictionary of colors used in the contrast plot.
     horizontal : bool
         If the plot is horizontal.
+    es_marker_kwargs: dict
+        Keyword arguments for the effectsize marker.
+    es_errorbar_kwargs: dict
+        Keyword arguments for the effectsize errorbar.
     """
 
+    # Plot the curves
     contrast_xtick_labels = []
     for j, tick in enumerate(ticks_to_plot):
         current_group = results.test[j]
@@ -1582,18 +1587,16 @@ def effect_size_curve_plotter(ticks_to_plot, results, ci_type, contrast_axes, vi
         contrast_axes.plot(
             effsize_x,
             effsize_y,
-            marker="o",
-            color=ytick_color,
-            markersize=es_marker_size,
+            # color=ytick_color,
+            **es_marker_kwargs
         )
 
         # Plot the confidence interval.
         contrast_axes.plot(
             ci_x,
             ci_y,
-            linestyle="-",
-            color=ytick_color,
-            linewidth=group_summary_kwargs["lw"],
+            # color=ytick_color,
+            **es_errorbar_kwargs
         )
 
         contrast_xtick_labels.append(