Update summary_bars name to reference_band

Update summary bar name to reference band

Author: JAnns98

README.md

@@ -40,52 +40,56 @@ performance improvements. It’s a big one!
 
 5.  **Other Visualization Improvements**:
 
-    - **Raw, Contrast, and Summary bars**: Our visualization package now
-      includes three types of customizable bars to enhance data
-      interpretation:
-
-      - **Raw Bars**: Colored rectangles that extend from the zero line
-        to the mean of each group’s raw data. These bars visually
-        highlight the central tendency of the raw data.
-
-      - **Contrast Bars**: Similar to raw bars, these highlight the
-        effect size difference between two groups (typically test and
-        control) in the contrast axis. They provide a visual
-        representation of the differences between groups.
-
-      - **Summary Bars**: Optional bars that can be added to emphasize a
-        specific effect size across the entire contrast axis. Unlike raw
-        and contrast bars, these span horizontally (or vertically if
-        `horizontal=True`) and are not displayed by default.
+    - **Comparing means and effect sizes**: The estimation plots now
+      include three types of customizable visual features to enhance
+      contextualization and comparison of means and effect sizes:
+
+      - **Bars for the mean of the observed values (`raw_bars`)**:
+        Colored rectangles that extend from the zero line to the mean of
+        each group’s raw data. These bars visually highlight the central
+        tendency of the raw data.
+
+      - **Bars for effect size/s (`contrast_bars`)**: Similar to raw
+        bars, these highlight the effect-size difference between two
+        groups (typically test and control) in the contrast axis. They
+        provide a visual representation of the differences between
+        groups.
+
+      - **Summary bands (`reference_band`)**: An optional band or ribbon
+        that can be added to emphasize a specific effect size’s
+        confidence interval that is used as a reference range across the
+        entire contrast axis. Unlike raw and contrast bars, these span
+        horizontally (or vertically if `horizontal=True`) and are not
+        displayed by default.
 
         Raw and contrast bars are shown by default. Users can customize
-        these bars and add summary bars as needed. For detailed
+        these bars and add summary bands as needed. For detailed
         customization instructions, please refer to the [Plot Aesthetics
         tutorial](../tutorials/09-plot_aesthetics.html).
 
-    - **Tighter spacing in Delta-Delta and Mini-Meta Plots**: We have
+    - **Tighter spacing in delta-delta and mini-meta plots**: We have
       adjusted the spacing of delta-delta and mini-meta plots to reduce
       whitespace. The new format brings the overall effect size closer
       to the two-groups effect sizes. In addition, delta-delta plots now
       have a gap in the zero line to separate the delta-delta from the ∆
       effect sizes.
 
-    - **Delta-Delta Effect Sizes for Proportion Plots**: In addition to
+    - **Delta-delta effect sizes for proportion plots**: In addition to
       continuous data, delta-delta plots now support binary data
       (proportions). This means that 2-way designs for binary outcomes
       can be analyzed with DABEST.
 
-    - **Proportion Plots Sample Sizes**: The sample size of each binary
+    - **Proportion plots sample sizes**: The sample size of each binary
       option for each group can now be displayed. These can be toggled
       on/off via the `prop_sample_counts` parameter.
 
-    - **Effect Size Lines for Paired Plots**: Along with lines
+    - **Effect size lines for paired plots**: Along with lines
       connecting paired observed values, the paired plots now also
       display lines linking the effect sizes within a group in the
       contrast axes. These lines can be toggled on/off via the
       `contrast_paired_lines` parameter.
 
-    - **Baseline Error Curves**: To represent the baseline/control group
+    - **Baseline error curves**: To represent the baseline/control group
       in the contrast axes, it is now possible to plot the baseline dot
       and the baseline error curve. The dot is shown by default, while
       the curve can be toggled on/off via the `show_baseline_ec`
@@ -94,25 +98,25 @@ performance improvements. It’s a big one!
       be used to show that the baseline itself is an estimate inferred
       from the observed values of the control data.
 
-    - **Delta Text**: Effect-size deltas (e.g. mean differences) are now
+    - **Delta text**: Effect-size deltas (e.g. mean differences) are now
       displayed as numerals next to their respective effect size. This
       can be toggled on/off via the `delta_text` parameter.
 
-    - **Empty Circle Color Palette**: A new swarmplot color palette
+    - **Empty circle color palette**: A new swarmplot color palette
       modification is available for unpaired plots via the
       `empty_circle` parameter in the `.plot()` method. This option
       modifies the two-group swarmplots to have empty circles for the
       control group and filled circles for the experimental group.
 
 6.  **Miscellaneous Improvements & Adjustments**
 
-    - **Numba for Speed Improvements**: We have added
+    - **Numba for speed improvements**: We have added
       [Numba](https://numba.pydata.org/) to speed up the various
       calculations in DABEST. Precalculations will be performed during
       import, which will help speed up the subsequent loading and
       plotting of data.
 
-    - **Terminology/Naming Updates**: During the refactoring of the
+    - **Terminology/naming updates**: During the refactoring of the
       code, we have made several updates to the documentation and
       terminology to improve clarity and consistency. For example:
 
@@ -131,11 +135,11 @@ performance improvements. It’s a big one!
         alongside these (if a delta-delta experiment was loaded
         correctly).
 
-    - **Updated Tutorial Pages**: We have updated the tutorial pages to
+    - **Updated tutorial pages**: We have updated the tutorial pages to
       reflect the new features and changes. The tutorial pages are now
       more comprehensive and (hopefully!) more intuitive!
 
-    - **Results Dataframe for Delta-Delta and Mini-Meta Plots**: A
+    - **Results dataframe for delta-delta and mini-meta plots**: A
       results dataframe can now be extracted for both the delta-delta
       and mini-meta effect size data (similar to the results dataframe
       for the regular effect sizes). These can be found via the

dabest/_effsize_objects.py

@@ -1186,8 +1186,8 @@ def plot(
         raw_bars_kwargs=None, # swarm_bars_kwargs=None, OLD
         contrast_bars=True,
         contrast_bars_kwargs=None,
-        summary_bars=None,
-        summary_bars_kwargs=None,
+        reference_band=None,
+        reference_band_kwargs=None,
         delta_text=True,
         delta_text_kwargs=None,
         delta_dot=True,
@@ -1386,10 +1386,10 @@ def plot(
             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, "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
+        reference_band : list, default None
+            Pass a list of indices of the contrast objects to have reference bands displayed on the plot.
+            For example, [0,1] will show reference bands for the first two contrast objects.
+        reference_band_kwargs: dict, default None
             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.

dabest/forest_plot.py

@@ -264,15 +264,15 @@ def check_for_errors(**kwargs):
     if not isinstance(remove_spines, bool):
         raise TypeError("`remove_spines` must be a boolean value.")
 
-    # Summary bars
-    summary_bars = kwargs.get('summary_bars')
-    if summary_bars is not None:
-        if not isinstance(summary_bars, list | tuple):
-            raise TypeError("`summary_bars` must be a list/tuple of indices (ints).")
-        if not all(isinstance(i, int) for i in summary_bars):
-            raise TypeError("`summary_bars` must be a list/tuple of indices (ints).")
-        if any(i >= number_of_curves_to_plot for i in summary_bars):
-            raise ValueError("Index {} chosen is out of range for the contrast objects.".format([i for i in summary_bars if i >= number_of_curves_to_plot]))
+    # Reference band
+    reference_band = kwargs.get('reference_band')
+    if reference_band is not None:
+        if not isinstance(reference_band, list | tuple):
+            raise TypeError("`reference_band` must be a list/tuple of indices (ints).")
+        if not all(isinstance(i, int) for i in reference_band):
+            raise TypeError("`reference_band` must be a list/tuple of indices (ints).")
+        if any(i >= number_of_curves_to_plot for i in reference_band):
+            raise ValueError("Index {} chosen is out of range for the contrast objects.".format([i for i in reference_band if i >= number_of_curves_to_plot]))
 
     # Delta text
     delta_text = kwargs.get('delta_text')
@@ -296,7 +296,7 @@ def get_kwargs(
         errorbar_kwargs,
         delta_text_kwargs,
         contrast_bars_kwargs,
-        summary_bars_kwargs,
+        reference_band_kwargs,
         marker_size
     ):
     from .misc_tools import merge_two_dicts
@@ -377,20 +377,20 @@ def get_kwargs(
     else:
         contrast_bars_kwargs = merge_two_dicts(default_contrast_bars_kwargs, contrast_bars_kwargs)
 
-    # Summary bars kwargs.
-    default_summary_bars_kwargs = {
+    # reference band kwargs.
+    default_reference_band_kwargs = {
                     "span_ax": False,
                     "color": None, 
                     "alpha": 0.15,
                     "zorder":-3
     }
-    if summary_bars_kwargs is None:
-        summary_bars_kwargs = default_summary_bars_kwargs
+    if reference_band_kwargs is None:
+        reference_band_kwargs = default_reference_band_kwargs
     else:
-        summary_bars_kwargs = merge_two_dicts(default_summary_bars_kwargs, summary_bars_kwargs)
+        reference_band_kwargs = merge_two_dicts(default_reference_band_kwargs, reference_band_kwargs)
 
     return (violin_kwargs, zeroline_kwargs, marker_kwargs, errorbar_kwargs, 
-            delta_text_kwargs, contrast_bars_kwargs, summary_bars_kwargs)
+            delta_text_kwargs, contrast_bars_kwargs, reference_band_kwargs)
 
 def color_palette(
         custom_palette, 
@@ -448,8 +448,8 @@ def forest_plot(
 
     contrast_bars: bool = True,
     contrast_bars_kwargs: dict = None,
-    summary_bars: list|tuple = None,
-    summary_bars_kwargs: dict = None,
+    reference_band: list|tuple = None,
+    reference_band_kwargs: dict = None,
 
     violin_kwargs: Optional[dict] = None,
     zeroline_kwargs: Optional[dict] = None,
@@ -516,10 +516,10 @@ def forest_plot(
         If True, it adds bars from the zeroline to the effect size curve.
     contrast_bars_kwargs : dict, default=None
         Additional keyword arguments for the contrast_bars.
-    summary_bars: list | tuple, default=None,
-        If True, it adds summary bars to the relevant effect size curves.
-    summary_bars_kwargs : dict, default=None,
-        Additional keyword arguments for the summary_bars.
+    reference_band: list | tuple, default=None,
+        It adds reference bands to the relevant effect size curves.
+    reference_band_kwargs : dict, default=None,
+        Additional keyword arguments for the reference_band.
     violin_kwargs : Optional[dict], default=None
         Additional arguments for violin plot customization.
     zeroline_kwargs : Optional[dict], default=None
@@ -559,15 +559,15 @@ def forest_plot(
 
     # Get Kwargs
     (violin_kwargs, zeroline_kwargs, marker_kwargs, errorbar_kwargs, 
-     delta_text_kwargs, contrast_bars_kwargs, summary_bars_kwargs) = get_kwargs(
+     delta_text_kwargs, contrast_bars_kwargs, reference_band_kwargs) = get_kwargs(
                                                                         violin_kwargs = violin_kwargs,
                                                                         zeroline_kwargs = zeroline_kwargs,
                                                                         horizontal = horizontal,
                                                                         marker_kwargs = marker_kwargs,
                                                                         errorbar_kwargs = errorbar_kwargs,
                                                                         delta_text_kwargs = delta_text_kwargs,
                                                                         contrast_bars_kwargs = contrast_bars_kwargs,
-                                                                        summary_bars_kwargs = summary_bars_kwargs,
+                                                                        reference_band_kwargs = reference_band_kwargs,
                                                                         marker_size = marker_size
     )
 
@@ -726,19 +726,19 @@ def forest_plot(
             else:
                 ax.add_patch(mpatches.Rectangle((x, 0), 0.25, y, color=bar_colors[x-1], **contrast_bars_kwargs))
 
-    # Summary bars
-    if summary_bars:
-        _bar_color = summary_bars_kwargs.pop('color')
+    # Reference band
+    if reference_band:
+        _bar_color = reference_band_kwargs.pop('color')
         if _bar_color is not None:
             bar_colors = [_bar_color] * number_of_curves_to_plot
         else:
             bar_colors = violin_colors
 
-        span_ax = summary_bars_kwargs.pop("span_ax")
+        span_ax = reference_band_kwargs.pop("span_ax")
         summary_xmin, summary_xmax = ax.get_xlim()
         summary_ymin, summary_ymax = ax.get_ylim()
 
-        for summary_index in summary_bars:
+        for summary_index in reference_band:
             if span_ax == True:
                 starting_location = summary_ymin if horizontal else summary_xmin
             else:
@@ -752,14 +752,14 @@ def forest_plot(
                     (summary_ci_low, starting_location),
                     summary_ci_high-summary_ci_low, summary_ymax+1, 
                     color=summary_color, 
-                    **summary_bars_kwargs)
+                    **reference_band_kwargs)
                     )
             else:
                 ax.add_patch(mpatches.Rectangle(
                     (starting_location, summary_ci_low),
                     summary_xmax+1, summary_ci_high-summary_ci_low, 
                     color=summary_color, 
-                    **summary_bars_kwargs)
+                    **reference_band_kwargs)
                     )
 
     ## Invert Y-axis if horizontal 

dabest/misc_tools.py

@@ -385,16 +385,16 @@ def get_kwargs(
     else:
         delta_text_kwargs = merge_two_dicts(default_delta_text_kwargs, plot_kwargs["delta_text_kwargs"])
 
-    # Summary bars kwargs.
-    default_summary_bars_kwargs = {
+    # Reference band kwargs.
+    default_reference_band_kwargs = {
                     "span_ax": False,
                     "alpha": 0.15,
                     "zorder":-3
     }
-    if plot_kwargs["summary_bars_kwargs"] is None:
-        summary_bars_kwargs = default_summary_bars_kwargs
+    if plot_kwargs["reference_band_kwargs"] is None:
+        reference_band_kwargs = default_reference_band_kwargs
     else:
-        summary_bars_kwargs = merge_two_dicts(default_summary_bars_kwargs, plot_kwargs["summary_bars_kwargs"])
+        reference_band_kwargs = merge_two_dicts(default_reference_band_kwargs, plot_kwargs["reference_band_kwargs"])
 
     # Swarm bars kwargs.
     default_raw_bars_kwargs = {
@@ -501,7 +501,7 @@ def get_kwargs(
     # Return the kwargs.
     return (swarmplot_kwargs, barplot_kwargs, sankey_kwargs, contrast_kwargs, slopegraph_kwargs, 
             reflines_kwargs, legend_kwargs, group_summaries_kwargs, redraw_axes_kwargs, delta_dot_kwargs,
-            delta_text_kwargs, summary_bars_kwargs, raw_bars_kwargs, contrast_bars_kwargs, table_kwargs, gridkey_kwargs,
+            delta_text_kwargs, reference_band_kwargs, raw_bars_kwargs, contrast_bars_kwargs, table_kwargs, gridkey_kwargs,
             contrast_marker_kwargs, contrast_errorbar_kwargs, prop_sample_counts_kwargs, contrast_paired_lines_kwargs)
 
 
@@ -1880,7 +1880,7 @@ def color_picker(color_type: str,
 def prepare_bars_for_plot(bar_type, bar_kwargs, horizontal, plot_palette_raw, color_col, show_pairs,
                           plot_data = None, xvar = None, yvar = None,  # Raw data
                           results = None, ticks_to_plot = None, extra_delta = None, # Contrast data
-                          summary_bars = None, summary_axes = None, ci_type = None  # Summary data
+                          reference_band = None, summary_axes = None, ci_type = None  # Summary data
                           ):
     from .misc_tools import color_picker
     bar_dict = {}
@@ -1905,20 +1905,20 @@ def prepare_bars_for_plot(bar_type, bar_kwargs, horizontal, plot_palette_raw, co
 
     elif bar_type == 'summary':
         # Begin checks        
-        if not isinstance(summary_bars, list):
-            raise TypeError("summary_bars must be a list of indices (ints).")
-        if not all(isinstance(i, int) for i in summary_bars):
-            raise TypeError("summary_bars must be a list of indices (ints).")
-        if any(i >= len(results) for i in summary_bars):
-            raise ValueError("Index {} chosen is out of range for the contrast objects.".format([i for i in summary_bars if i >= len(results)]))
-
-        ticks = [ticks_to_plot[tick] for tick in summary_bars]
+        if not isinstance(reference_band, list):
+            raise TypeError("reference_band must be a list of indices (ints).")
+        if not all(isinstance(i, int) for i in reference_band):
+            raise TypeError("reference_band must be a list of indices (ints).")
+        if any(i >= len(results) for i in reference_band):
+            raise ValueError("Index {} chosen is out of range for the contrast objects.".format([i for i in reference_band if i >= len(results)]))
+
+        ticks = [ticks_to_plot[tick] for tick in reference_band]
         summary_xmin, summary_xmax = summary_axes.get_xlim()
         summary_ymin, summary_ymax = summary_axes.get_ylim()
         span_ax = bar_kwargs.pop("span_ax")
 
         x_start_values, y_start_values, x_distances, y_distances = [], [], [], []
-        for summary_index in summary_bars:
+        for summary_index in reference_band:
             summary_ci_low = results.get(ci_type+'_low')[summary_index]
             summary_ci_high = results.get(ci_type+'_high')[summary_index]