Merge v2025.03.27 into master branch

.github/workflows/test-pytest.yaml

@@ -8,7 +8,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v4
         with:
-          python-version: 3.8
+          python-version: 3.11
           cache: "pip"
           cache-dependency-path: settings.ini
       - name: Run pytest

.gitignore

@@ -5,6 +5,7 @@ _proc/
 .gitattributes
 .last_checked
 .gitconfig
+.cursorignore
 *.bak
 *.log
 *~

CHANGELOG.md

@@ -2,6 +2,49 @@
 
 <!-- do not remove -->
 
+## v2025.03.27
+
+### New Features
+
+- **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.
+
+- **Forest Plots**: Forest plots provide a simple and intuitive way to visualize many delta-delta (or Deltas’ g), mini-meta, or regular delta effect sizes at once from multiple different dabest objects without presenting the raw data.
+
+- **Gridkey**: Users can now represent their experimental labels in a gridkey format. This can be accessed with the `gridkey` argument in the `plot()` method. 
+
+- **Aesthetic Updates**: We have made several aesthetic improvements to the plots, including:
+   - **Raw, Contrast, and Summary bars**: We added bars highlighting the various groups' differences. These bars can be customized to suit the user’s needs. Raw and contrast bars are provided by default, summary bars can be added by the user.
+
+   - **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 added effect size closer to the regular effect sizes. In addition, delta-delta plots now have a gap in the zeroline to separate the delta-delta and regular effect sizes.
+
+   - **Delta-delta Effect Sizes for Proportion Plots**: Delta-delta experimental plotting now supports binary data.
+
+   - **Proportion Plots Sample Sizes**: The sample size of each binary option for each group can now be displayed. These can be toggled on or off via the `prop_sample_counts` parameter.
+
+   - **Effect Size Lines for Paired Plots**: Paired plots now display lines linking the effect sizes within a group together in the contrast axes. These can be toggled on or off via the `contrast_paired_lines` parameter.
+
+   - **Baseline Error Curves**: Baseline error dot and curve are now available to represent the baseline/control group in the contrast axes. The dot is shown by default, while the curve can be toggled on/off by the user (via the `show_baseline_ec` parameter).
+
+   - **Delta Text**: Effect size deltas are now displayed as text next to their respective effect size. This can be toggled on or 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.
+
+### Enhancement
+
+- **Python 3.13 Support**: DABEST now supports Python 3.10-3.13.
+
+- **Numba for Speed Improvements**: We have included Numba to speed up the various calculations in DABEST. This should make the calculations faster and more efficient. Importing DABEST may take a little longer than before, and a progress bar will appear during the import process to show the calculations being performed. Once imported, loading and plotting data should now be faster.
+
+- **Terminology Updates**: 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 Deltas’ 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 Deltas’ 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.
+
+
+
 ## v2024.03.29
 
 ### New Features

README.md

@@ -1,9 +1,10 @@
 # DABEST-Python
 
+
 <!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
 
 [![minimal Python
-version](https://img.shields.io/badge/Python%3E%3D-3.8-6666ff.svg)](https://www.anaconda.com/distribution/)
+version](https://img.shields.io/badge/Python%3E%3D-3.10-6666ff.svg)](https://www.anaconda.com/distribution/)
 [![PyPI
 version](https://badge.fury.io/py/dabest.svg)](https://badge.fury.io/py/dabest)
 [![Downloads](https://img.shields.io/pepy/dt/dabest.svg)](https://pepy.tech/project/dabest)
@@ -13,37 +14,139 @@ 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 Ondeh (v2024.03.29)**. This
-new version of the DABEST Python library provides several new features
-and includes performance improvements.
-
-1.  **New Paired Proportion Plot**: This feature builds upon the
-    existing proportional analysis capabilities by introducing advanced
-    aesthetics and clearer visualization of changes in proportions
-    between different groups, inspired by the informative nature of
-    Sankey Diagrams. It’s particularly useful for studies that require
-    detailed examination of how proportions shift in paired
-    observations.
-
-2.  **Customizable Swarm Plot**: Enhancements allow for tailored swarm
-    plot aesthetics, notably the adjustment of swarm sides to produce
-    asymmetric swarm plots. This customization enhances data
-    representation, making visual distinctions more pronounced and
-    interpretations clearer.
-
-3.  **Standardized Delta-delta Effect Size**: We added a new metric akin
-    to a Hedges’ g for delta-delta effect size, which allows comparisons
-    between delta-delta effects generated from metrics with different
-    units.
-
-4.  **Miscellaneous Improvements**: This version also encompasses a
-    broad range of miscellaneous enhancements, including bug fixes,
-    Bootstrapping speed improvements, new templates for raising issues,
-    and updated unit tests. These improvements are designed to
-    streamline the user experience, increase the software’s stability,
-    and expand its versatility. By addressing user feedback and
-    identified issues, DABEST continues to refine its functionality and
-    reliability.
+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.
 
 ## Contents
 
@@ -91,7 +194,7 @@ allowing everyone access to high-quality estimation plots.
 
 ## Installation
 
-This package is tested on Python 3.8 and onwards. It is highly
+This package is tested on Python 3.11 and onwards. It is highly
 recommended to download the [Anaconda
 distribution](https://www.continuum.io/downloads) of Python in order to
 obtain the dependencies easily.
@@ -160,17 +263,17 @@ page](https://github.com/ACCLAB/DABEST-python/issues/new).
 ## Contributing
 
 All contributions are welcome; please read the [Guidelines for
-contributing](CONTRIBUTING.md) first.
+contributing](../CONTRIBUTING.md) first.
 
-We also have a [Code of Conduct](CODE_OF_CONDUCT.md) to foster an
+We also have a [Code of Conduct](../CODE_OF_CONDUCT.md) to foster an
 inclusive and productive space.
 
 ### A wish list for new features
 
 If you have any specific comments and ideas for new features that you
 would like to share with us, please read the [Guidelines for
-contributing](CONTRIBUTING.md), create a new issue using Feature request
-template or create a new post in [our Google
+contributing](../CONTRIBUTING.md), create a new issue using Feature
+request template or create a new post in [our Google
 Group](https://groups.google.com/g/estimationstats).
 
 ## Acknowledgements
@@ -197,7 +300,7 @@ The test suite ensures that the bootstrapping functions and the plotting
 functions perform as expected.
 
 For detailed information, please refer to the [test
-folder](nbs/tests/README.md)
+folder](../nbs/tests/README.md)
 
 ## DABEST in other languages
 

dabest/__init__.py

@@ -1,6 +1,15 @@
 from ._api import load, prop_dataset
 from ._stats_tools import effsize as effsize
+from ._stats_tools import confint_2group_diff as ci_2g
 from ._effsize_objects import TwoGroupsEffectSize, PermutationTest
 from ._dabest_object import Dabest
+from .forest_plot import forest_plot
 
-__version__ = "2024.03.29"
+
+import os
+if os.environ.get('SKIP_NUMBA_COMPILE') != '1':
+    from ._stats_tools.precompile import precompile_all, _NUMBA_COMPILED
+    if not _NUMBA_COMPILED:
+        precompile_all()
+
+__version__ = "2025.03.27"

dabest/_api.py

@@ -1,3 +1,5 @@
+"""Loading data and relevant groups"""
+
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/API/load.ipynb.
 
 # %% auto 0
@@ -20,6 +22,7 @@ def load(
     experiment_label=None,
     x1_level=None,
     mini_meta=False,
+    ps_adjust=False,
 ):
     """
     Loads data in preparation for estimation statistics.
@@ -80,6 +83,9 @@ def load(
         is True; otherwise it can only be a string.
     mini_meta : boolean, default False
         Indicator of weighted delta calculation.
+    ps_adjust : boolean, default False
+        Indicator of whether to adjust calculated p-value according to Phipson & Smyth (2010)
+        # https://doi.org/10.2202/1544-6115.1585
 
     Returns
     -------
@@ -103,6 +109,7 @@ def load(
         experiment_label,
         x1_level,
         mini_meta,
+        ps_adjust,
     )
 
 # %% ../nbs/API/load.ipynb 5

dabest/_bootstrap_tools.py

@@ -66,7 +66,9 @@ def __init__(
         reps: int = 5000,  # Number of bootstrap iterations to perform.
     ):
         # Turn to pandas series.
-        x1 = pd.Series(x1).dropna()
+        # x1 = pd.Series(x1).dropna()
+        x1 = x1[~np.isnan(x1)]
+
         diff = False
 
         # Initialise stat_function
@@ -89,7 +91,9 @@ def __init__(
             if x2 is None:
                 raise ValueError("Please specify x2.")
 
-            x2 = pd.Series(x2).dropna()
+            # x2 = pd.Series(x2).dropna()
+            x2 = x1[~np.isnan(x2)]
+
             if len(x1) != len(x2):
                 raise ValueError("x1 and x2 are not the same length.")
 
@@ -134,7 +138,8 @@ def __init__(
 
         elif x2 is not None and paired is None:
             diff = True
-            x2 = pd.Series(x2).dropna()
+            # x2 = pd.Series(x2).dropna()
+            x2 = x2[~np.isnan(x2)]
             # Generate statarrays for both arrays.
             ref_statarray = sns.algorithms.bootstrap(x1, **sns_bootstrap_kwargs)
             exp_statarray = sns.algorithms.bootstrap(x2, **sns_bootstrap_kwargs)