Merge branch 'vnbdev' of github.com:ACCLAB/DABEST-python into patch-docstring-fix

Author: Jacobluke-

dabest/_effsize_objects.py

@@ -973,6 +973,7 @@ def plot(
         contrast_ylim=None,
         delta2_ylim=None,
         swarm_side=None,
+        empty_circle=False,
         custom_palette=None,
         swarm_desat=0.5,
         halfviolin_desat=1,
@@ -1073,6 +1074,12 @@ def plot(
             https://seaborn.pydata.org/generated/seaborn.cubehelix_palette.html
             The named colors of matplotlib can be found here:
             https://matplotlib.org/examples/color/named_colors.html
+        swarm_side: string, default None
+            The side on which points are swarmed for swarmplots ("center", "left", or "right").
+        empty_circle: boolean, default False
+            Boolean value determining if empty circles will be used for plotting of
+            swarmplot for control groups. Color of each individual swarm is also now
+            dependent on the comparison group.
         swarm_desat : float, default 1
             Decreases the saturation of the colors in the swarmplot by the
             desired proportion. Uses `seaborn.desaturate()` to acheive this.
@@ -1221,7 +1228,7 @@ def plot(
         if hasattr(self, "results") is False:
             self.__pre_calc()
 
-        if self.__delta2:
+        if self.__delta2 and not empty_circle:
             color_col = self.__x2
 
         # if self.__proportional:

dabest/_modidx.py

@@ -64,7 +64,9 @@
             'dabest.forest_plot': { 'dabest.forest_plot.extract_plot_data': ( 'API/forest_plot.html#extract_plot_data',
                                                                               'dabest/forest_plot.py'),
                                     'dabest.forest_plot.forest_plot': ('API/forest_plot.html#forest_plot', 'dabest/forest_plot.py'),
-                                    'dabest.forest_plot.load_plot_data': ('API/forest_plot.html#load_plot_data', 'dabest/forest_plot.py')},
+                                    'dabest.forest_plot.load_plot_data': ('API/forest_plot.html#load_plot_data', 'dabest/forest_plot.py'),
+                                    'dabest.forest_plot.map_effect_attribute': ( 'API/forest_plot.html#map_effect_attribute',
+                                                                                 'dabest/forest_plot.py')},
             'dabest.misc_tools': { 'dabest.misc_tools.Cumming_Plot_Aesthetic_Adjustments': ( 'API/misc_tools.html#cumming_plot_aesthetic_adjustments',
                                                                                              'dabest/misc_tools.py'),
                                    'dabest.misc_tools.Gardner_Altman_Plot_Aesthetic_Adjustments': ( 'API/misc_tools.html#gardner_altman_plot_aesthetic_adjustments',

dabest/forest_plot.py

@@ -3,7 +3,7 @@
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/API/forest_plot.ipynb.
 
 # %% auto 0
-__all__ = ['load_plot_data', 'extract_plot_data', 'forest_plot']
+__all__ = ['load_plot_data', 'extract_plot_data', 'map_effect_attribute', 'forest_plot']
 
 # %% ../nbs/API/forest_plot.ipynb 5
 import matplotlib.pyplot as plt
@@ -74,28 +74,42 @@ def extract_plot_data(contrast_plot_data, contrast_type):
 
     return bootstraps, differences, bcalows, bcahighs
 
+def map_effect_attribute(attribute_key):
+    # Check if the attribute key exists in the dictionary
+    effect_attr_map = {
+        "mean_diff": "Mean Difference",
+        "median_diff": "Median Difference",
+        "cliffs_delta": "Cliffs Delta",
+        "cohens_d": "Cohens d",
+        "hedges_g": "Hedges g",
+        "delta_g": "Delta g"
+    }
+    if attribute_key in effect_attr_map:
+        return effect_attr_map[attribute_key]
+    else:
+        raise TypeError("The `effect_size` argument must be a string. Please choose from the following effect sizes: `mean_diff`,`median_diff`,`cliffs_delta`,`cohens_d``, and `hedges_g`.")  # Return a default value or message if the key is not found
 
 def forest_plot(
     contrasts: List,
     selected_indices: Optional[List] = None,
     contrast_type: str = "delta2",
-    xticklabels: Optional[List] = None,
     effect_size: str = "mean_diff",
     contrast_labels: List[str] = None,
-    ylabel: str = "value",
+    ylabel: str = "effect size",
     plot_elements_to_extract: Optional[List] = None,
     title: str = "ΔΔ Forest",
     custom_palette: Optional[Union[dict, list, str]] = None,
-    fontsize: int = 20,
+    fontsize: int = 12,
+    title_font_size: int =16,
     violin_kwargs: Optional[dict] = None,
     marker_size: int = 20,
     ci_line_width: float = 2.5,
-    zero_line_width: int = 1,
+    desat_violin: float = 1,
     remove_spines: bool = True,
     ax: Optional[plt.Axes] = None,
     additional_plotting_kwargs: Optional[dict] = None,
     rotation_for_xlabels: int = 45,
-    alpha_violin_plot: float = 0.4,
+    alpha_violin_plot: float = 0.8,
     horizontal: bool = False  # New argument for horizontal orientation
 )-> plt.Figure:
     """  
@@ -108,11 +122,9 @@ def forest_plot(
     selected_indices : Optional[List], default=None
         Indices of specific contrasts to plot, if not plotting all.
     analysis_type : str
-         the type of analysis (e.g., 'delta2', 'minimeta').
-    xticklabels : Optional[List], default=None
-        Custom labels for the x-axis ticks.
+         the type of analysis (e.g., 'delta2', 'mini_meta').
     effect_size : str
-        Type of effect size to plot (e.g., 'mean_diff', 'median_diff').
+        Type of effect size to plot (e.g., 'mean_diff', 'median_diff', `cliffs_delta`,`cohens_d``, and `hedges_g`).
     contrast_labels : List[str]
         Labels for each contrast.
     ylabel : str
@@ -127,14 +139,14 @@ def forest_plot(
         Custom color palette for the plot.
     fontsize : int
         Font size for text elements in the plot.
+    title_font_size: int =16
+        Font size for text of plot title.
     violin_kwargs : Optional[dict], default=None
         Additional arguments for violin plot customization.
     marker_size : int
         Marker size for plotting mean differences or effect sizes.
     ci_line_width : float
         Width of confidence interval lines.
-    zero_line_width : int
-        Width of the line indicating zero effect size.
     remove_spines : bool, default=False
         If True, removes top and right plot spines.
     ax : Optional[plt.Axes], default=None
@@ -163,14 +175,13 @@ def forest_plot(
     if selected_indices is not None and not isinstance(selected_indices, (list, type(None))):
         raise TypeError("The `selected_indices` must be a list of integers or `None`.")
 
+    # For the 'contrast_type' parameter
     if not isinstance(contrast_type, str):
-        raise TypeError("The `contrast_type` argument must be a string.")
-    
-    if xticklabels is not None and not all(isinstance(label, str) for label in xticklabels):
-        raise TypeError("The `xticklabels` must be a list of strings or `None`.")
-    
+        raise TypeError("The `contrast_type` argument must be a string. Please choose from `delta2` and `mini_meta`.")
+
+    # For the 'effect_size' parameter
     if not isinstance(effect_size, str):
-        raise TypeError("The `effect_size` argument must be a string.")
+        raise TypeError("The `effect_size` argument must be a string. Please choose from the following effect sizes: `mean_diff`, `median_diff`, `cliffs_delta`, `cohens_d`, and `hedges_g`.")
 
     if contrast_labels is not None and not all(isinstance(label, str) for label in contrast_labels):
         raise TypeError("The `contrast_labels` must be a list of strings or `None`.")
@@ -193,9 +204,6 @@ def forest_plot(
     if not isinstance(ci_line_width, (int, float)) or ci_line_width <= 0:
         raise TypeError("`ci_line_width` must be a positive integer or float.")
 
-    if not isinstance(zero_line_width, (int, float)) or zero_line_width <= 0:
-        raise TypeError("`zero_line_width` must be a positive integer or float.")
-    
     if not isinstance(remove_spines, bool):
         raise TypeError("`remove_spines` must be a boolean value.")
 
@@ -211,6 +219,8 @@ def forest_plot(
     if not isinstance(horizontal, bool):
         raise TypeError("`horizontal` must be a boolean value.")
 
+    if (effect_size and isinstance(effect_size, str)):
+        ylabel = map_effect_attribute(effect_size)
     # Load plot data
     contrast_plot_data = load_plot_data(contrasts, effect_size, contrast_type)
 
@@ -252,7 +262,7 @@ def forest_plot(
     if custom_palette:
         if isinstance(custom_palette, dict):
             violin_colors = [
-                custom_palette.get(c, sns.color_palette()[0]) for c in contrasts
+                custom_palette.get(c, sns.color_palette()[0]) for c in contrast_labels
             ]
         elif isinstance(custom_palette, list):
             violin_colors = custom_palette[: len(contrasts)]
@@ -264,12 +274,18 @@ def forest_plot(
                     f"The specified `custom_palette` {custom_palette} is not a recognized Matplotlib palette."
                 )
     else:
-        violin_colors = sns.color_palette()[: len(contrasts)]
+        violin_colors = sns.color_palette(n_colors=len(contrasts))
 
+    violin_colors = [sns.desaturate(color, desat_violin) for color in violin_colors]
+    
     for patch, color in zip(v["bodies"], violin_colors):
         patch.set_facecolor(color)
         patch.set_alpha(alpha_violin_plot)
-
+    if horizontal:
+        ax.plot([0, 0], [0, len(contrasts)+1], 'k', linewidth = 1)
+    else:
+        ax.plot([0, len(contrasts)+1], [0, 0], 'k', linewidth = 1)
+    
     # Flipping the axes for plotting based on 'horizontal'
     for k in range(1, len(contrasts) + 1):
         if horizontal:
@@ -282,19 +298,26 @@ def forest_plot(
     # Adjusting labels, ticks, and limits based on 'horizontal'
     if horizontal:
         ax.set_yticks(range(1, len(contrasts) + 1))
-        ax.set_yticklabels(contrast_labels,  rotation=rotation_for_xlabels, fontsize=fontsize)
+        ax.set_yticklabels(contrast_labels,  rotation=0, fontsize=fontsize)
         ax.set_xlabel(ylabel, fontsize=fontsize)
+        ax.set_ylim([0.7, len(contrasts) + 0.5])
     else:
         ax.set_xticks(range(1, len(contrasts) + 1))
         ax.set_xticklabels(contrast_labels, rotation=rotation_for_xlabels, fontsize=fontsize)
         ax.set_ylabel(ylabel, fontsize=fontsize)
+        ax.set_xlim([0.7, len(contrasts) + 0.5])
 
     # Setting the title and adjusting spines as before
-    ax.set_title(title, fontsize=fontsize)
+    ax.set_title(title, fontsize=title_font_size)
     if remove_spines:
-        for spine in ax.spines.values():
-            spine.set_visible(False)
-
+        if horizontal:
+            ax.spines['left'].set_visible(False)
+            ax.spines['right'].set_visible(False)
+            ax.spines['top'].set_visible(False)
+        else:
+            ax.spines['top'].set_visible(False)
+            ax.spines['bottom'].set_visible(False)
+            ax.spines['right'].set_visible(False)
     # Apply additional customizations if provided
     if additional_plotting_kwargs:
         ax.set(**additional_plotting_kwargs)