Add es_paired_lines and es_paired_lines_kwargs, and added tutorial and tests for this feature.

Author: JAnns98

dabest/_effsize_objects.py

@@ -1039,7 +1039,10 @@ def plot(
         es_errorbar_kwargs=None,
 
         prop_sample_counts=False,
-        prop_sample_counts_kwargs=None
+        prop_sample_counts_kwargs=None,
+
+        es_paired_lines=True,
+        es_paired_lines_kwargs=None,
     ):
         """
         Creates an estimation plot for the effect size of interest.
@@ -1193,17 +1196,17 @@ def plot(
         contrast_bars_kwargs : dict, default None
             Pass relevant keyword arguments to the contrast bars. Pass any keyword arguments accepted by 
             matplotlib.patches.Rectangle here, as a string. If None, the following keywords are passed:
-            {"color": None, "alpha": 0.3}
+            {"color": None, "alpha": 0.3, "zorder":-3}
         swarm_bars_kwargs : dict, default None
             Pass relevant keyword arguments to the swarm bars. Pass any keyword arguments accepted by 
             matplotlib.patches.Rectangle here, as a string. If None, the following keywords are passed:
-            {"color": None, "alpha": 0.3}
+            {"color": None, "alpha": 0.3, "zorder":-3}
 
         summary_bars : list, default None
             Pass a list of indices of the contrast objects to have summary bars displayed on the plot.
             For example, [0,1] will show summary bars for the first two contrast objects.
         summary_bars_kwargs: dict, default None
-            If None, the following keywords are passed: {"span_ax": False, "color": None, "alpha": 0.15}
+            If None, the following keywords are passed: {"span_ax": False, "color": None, "alpha": 0.15, "zorder":-3}
         delta_text : boolean, default True
             Whether or not to display the text deltas.
         delta_text_kwargs : dict, default None
@@ -1251,7 +1254,13 @@ def plot(
             Show the sample counts for each group in proportional plots
         prop_sample_counts_kwargs: dict, default None
             Pass relevant keyword arguments. If None, the following keywords are passed:
-            {'color': 'k', 'zorder': 5, 'ha': 'center', 'va': 'center'}
+            {'color': 'k', 'zorder': 5, 'ha': 'center', 'va': 'center'},
+
+        es_paired_lines: bool, default True
+            Whether or not to add lines to connect the effect size curves in paired plots.
+        es_paired_lines_kwargs: dict, default None
+            Pass relevant plot keyword arguments. If None, the following keywords are passed:
+            {"linestyle": "-", "linewidth": 2, "zorder": -2, "color": 'dimgray', "alpha": 1}
         
 
         Returns

dabest/misc_tools.py

@@ -93,13 +93,13 @@ def get_unique_categories(names):
         # For dict_keys and other iterables
         return np.unique(list(names))
 
-def get_params(effectsize_df, plot_kwargs):
+def get_params(effectsize_df: object, plot_kwargs: dict):
     """
-    Extracts the parameters from the `effectsize_df` and `plot_kwargs` objects for use in the plotter function.
+    Extracts parameters from the `effectsize_df` and `plot_kwargs` objects for use in the plotter function.
     
     Parameters
     ----------
-    effectsize_df : object (Dataframe)
+    effectsize_df : object
         A `dabest` EffectSizeDataFrame object.
     plot_kwargs : dict
         Kwargs passed to the plot function.
@@ -119,7 +119,6 @@ def get_params(effectsize_df, plot_kwargs):
     x1_level = dabest_obj.x1_level
     experiment_label = dabest_obj.experiment_label
 
-
     if effect_size not in ["mean_diff", "delta_g"] or not delta2:
         show_delta2 = False
     else:
@@ -352,7 +351,8 @@ def get_kwargs(plot_kwargs, ytick_color):
     default_summary_bars_kwargs = {
                     "span_ax": False,
                     "color": None, 
-                    "alpha": 0.15
+                    "alpha": 0.15,
+                    "zorder":-3
     }
     if plot_kwargs["summary_bars_kwargs"] is None:
         summary_bars_kwargs = default_summary_bars_kwargs
@@ -362,7 +362,8 @@ def get_kwargs(plot_kwargs, ytick_color):
     # Swarm bars kwargs.
     default_swarm_bars_kwargs = {
                     "color": None, 
-                    "alpha": 0.3
+                    "alpha": 0.3,
+                    "zorder":-3
     }
     if plot_kwargs["swarm_bars_kwargs"] is None:
         swarm_bars_kwargs = default_swarm_bars_kwargs
@@ -372,7 +373,8 @@ def get_kwargs(plot_kwargs, ytick_color):
     # Contrast bars kwargs.
     default_contrast_bars_kwargs = {
                     "color": None, 
-                    "alpha": 0.3
+                    "alpha": 0.3,
+                    "zorder":-3
     }
     if plot_kwargs["contrast_bars_kwargs"] is None:
         contrast_bars_kwargs = default_contrast_bars_kwargs
@@ -447,11 +449,25 @@ def get_kwargs(plot_kwargs, ytick_color):
     else:
         prop_sample_counts_kwargs = merge_two_dicts(default_prop_sample_counts_kwargs, plot_kwargs['prop_sample_counts_kwargs'])
 
+
+    # RM Lines kwargs
+    default_es_paired_lines_kwargs = {
+        "linestyle": "-",
+        "linewidth": 2,
+        "zorder": -2,
+        "color": 'dimgray',
+        "alpha": 1
+    }
+    if plot_kwargs["es_paired_lines_kwargs"] is None:
+        es_paired_lines_kwargs = default_es_paired_lines_kwargs
+    else:
+        es_paired_lines_kwargs = merge_two_dicts(default_es_paired_lines_kwargs, plot_kwargs["es_paired_lines_kwargs"])
+
     # Return the kwargs.
     return (swarmplot_kwargs, barplot_kwargs, sankey_kwargs, violinplot_kwargs, slopegraph_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, prop_sample_counts_kwargs)
+            es_marker_kwargs, es_errorbar_kwargs, prop_sample_counts_kwargs, es_paired_lines_kwargs)
 
 
 def get_color_palette(plot_kwargs, plot_data, xvar, show_pairs, idx, all_plot_groups):
@@ -485,6 +501,7 @@ def get_color_palette(plot_kwargs, plot_data, xvar, show_pairs, idx, all_plot_gr
         bootstraps_color_by_group = False
     if show_pairs:
         bootstraps_color_by_group = False
+
     # Handle the color palette.
     filled = True
     empty_circle = plot_kwargs["empty_circle"]

dabest/plot_tools.py

@@ -949,14 +949,14 @@ def summary_bars_plotter(summary_bars: list, results: object, ax_to_plot: object
                 ax_to_plot.add_patch(mpatches.Rectangle(
                     (summary_ci_low, starting_location),
                     summary_ci_high-summary_ci_low, summary_ymin+1, 
-                    zorder=-2, color=summary_color, 
+                    color=summary_color, 
                     **summary_bars_kwargs)
                     )
             else:
                 ax_to_plot.add_patch(mpatches.Rectangle(
                     (starting_location, summary_ci_low),
                     summary_xmax+1, summary_ci_high-summary_ci_low, 
-                    zorder=-2, color=summary_color, 
+                    color=summary_color, 
                     **summary_bars_kwargs)
                     )
 
@@ -1023,13 +1023,11 @@ def contrast_bars_plotter(results: object, ax_to_plot: object,  swarm_plot_ax: o
                 if type(contrast_bars_colors) == list 
                 else unpacked_idx[int(contrast_bars_x)]
             )
-            ax_to_plot.add_patch(mpatches.Rectangle((0,contrast_bars_x-0.5),contrast_bars_y, 0.5, zorder=-10, color=contrast_bars_colors[idx_selector], **contrast_bars_kwargs))
+            ax_to_plot.add_patch(mpatches.Rectangle((0,contrast_bars_x-0.5),contrast_bars_y, 0.5, color=contrast_bars_colors[idx_selector], **contrast_bars_kwargs))
 
-        if show_mini_meta:
-            ax_to_plot.add_patch(mpatches.Rectangle((0, max(swarm_plot_ax.get_yticks())-0.5), mini_meta_delta.difference, 0.5, zorder=-10, color='black', **contrast_bars_kwargs))
-
-        if show_delta2:
-            ax_to_plot.add_patch(mpatches.Rectangle((0, max(swarm_plot_ax.get_yticks())-0.5), delta_delta.difference, 0.5, zorder=-10, color='black', **contrast_bars_kwargs))
+        if show_mini_meta or show_delta2:
+            diff = mini_meta_delta.difference if show_mini_meta else delta_delta.difference
+            ax_to_plot.add_patch(mpatches.Rectangle((0, max(swarm_plot_ax.get_yticks())-0.5), diff, 0.5, color='black', **contrast_bars_kwargs))
 
     else:
         for contrast_bars_x,contrast_bars_y in zip(ticks_to_plot, contrast_means):
@@ -1038,13 +1036,11 @@ def contrast_bars_plotter(results: object, ax_to_plot: object,  swarm_plot_ax: o
                 if type(contrast_bars_colors) == list 
                 else unpacked_idx[int(contrast_bars_x)]
             )
-            ax_to_plot.add_patch(mpatches.Rectangle((contrast_bars_x-0.25,0),0.5, contrast_bars_y, zorder=-1, color=contrast_bars_colors[idx_selector], **contrast_bars_kwargs))
+            ax_to_plot.add_patch(mpatches.Rectangle((contrast_bars_x-0.25,0),0.5, contrast_bars_y, color=contrast_bars_colors[idx_selector], **contrast_bars_kwargs))
 
-        if show_mini_meta:
-            ax_to_plot.add_patch(mpatches.Rectangle((max(swarm_plot_ax.get_xticks())+2-0.25,0),0.5, mini_meta_delta.difference, zorder=-1, color='black', **contrast_bars_kwargs))
-
-        if show_delta2:
-            ax_to_plot.add_patch(mpatches.Rectangle((max(swarm_plot_ax.get_xticks())+2-0.25,0),0.5, delta_delta.difference, zorder=-1, color='black', **contrast_bars_kwargs))
+        if show_mini_meta or show_delta2:
+            diff = mini_meta_delta.difference if show_mini_meta else delta_delta.difference
+            ax_to_plot.add_patch(mpatches.Rectangle((max(swarm_plot_ax.get_xticks())+2-0.25,0),0.5, diff, color='black', **contrast_bars_kwargs))
 
     ax_to_plot.set_xlim(og_xlim)
     ax_to_plot.set_ylim(og_ylim)
@@ -1103,7 +1099,7 @@ def swarm_bars_plotter(plot_data: object, xvar: str, yvar: str, ax: object,
             else unpacked_idx[swarm_bars_x]
             )
         ax.add_patch(mpatches.Rectangle((swarm_bars_x-0.25,0), 0.5, swarm_bars_y, 
-                                        zorder=-1,color=swarm_bars_colors[idx_selector],**swarm_bars_kwargs))
+                                        color=swarm_bars_colors[idx_selector],**swarm_bars_kwargs))
 
     ax.set_xlim(og_xlim)
     ax.set_ylim(og_ylim)
@@ -1344,15 +1340,12 @@ def slopegraph_plotter(dabest_obj, plot_data, xvar, yvar, color_col, plot_palett
     """
     # Jitter Kwargs 
     # With help from devMJBL
-    jitter = slopegraph_kwargs["jitter"]
+    jitter = slopegraph_kwargs.pop("jitter")
     if jitter >= 1:
         err0 = "Jitter value is too high. Defaulting to 1."
         warnings.warn(err0)
         jitter = 1
-    rng = np.random.default_rng(slopegraph_kwargs["jitter_seed"])
-    for key in ["jitter", "jitter_seed"]:
-        if key in slopegraph_kwargs:
-            slopegraph_kwargs.pop(key)
+    rng = np.random.default_rng(slopegraph_kwargs.pop("jitter_seed"))
 
     # Pivot the long (melted) data.
     if color_col is None:
@@ -1539,7 +1532,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, bootstraps_color_by_group, plot_palette_contrast,
-                              horizontal, es_marker_kwargs, es_errorbar_kwargs):
+                              horizontal, es_marker_kwargs, es_errorbar_kwargs,
+                              idx, is_paired, es_paired_lines, es_paired_lines_kwargs):
     """
     Add effect size curves to the contrast plot.
 
@@ -1571,6 +1565,14 @@ def effect_size_curve_plotter(ticks_to_plot, results, ci_type, contrast_axes, vi
         Keyword arguments for the effectsize marker.
     es_errorbar_kwargs: dict
         Keyword arguments for the effectsize errorbar.
+    idx : list
+        List of indices of the raw groups.
+    is_paired : bool
+        Whether the data is paired.
+    es_paired_lines : bool
+        Whether to add lines for repeated measures data.
+    es_paired_lines_kwargs : dict
+        Keyword arguments for the repeated measures lines.
     """
 
     # Plot the curves
@@ -1618,21 +1620,56 @@ def effect_size_curve_plotter(ticks_to_plot, results, ci_type, contrast_axes, vi
         contrast_axes.plot(
             effsize_x,
             effsize_y,
-            # color=ytick_color,
             **es_marker_kwargs
         )
 
         # Plot the confidence interval.
         contrast_axes.plot(
             ci_x,
             ci_y,
-            # color=ytick_color,
             **es_errorbar_kwargs
         )
 
         contrast_xtick_labels.append(
             "{}\nminus\n{}".format(current_group, current_control)
         )
+
+    # Add lines for repeated measures data
+    if is_paired and es_paired_lines:
+        temp_num = 0
+        lines_to_plot_list = []
+
+        for group in idx:
+            new_group = []
+            if len(group) >= 2:
+                new_group.append(temp_num)
+                for i in range(1, len(group)):
+                    new_group.append(temp_num+i)
+            temp_num += len(group)
+            lines_to_plot_list.append(new_group)
+
+        for group in lines_to_plot_list:
+            if len(group) > 0:
+                mean_diffs_for_lines = []
+                for ticks in group:
+                    if ticks in ticks_to_plot:
+                        mean_diffs_for_lines.append(results.loc[ticks_to_plot.index(ticks)]["difference"])
+                    else:
+                        mean_diffs_for_lines.append(int(0))
+
+                if horizontal:
+                    contrast_axes.plot(
+                        mean_diffs_for_lines,
+                        group,
+                        **es_paired_lines_kwargs
+                    )
+                else:
+                    contrast_axes.plot(
+                        group, 
+                        mean_diffs_for_lines,
+                        **es_paired_lines_kwargs
+                    )
+
     return current_group, current_control, current_effsize, contrast_xtick_labels
 
 def gridkey_plotter(is_paired, idx, all_plot_groups, gridkey_rows, rawdata_axes, contrast_axes,