Merge pull request #213 from ACCLAB/v2025.10.20

v2025.10.20 Bingka

Various changes including:
- whorlmaps
- updated slopegraph aesthetics with added group summaries
- updated mini meta delta calculation
- extra custom_palette functionality

Author: JAnns98

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 <!-- do not remove -->
 
+## v2025.10.20
+
+### New Features
+1. **Whorlmap Visualization**: Introducing a new way to visualize effect sizes from multiple comparisons in a grid of whorled square cells. This design condenses information from full bootstrap distributions of an array of contrast objects into a compact visual representation. It optimizes visual real estate by presenting a clear impression of the whole dataset at a glance while retaining nuanced distributional information for further scrutiny. Whorlmaps are a space-efficient alternative to stacked forest plots when working with multi-dimensional DABEST objects from large scale experiments. 
+   
+2. **Slopegraphs have a new look**: Slopegraphs for paired continuous data now show summary statistics for each group. By default, a thick trend line connects group means, with vertical bars indicating standard deviation. Users can choose the summary type via the `group_summaries` argument in .plot() — options include `'mean_sd'`, `'median_quartiles'`, or `None`. Appearance can be customized using `group_summaries_kwargs`. See the group summaries section in the Plot Aesthetics tutorial for more details.
+   
+3. **Fixed Mini-meta Weighted Delta Calculation**: The weighted delta in mini-meta plots has been updated to ensure accurate calculation and reporting of the weighted delta.
+   
+4. **Expanded custom_palette functionality**:
+     - **Barplots (unpaired, proportional)**: The custom_palette dict can now take 0 and 1 as keys to color the filled and unfilled portions of the plots. See the custom palette section in the Plot Aesthetics tutorial for more details.
+  
+     - **Slopegraphs (paired, non proportional)**: The custom_palette can now be used to color the contrast bars and effect-size curves. See the custom palette section in the Plot Aesthetics tutorial for more details.
+
+
+
 ## v2025.03.27
 
 ### New Features

README.md

@@ -14,139 +14,66 @@ citation](https://zenodo.org/badge/DOI/10.1038/s41592-019-0470-3.svg)](https://r
 
 ## Recent Version Update
 
-We are proud to announce **DABEST Version Dadar (v2025.03.27)** This new
-version of the DABEST Python library includes several new features and
-performance improvements. It’s a big one!
-
-1.  **Python 3.13 Support**: DABEST now supports Python 3.10—3.13.
-
-2.  **Horizontal Plots**: Users can now create horizontal layout plots,
-    providing compact data visualization. This can be achieved by
-    setting `horizontal=True` in the `.plot()` method. See the
-    [Horizontal Plots
-    tutorial](https://acclab.github.io/DABEST-python/tutorials/08-horizontal_plot.html)
-    for more details.
-
-3.  **Forest Plots**: Forest plots provide a simple and intuitive way to
-    visualize many delta-delta (or delta *g*), mini-meta, or regular
-    delta effect sizes at once from multiple different dabest objects
-    without presenting the raw data. See the [Forest Plots
-    tutorial](https://acclab.github.io/DABEST-python/tutorials/07-forest_plot.html)
-    for more details.
-
-4.  **Gridkey**: Users can now represent experimental labels in a
-    ‘gridkey’ table. This can be accessed with the `gridkey` parameter
-    in the `.plot()` method. See the gridkey section in the [Plot
-    Aesthetics
-    tutorial](https://acclab.github.io/DABEST-python/tutorials/09-plot_aesthetics.html)
-    for more details.
-
-5.  **Other Visualization Improvements**:
-
-    - **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 bands as needed. For detailed
-        customization instructions, please refer to the [Plot Aesthetics
-        tutorial](https://acclab.github.io/DABEST-python/tutorials/09-plot_aesthetics.html).
-
-    - **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
-      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
-      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
-      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
-      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`
-      parameter. This dot helps make it clear where the baseline comes
-      from i.e. the control minus itself. The baseline error curve can
-      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
-      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
-      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](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
-      code, we have made several updates to the documentation and
-      terminology to improve clarity and consistency. For example:
-
-      - Plot arguments have been adjusted to bring more clarity and
-        consistency in naming. Arguments relating to the rawdata plot
-        axis will now be typically referred to with `raw` while
-        arguments relating to the contrast axis will be referred to with
-        `contrast`. For example, `raw_label` replaces `swarm_label` and
-        `bar_label`. The various kwargs relating to each different type
-        of plot (e.g., `swarmplot_kwargs`) remain unchanged.
-
-      - The method to utilise the Delta *g* effect size is now via the
-        .hedges_g.plot() method rather than creating a whole new Delta_g
-        object as before. The functionality remains the same, it plots
-        hedges_g effect sizes and then the Delta *g* effect size
-        alongside these (if a delta-delta experiment was loaded
-        correctly).
-
-    - **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 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
-      `.results` attribute of the `.delta_delta` or `.mini_meta` object.
+**✨ DABEST “Bingka” v2025.10.20 for Python is now released! ✨**
+
+Dear DABEST users, The latest version of the DABEST Python library
+brings new visualizations, refined plots, and improved accuracy.
+
+1.  **Whorlmap 🌀: Compact visualization for multi-dimensional effects**
+
+    Introducing **Whorlmap**, a new way to visualize effect sizes from
+    multiple comparisons in a compact, grid-based format.
+
+    Whorlmaps condense information from the full bootstrap distributions
+    of many contrast objects into a **2D heatmap-style grid of “whorled”
+    cells**. This provides an overview of the entire dataset while
+    preserving the underlying distributional detail.
+
+    They are especially useful for large-scale or multi-condition
+    experiments, serving as a **space-efficient alternative to stacked
+    forest plots**.
+
+    You can generate a Whorlmap directly from multi-dimensional DABEST
+    objects using the `.whorlmap()` method. See the [Whorlmap
+    tutorial](10-whorlmap.html) for more details.
+
+2.  **Slopegraphs 📈: Enhanced summaries for paired data**
+
+    Slopegraphs for paired continuous data now display **group summary
+    statistics**.
+
+    - By default, a thick trend line connects group means, with vertical
+      bars showing standard deviation.
+
+    - Choose the summary type via the group_summaries argument in
+      `.plot()` — options include `'mean_sd'`, `'median_quartiles'`, or
+      `None`.
+
+    - Customize appearance with `group_summaries_kwargs`.
+
+    See the Group Summaries section in the [Plot Aesthetics
+    tutorial](08-plot_aesthetics.html) for more details.
+
+3.  **Mini-meta Weighted Delta Fix 🧮**
+
+    The weighted delta calculation in mini-meta plots has been updated
+    for **greater accuracy and consistency**.
+
+4.  **Expanded custom_palette functionality 🎨**
+
+    - **Barplots (unpaired, proportional):** `custom_palette` can now
+      take `1` and `0` as dictionary keys to color the filled and
+      unfilled portions of the plot.
+
+    - **Slopegraphs (paired, non-proportional):** `custom_palette` can
+      now color contrast bars and effect-size curves.
+
+See the Custom Palette section in the [Plot Aesthetics
+tutorial](08-plot_aesthetics.html) for examples.
+
+Thank you for your continued support!
+
+*The DABEST Development Team*
 
 ## Contents
 

dabest/__init__.py

@@ -12,4 +12,4 @@
     if not _NUMBA_COMPILED:
         precompile_all()
 
-__version__ = "2025.03.27"
+__version__ = "2025.10.20"

dabest/_delta_objects.py

@@ -435,17 +435,19 @@ def __init__(self, effectsizedataframe, permutation_count,
                                                  self.__control_N,
                                                  self.__test_var, 
                                                  self.__test_N)
+        
+        self.__bootstraps_variance = ci2g.calculate_bootstraps_var(self.__bootstraps)
 
         # Compute the weighted average mean differences of the bootstrap data
         # using the pooled group variances of the raw data as the inverse of 
         # weights
         self.__bootstraps_weighted_delta = ci2g.calculate_weighted_delta(
-                                                          self.__group_var, 
+                                                          self.__bootstraps_variance, 
                                                           self.__bootstraps)
 
         # Compute the weighted average mean difference based on the raw data
         self.__difference = es.weighted_delta(np.array(self.__effsizedf["difference"]),
-                                                   self.__group_var)
+                                                   self.__bootstraps_variance)
 
         sorted_weighted_deltas = npsort(self.__bootstraps_weighted_delta)
 
@@ -753,6 +755,14 @@ def group_var(self):
         in order. 
         '''
         return self.__group_var
+    
+    @property
+    def bootstraps_var(self):
+        '''
+        Return the variances of each bootstrapped mean difference distribution
+        in order. 
+        '''
+        return self.__bootstraps_variance
 
 
     @property

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/_modidx.py

@@ -27,6 +27,8 @@
                                                                                                                                           'dabest/_stats_tools/confint_2group_diff.py'),
                                                          'dabest._stats_tools.confint_2group_diff.bootstrap_indices': ( 'API/confint_2group_diff.html#bootstrap_indices',
                                                                                                                         'dabest/_stats_tools/confint_2group_diff.py'),
+                                                         'dabest._stats_tools.confint_2group_diff.calculate_bootstraps_var': ( 'API/confint_2group_diff.html#calculate_bootstraps_var',
+                                                                                                                               'dabest/_stats_tools/confint_2group_diff.py'),
                                                          'dabest._stats_tools.confint_2group_diff.calculate_group_var': ( 'API/confint_2group_diff.html#calculate_group_var',
                                                                                                                           'dabest/_stats_tools/confint_2group_diff.py'),
                                                          'dabest._stats_tools.confint_2group_diff.calculate_weighted_delta': ( 'API/confint_2group_diff.html#calculate_weighted_delta',
@@ -107,6 +109,36 @@
                                                                                    'dabest/misc_tools.py'),
                                    'dabest.misc_tools.show_legend': ('API/misc_tools.html#show_legend', 'dabest/misc_tools.py'),
                                    'dabest.misc_tools.unpack_and_add': ('API/misc_tools.html#unpack_and_add', 'dabest/misc_tools.py')},
+            'dabest.multi': { 'dabest.multi.MultiContrast': ('API/multi.html#multicontrast', 'dabest/multi.py'),
+                              'dabest.multi.MultiContrast.__init__': ('API/multi.html#multicontrast.__init__', 'dabest/multi.py'),
+                              'dabest.multi.MultiContrast.__repr__': ('API/multi.html#multicontrast.__repr__', 'dabest/multi.py'),
+                              'dabest.multi.MultiContrast._extract_data': ('API/multi.html#multicontrast._extract_data', 'dabest/multi.py'),
+                              'dabest.multi.MultiContrast._extract_single_contrast': ( 'API/multi.html#multicontrast._extract_single_contrast',
+                                                                                       'dabest/multi.py'),
+                              'dabest.multi.MultiContrast._validate_and_parse_structure': ( 'API/multi.html#multicontrast._validate_and_parse_structure',
+                                                                                            'dabest/multi.py'),
+                              'dabest.multi.MultiContrast._validate_ci_type': ( 'API/multi.html#multicontrast._validate_ci_type',
+                                                                                'dabest/multi.py'),
+                              'dabest.multi.MultiContrast._validate_contrast_consistency': ( 'API/multi.html#multicontrast._validate_contrast_consistency',
+                                                                                             'dabest/multi.py'),
+                              'dabest.multi.MultiContrast._validate_effect_size': ( 'API/multi.html#multicontrast._validate_effect_size',
+                                                                                    'dabest/multi.py'),
+                              'dabest.multi.MultiContrast._validate_effect_size_compatibility': ( 'API/multi.html#multicontrast._validate_effect_size_compatibility',
+                                                                                                  'dabest/multi.py'),
+                              'dabest.multi.MultiContrast._validate_individual_dabest_obj': ( 'API/multi.html#multicontrast._validate_individual_dabest_obj',
+                                                                                              'dabest/multi.py'),
+                              'dabest.multi.MultiContrast.bootstraps': ('API/multi.html#multicontrast.bootstraps', 'dabest/multi.py'),
+                              'dabest.multi.MultiContrast.confidence_intervals': ( 'API/multi.html#multicontrast.confidence_intervals',
+                                                                                   'dabest/multi.py'),
+                              'dabest.multi.MultiContrast.effect_sizes': ('API/multi.html#multicontrast.effect_sizes', 'dabest/multi.py'),
+                              'dabest.multi.MultiContrast.forest_plot': ('API/multi.html#multicontrast.forest_plot', 'dabest/multi.py'),
+                              'dabest.multi.MultiContrast.get_bootstrap_by_position': ( 'API/multi.html#multicontrast.get_bootstrap_by_position',
+                                                                                        'dabest/multi.py'),
+                              'dabest.multi.MultiContrast.whorlmap': ('API/multi.html#multicontrast.whorlmap', 'dabest/multi.py'),
+                              'dabest.multi._sample_bootstrap': ('API/multi.html#_sample_bootstrap', 'dabest/multi.py'),
+                              'dabest.multi._spiralize': ('API/multi.html#_spiralize', 'dabest/multi.py'),
+                              'dabest.multi.combine': ('API/multi.html#combine', 'dabest/multi.py'),
+                              'dabest.multi.whorlmap': ('API/multi.html#whorlmap', 'dabest/multi.py')},
             'dabest.plot_tools': { 'dabest.plot_tools.SwarmPlot': ('API/plot_tools.html#swarmplot', 'dabest/plot_tools.py'),
                                    'dabest.plot_tools.SwarmPlot.__init__': ( 'API/plot_tools.html#swarmplot.__init__',
                                                                              'dabest/plot_tools.py'),