Updated slopegraph format to include group summaries

- Added group summary lines to slopegraphs
- Added ability to color effect size curves and the constrast bars and delta text via using custom_palette to paired plots

Author: JAnns98

dabest/_effsize_objects.py

@@ -1143,7 +1143,7 @@ def plot(
         face_color=None,
 
         raw_desat=0.5, # swarm_desat=0.5, OLD # bar_desat=0.5, OLD
-        contrast_desat=1, # halfviolin_desat=1, OLD
+        contrast_desat=1.0, # halfviolin_desat=1, OLD
 
         raw_alpha=None, # NEW
         contrast_alpha=0.8, # halfviolin_alpha=0.8, OLD
@@ -1478,7 +1478,8 @@ def plot(
 
         if raw_alpha is None:
             raw_alpha = (0.4 if self.is_proportional and self.is_paired 
-                         else 0.5 if self.is_paired
+                         else 0.5 if self.is_paired and (color_col is not None or self.__delta2)
+                         else 0.2 if self.is_paired and color_col is None
                          else 1.0
             )
 

dabest/misc_tools.py

@@ -203,7 +203,8 @@ def get_params(
 
 def get_kwargs(
         plot_kwargs: dict, 
-        ytick_color
+        ytick_color,
+        is_paired: bool = False
     ):
     """
     Extracts the kwargs from the `plot_kwargs` object for use in the plotter function.
@@ -214,6 +215,8 @@ def get_kwargs(
         Kwargs passed to the plot function.
     ytick_color : str or color list
         Color of the yticks.
+    is_paired : bool, optional
+        A boolean flag to determine if the plot is for paired data. Default is False.
     """
     from .misc_tools import merge_two_dicts
 
@@ -334,7 +337,7 @@ def get_kwargs(
     default_group_summaries_kwargs = {
                         "zorder": 3, 
                         "lw": 2, 
-                        "alpha": 1,
+                        "alpha": 1 if not is_paired else 0.6,
                         'gap_width_percent': 1.5,
                         'offset': 0.1,
                         'color': None
@@ -548,7 +551,13 @@ def get_color_palette(
         color_groups = pd.unique(plot_data[color_col])
         bootstraps_color_by_group = False
     if show_pairs:
-        bootstraps_color_by_group = False
+        if plot_kwargs["custom_palette"] is not None:
+            if delta2 or sankey:
+                bootstraps_color_by_group = False
+            else:
+                bootstraps_color_by_group = True
+        else:
+            bootstraps_color_by_group = False
 
     # Handle the color palette.
     filled = True
@@ -1856,13 +1865,15 @@ def color_picker(color_type: str,
                  elements: list, 
                  color_col: str, 
                  show_pairs: bool, 
-                 color_palette: dict) -> list:
+                 color_palette: dict,
+                 bootstraps_color_by_group: bool) -> list:
     num_of_elements = len(elements)
     colors = (
         [kwargs.pop('color')] * num_of_elements
         if kwargs.get('color', None) is not None
         else ['black'] * num_of_elements
-        if color_col is not None or show_pairs 
+        # if color_col is not None or show_pairs
+        if color_col is not None or not bootstraps_color_by_group
         else list(color_palette.values())
     )
     if color_type in ['contrast', 'summary', 'delta_text']:
@@ -1877,7 +1888,7 @@ def color_picker(color_type: str,
     return final_colors
 
 
-def prepare_bars_for_plot(bar_type, bar_kwargs, horizontal, plot_palette_raw, color_col, show_pairs,
+def prepare_bars_for_plot(bar_type, bar_kwargs, horizontal, plot_palette_raw, color_col, show_pairs, bootstraps_color_by_group,
                           plot_data = None, xvar = None, yvar = None,  # Raw data
                           results = None, ticks_to_plot = None, extra_delta = None, # Contrast data
                           reference_band = None, summary_axes = None, ci_type = None  # Summary data
@@ -1951,7 +1962,8 @@ def prepare_bars_for_plot(bar_type, bar_kwargs, horizontal, plot_palette_raw, co
                 elements = ticks_to_plot if bar_type=='contrast' else ticks, 
                 color_col = color_col, 
                 show_pairs = show_pairs, 
-                color_palette = plot_palette_raw
+                color_palette = plot_palette_raw,
+                bootstraps_color_by_group = bootstraps_color_by_group
             )
     if bar_type == 'contrast' and extra_delta is not None:
         colors.append('black')

dabest/plot_tools.py

@@ -904,6 +904,7 @@ def delta_text_plotter(
         show_pairs: bool,
         float_contrast: bool,
         extra_delta: float,
+        bootstraps_color_by_group: bool = False
     ):
     """
     Add delta text to the contrast plot.
@@ -928,6 +929,8 @@ def delta_text_plotter(
         Whether the DABEST plot uses Gardner-Altman or Cummings.
     extra_delta : float or None
         The extra mini-meta or delta-delta value if applicable.
+    bootstraps_color_by_group : bool, optional
+        Whether to color the bootstraps by group. Default is False.
     """
     # Colors
     from .misc_tools import color_picker
@@ -936,7 +939,8 @@ def delta_text_plotter(
                                      elements = ticks_to_plot, 
                                      color_col = color_col, 
                                      show_pairs = show_pairs, 
-                                     color_palette = plot_palette_raw
+                                     color_palette = plot_palette_raw,
+                                     bootstraps_color_by_group = bootstraps_color_by_group
                                     )
 
     num_of_elements = len(ticks_to_plot) + 1 if extra_delta is not None else len(ticks_to_plot)
@@ -1091,7 +1095,8 @@ def slopegraph_plotter(
         temp_idx: list, 
         horizontal: bool,
         temp_all_plot_groups: list,
-        plot_kwargs: dict
+        plot_kwargs: dict,
+        group_summaries_kwargs: dict
     ):
     """
     Add slopegraph to the rawdata axes.
@@ -1124,6 +1129,8 @@ def slopegraph_plotter(
         List of all plot groups.
     plot_kwargs : dict
         Keyword arguments for the plot.
+    group_summaries_kwargs : dict, optional
+        Keyword arguments for group summaries, if applicable.
 
     """
     # Jitter Kwargs 
@@ -1178,6 +1185,45 @@ def slopegraph_plotter(
             x_points, y_points = (y_points, x_points) if horizontal else (x_points, y_points)
             rawdata_axes.plot(x_points, y_points, **slopegraph_kwargs)
 
+        # Add the group summaries if applicable.
+        group_summaries = plot_kwargs.get("group_summaries", None)
+        if group_summaries is not None:
+            for key in ['gap_width_percent', 'offset']:
+                group_summaries_kwargs.pop(key, None)
+            group_summaries_kwargs['color'] = 'black' if group_summaries_kwargs.get('color') is None else group_summaries_kwargs['color']
+            group_summaries_kwargs['capsize'] = 0 if group_summaries_kwargs.get('capsize') is None else group_summaries_kwargs['capsize']
+
+            index_points = [t for t in range(x_start, x_start + grp_count)]
+            av_points, err_points, lo_points, hi_points = [], [], [], []
+            for group in range(len(index_points)):
+                if group_summaries == "mean_sd":
+                    av_points.append(current_pair.iloc[:, int(group)].mean())
+                    err_points.append(current_pair.iloc[:, int(group)].std())
+                elif group_summaries == "median_quartiles":
+                    median = current_pair.iloc[:, int(group)].median()
+                    av_points.append(median)
+                    lo_points.append(median - current_pair.iloc[:, int(group)].quantile(0.25))
+                    hi_points.append(current_pair.iloc[:, int(group)].quantile(0.75) - median)
+
+            if group_summaries == "median_quartiles":
+                err_points = [lo_points, hi_points] 
+
+            # Plot the lines
+            if horizontal:
+                rawdata_axes.errorbar(
+                        av_points,
+                        index_points, 
+                        xerr=err_points, 
+                        **group_summaries_kwargs
+                        )
+            else:
+                rawdata_axes.errorbar(
+                        index_points, 
+                        av_points, 
+                        yerr=err_points, 
+                        **group_summaries_kwargs
+                        )
+
         x_start = x_start + grp_count
 
     # Set the tick labels, because the slopegraph plotting doesn't.

dabest/plotter.py

@@ -137,7 +137,8 @@ def effectsize_df_plotter(effectsize_df: object, **plot_kwargs) -> matplotlib.fi
      raw_bars_kwargs, contrast_bars_kwargs, table_kwargs, gridkey_kwargs, contrast_marker_kwargs, 
      contrast_errorbar_kwargs, prop_sample_counts_kwargs, contrast_paired_lines_kwargs) = get_kwargs(
                                                                                                 plot_kwargs = plot_kwargs, 
-                                                                                                ytick_color = ytick_color
+                                                                                                ytick_color = ytick_color,
+                                                                                                is_paired = effectsize_df.is_paired
     )
 
     (dabest_obj, plot_data, xvar, yvar, is_paired, effect_size, proportional, 
@@ -219,6 +220,7 @@ def effectsize_df_plotter(effectsize_df: object, **plot_kwargs) -> matplotlib.fi
                 horizontal = horizontal,
                 temp_all_plot_groups = temp_all_plot_groups, 
                 plot_kwargs = plot_kwargs,
+                group_summaries_kwargs = group_summaries_kwargs
             )
 
             ## Add delta dots to the contrast axes for paired plots.
@@ -333,7 +335,7 @@ def effectsize_df_plotter(effectsize_df: object, **plot_kwargs) -> matplotlib.fi
 
     ## Swarm bars
     raw_bars = plot_kwargs["raw_bars"]
-    if raw_bars and not proportional and not horizontal: #Currently not supporting swarm bars for horizontal plots (looks weird)
+    if raw_bars and not proportional and not is_paired and not horizontal: #Currently not supporting swarm bars for horizontal plots (looks weird)
         raw_bars_dict, raw_bars_kwargs = prepare_bars_for_plot(
                                                     bar_type = 'raw', 
                                                     bar_kwargs = raw_bars_kwargs, 
@@ -343,7 +345,8 @@ def effectsize_df_plotter(effectsize_df: object, **plot_kwargs) -> matplotlib.fi
                                                     show_pairs = show_pairs, 
                                                     plot_data = plot_data,
                                                     xvar = xvar, 
-                                                    yvar = yvar,      
+                                                    yvar = yvar,    
+                                                    bootstraps_color_by_group = bootstraps_color_by_group,  
                                         )
         add_bars_to_plot(bar_dict = raw_bars_dict, 
                          ax = rawdata_axes, 
@@ -424,6 +427,7 @@ def effectsize_df_plotter(effectsize_df: object, **plot_kwargs) -> matplotlib.fi
                                                     show_pairs = show_pairs, 
                                                     results = results, 
                                                     ticks_to_plot = ticks_to_plot, 
+                                                    bootstraps_color_by_group = bootstraps_color_by_group,  
                                                     extra_delta = (effectsize_df.mini_meta.difference if show_mini_meta 
                                                                   else effectsize_df.delta_delta.difference if show_delta2
                                                                   else None)
@@ -445,6 +449,7 @@ def effectsize_df_plotter(effectsize_df: object, **plot_kwargs) -> matplotlib.fi
                     plot_palette_raw = plot_palette_raw, 
                     show_pairs = show_pairs,
                     float_contrast = float_contrast, 
+                    bootstraps_color_by_group = bootstraps_color_by_group,
                     extra_delta = (effectsize_df.mini_meta.difference if show_mini_meta 
                                                                   else effectsize_df.delta_delta.difference if show_delta2
                                                                   else None),
@@ -588,6 +593,7 @@ def effectsize_df_plotter(effectsize_df: object, **plot_kwargs) -> matplotlib.fi
                                                                        reference_band = reference_band, 
                                                                        summary_axes = contrast_axes, 
                                                                        ci_type = ci_type,
+                                                                       bootstraps_color_by_group = bootstraps_color_by_group,
                                                                     )
 
         add_bars_to_plot(bar_dict = reference_band_dict,

nbs/API/effsize_objects.ipynb

@@ -1343,7 +1343,7 @@
     "        face_color=None,\n",
     "\n",
     "        raw_desat=0.5, # swarm_desat=0.5, OLD # bar_desat=0.5, OLD\n",
-    "        contrast_desat=1, # halfviolin_desat=1, OLD\n",
+    "        contrast_desat=1.0, # halfviolin_desat=1, OLD\n",
     "\n",
     "        raw_alpha=None, # NEW\n",
     "        contrast_alpha=0.8, # halfviolin_alpha=0.8, OLD\n",
@@ -1678,7 +1678,8 @@
     "\n",
     "        if raw_alpha is None:\n",
     "            raw_alpha = (0.4 if self.is_proportional and self.is_paired \n",
-    "                         else 0.5 if self.is_paired\n",
+    "                         else 0.5 if self.is_paired and (color_col is not None or self.__delta2)\n",
+    "                         else 0.2 if self.is_paired and color_col is None\n",
     "                         else 1.0\n",
     "            )\n",
     "\n",

nbs/API/misc_tools.ipynb

@@ -256,7 +256,8 @@
     "\n",
     "def get_kwargs(\n",
     "        plot_kwargs: dict, \n",
-    "        ytick_color\n",
+    "        ytick_color,\n",
+    "        is_paired: bool = False\n",
     "    ):\n",
     "    \"\"\"\n",
     "    Extracts the kwargs from the `plot_kwargs` object for use in the plotter function.\n",
@@ -267,6 +268,8 @@
     "        Kwargs passed to the plot function.\n",
     "    ytick_color : str or color list\n",
     "        Color of the yticks.\n",
+    "    is_paired : bool, optional\n",
+    "        A boolean flag to determine if the plot is for paired data. Default is False.\n",
     "    \"\"\"\n",
     "    from .misc_tools import merge_two_dicts\n",
     "\n",
@@ -387,7 +390,7 @@
     "    default_group_summaries_kwargs = {\n",
     "                        \"zorder\": 3, \n",
     "                        \"lw\": 2, \n",
-    "                        \"alpha\": 1,\n",
+    "                        \"alpha\": 1 if not is_paired else 0.6,\n",
     "                        'gap_width_percent': 1.5,\n",
     "                        'offset': 0.1,\n",
     "                        'color': None\n",
@@ -601,7 +604,13 @@
     "        color_groups = pd.unique(plot_data[color_col])\n",
     "        bootstraps_color_by_group = False\n",
     "    if show_pairs:\n",
-    "        bootstraps_color_by_group = False\n",
+    "        if plot_kwargs[\"custom_palette\"] is not None:\n",
+    "            if delta2 or sankey:\n",
+    "                bootstraps_color_by_group = False\n",
+    "            else:\n",
+    "                bootstraps_color_by_group = True\n",
+    "        else:\n",
+    "            bootstraps_color_by_group = False\n",
     "\n",
     "    # Handle the color palette.\n",
     "    filled = True\n",
@@ -1909,13 +1918,15 @@
     "                 elements: list, \n",
     "                 color_col: str, \n",
     "                 show_pairs: bool, \n",
-    "                 color_palette: dict) -> list:\n",
+    "                 color_palette: dict,\n",
+    "                 bootstraps_color_by_group: bool) -> list:\n",
     "    num_of_elements = len(elements)\n",
     "    colors = (\n",
     "        [kwargs.pop('color')] * num_of_elements\n",
     "        if kwargs.get('color', None) is not None\n",
     "        else ['black'] * num_of_elements\n",
-    "        if color_col is not None or show_pairs \n",
+    "        # if color_col is not None or show_pairs\n",
+    "        if color_col is not None or not bootstraps_color_by_group\n",
     "        else list(color_palette.values())\n",
     "    )\n",
     "    if color_type in ['contrast', 'summary', 'delta_text']:\n",
@@ -1930,7 +1941,7 @@
     "    return final_colors\n",
     "\n",
     "\n",
-    "def prepare_bars_for_plot(bar_type, bar_kwargs, horizontal, plot_palette_raw, color_col, show_pairs,\n",
+    "def prepare_bars_for_plot(bar_type, bar_kwargs, horizontal, plot_palette_raw, color_col, show_pairs, bootstraps_color_by_group,\n",
     "                          plot_data = None, xvar = None, yvar = None,  # Raw data\n",
     "                          results = None, ticks_to_plot = None, extra_delta = None, # Contrast data\n",
     "                          reference_band = None, summary_axes = None, ci_type = None  # Summary data\n",
@@ -2004,7 +2015,8 @@
     "                elements = ticks_to_plot if bar_type=='contrast' else ticks, \n",
     "                color_col = color_col, \n",
     "                show_pairs = show_pairs, \n",
-    "                color_palette = plot_palette_raw\n",
+    "                color_palette = plot_palette_raw,\n",
+    "                bootstraps_color_by_group = bootstraps_color_by_group\n",
     "            )\n",
     "    if bar_type == 'contrast' and extra_delta is not None:\n",
     "        colors.append('black')\n",