Added more error checking for forest plot

Author: JAnns98

dabest/forest_plot.py

@@ -127,8 +127,8 @@ def check_for_errors(
                 horizontal,
                 marker_size,
                 custom_palette,
-                halfviolin_alpha,
-                halfviolin_desat,
+                contrast_alpha,
+                contrast_desat,
                 labels,
                 labels_rotation,
                 labels_fontsize,
@@ -166,8 +166,26 @@ def check_for_errors(
     if idx is not None:
         if not isinstance(idx, (tuple, list)):
             raise TypeError("`idx` must be a tuple or list of integers.")
-        # if contrast_type == "mini_meta":
-        #     raise ValueError("The `idx` argument is not applicable to mini-meta analyses.")
+
+        msg1 = "The `idx` argument must have the same length as the number of dabest objects. "
+        msg2 = "E.g., If two dabest objects are supplied, there should be two lists within `idx`. "
+        msg3 = "E.g., `idx` = [[1,2],[0,1]]."
+        _total = 0
+        for _group in idx:
+            if isinstance(_group, int | float):
+                raise ValueError(msg1+msg2+msg3)
+            else:
+                _total += 1
+        if _total != len(data):
+            raise ValueError(msg1+msg2+msg3)
+        
+    if idx is not None:
+        number_of_curves_to_plot = sum([len(i) for i in idx])
+    else:
+        if contrast_type == 'delta':
+            number_of_curves_to_plot = sum(len(getattr(i, effect_size).results) for i in data)
+        else:
+            number_of_curves_to_plot = len(data)
 
     # Axes
     if ax is not None and not isinstance(ax, plt.Axes):
@@ -195,25 +213,26 @@ def check_for_errors(
         raise TypeError("`marker_size` must be a positive integer or float.")
 
     # Custom palette
-    if custom_palette is not None and not isinstance(custom_palette, (dict, list, str, type(None))):
+    if custom_palette is not None and not isinstance(custom_palette, (dict, list, tuple, str, type(None))):
         raise TypeError("The `custom_palette` must be either a dictionary, list, string, or `None`.")
     if isinstance(custom_palette, dict) and labels is None:
         raise ValueError("The `labels` argument must be provided if `custom_palette` is a dictionary.")
+    if isinstance(custom_palette, (list, tuple)) and len(custom_palette) < number_of_curves_to_plot:
+        raise ValueError("The `custom_palette` list/tuple must have the same length as the number of `data` provided.")
 
-
-    # Halfviolin alpha and desat
-    if not isinstance(halfviolin_alpha, float) or not 0 <= halfviolin_alpha <= 1:
-        raise TypeError("`halfviolin_alpha` must be a float between 0 and 1.")
+    # Contrast alpha and desat
+    if not isinstance(contrast_alpha, float) or not 0 <= contrast_alpha <= 1:
+        raise TypeError("`contrast_alpha` must be a float between 0 and 1.")
 
-    if not isinstance(halfviolin_desat, (float, int)) or not 0 <= halfviolin_desat <= 1:
-        raise TypeError("`halfviolin_desat` must be a float between 0 and 1 or an int (1).")
+    if not isinstance(contrast_desat, (float, int)) or not 0 <= contrast_desat <= 1:
+        raise TypeError("`contrast_desat` must be a float between 0 and 1 or an int (1).")
 
 
     # Contrast labels
     if labels is not None and not all(isinstance(label, str) for label in labels):
         raise TypeError("The `labels` must be a list of strings or `None`.")
 
-    number_of_curves_to_plot = sum([len(i) for i in idx]) if idx is not None else len(data)
+    
     if labels is not None and len(labels) != number_of_curves_to_plot:
         raise ValueError("`labels` must match the number of `data` provided.")
 
@@ -360,7 +379,7 @@ def color_palette(
         custom_palette, 
         labels, 
         number_of_curves_to_plot,
-        halfviolin_desat
+        contrast_desat
     ):
     if custom_palette is not None:
         if isinstance(custom_palette, dict):
@@ -378,7 +397,7 @@ def color_palette(
                 )
     else:
         violin_colors = sns.color_palette(n_colors=number_of_curves_to_plot)
-    violin_colors = [sns.desaturate(color, halfviolin_desat) for color in violin_colors]
+    violin_colors = [sns.desaturate(color, contrast_desat) for color in violin_colors]
     return violin_colors
 
 
@@ -392,8 +411,8 @@ def forest_plot(
 
     marker_size: int = 10,
     custom_palette: Optional[Union[dict, list, str]] = None,
-    halfviolin_alpha: float = 0.8,
-    halfviolin_desat: float = 1,
+    contrast_alpha: float = 0.8,
+    contrast_desat: float = 1,
 
     labels: list[str] = None,
     labels_rotation: int = None,
@@ -442,9 +461,9 @@ def forest_plot(
         Marker size for plotting effect size dots.
     custom_palette : Optional[Union[dict, list, str]], default=None
         Custom color palette for the plot.
-    halfviolin_alpha : float, default=0.8
+    contrast_alpha : float, default=0.8
         Transparency level for violin plots.
-    halfviolin_desat : float, default=1
+    contrast_desat : float, default=1
         Saturation level for violin plots.
     labels : List[str]
         Labels for each contrast. If None, defaults to 'Contrast 1', 'Contrast 2', etc.
@@ -468,9 +487,14 @@ def forest_plot(
         Custom y-tick labels for the plot.
     remove_spines : bool, default=True
         If True, removes plot spines (except the relevant dependent variable spine).
-
-
-
+    delta_text : bool, default=True
+        If True, it adds text next to each curve representing the effect size value.
+    delta_text_kwargs : dict, default=None
+        Additional keyword arguments for the delta_text.
+    contrast_bars : bool, default=True
+        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.
     violin_kwargs : Optional[dict], default=None
         Additional arguments for violin plot customization.
     zeroline_kwargs : Optional[dict], default=None
@@ -498,8 +522,8 @@ def forest_plot(
                             horizontal = horizontal,
                             marker_size = marker_size,
                             custom_palette = custom_palette,
-                            halfviolin_alpha = halfviolin_alpha,
-                            halfviolin_desat = halfviolin_desat,
+                            contrast_alpha = contrast_alpha,
+                            contrast_desat = contrast_desat,
                             labels = labels,
                             labels_rotation = labels_rotation,
                             labels_fontsize = labels_fontsize,
@@ -551,7 +575,7 @@ def forest_plot(
     )
     halfviolin(
             v, 
-            alpha = halfviolin_alpha, 
+            alpha = contrast_alpha, 
             half = "bottom" if horizontal else "right",
         )
 
@@ -570,7 +594,7 @@ def forest_plot(
                         custom_palette = custom_palette, 
                         labels = labels, 
                         number_of_curves_to_plot = number_of_curves_to_plot,
-                        halfviolin_desat = halfviolin_desat
+                        contrast_desat = contrast_desat
                     )
 
     for patch, color in zip(v["bodies"], violin_colors):

nbs/API/forest_plot.ipynb

@@ -187,8 +187,8 @@
     "                horizontal,\n",
     "                marker_size,\n",
     "                custom_palette,\n",
-    "                halfviolin_alpha,\n",
-    "                halfviolin_desat,\n",
+    "                contrast_alpha,\n",
+    "                contrast_desat,\n",
     "                labels,\n",
     "                labels_rotation,\n",
     "                labels_fontsize,\n",
@@ -226,8 +226,26 @@
     "    if idx is not None:\n",
     "        if not isinstance(idx, (tuple, list)):\n",
     "            raise TypeError(\"`idx` must be a tuple or list of integers.\")\n",
-    "        # if contrast_type == \"mini_meta\":\n",
-    "        #     raise ValueError(\"The `idx` argument is not applicable to mini-meta analyses.\")\n",
+    "\n",
+    "        msg1 = \"The `idx` argument must have the same length as the number of dabest objects. \"\n",
+    "        msg2 = \"E.g., If two dabest objects are supplied, there should be two lists within `idx`. \"\n",
+    "        msg3 = \"E.g., `idx` = [[1,2],[0,1]].\"\n",
+    "        _total = 0\n",
+    "        for _group in idx:\n",
+    "            if isinstance(_group, int | float):\n",
+    "                raise ValueError(msg1+msg2+msg3)\n",
+    "            else:\n",
+    "                _total += 1\n",
+    "        if _total != len(data):\n",
+    "            raise ValueError(msg1+msg2+msg3)\n",
+    "        \n",
+    "    if idx is not None:\n",
+    "        number_of_curves_to_plot = sum([len(i) for i in idx])\n",
+    "    else:\n",
+    "        if contrast_type == 'delta':\n",
+    "            number_of_curves_to_plot = sum(len(getattr(i, effect_size).results) for i in data)\n",
+    "        else:\n",
+    "            number_of_curves_to_plot = len(data)\n",
     "\n",
     "    # Axes\n",
     "    if ax is not None and not isinstance(ax, plt.Axes):\n",
@@ -255,25 +273,26 @@
     "        raise TypeError(\"`marker_size` must be a positive integer or float.\")\n",
     "\n",
     "    # Custom palette\n",
-    "    if custom_palette is not None and not isinstance(custom_palette, (dict, list, str, type(None))):\n",
+    "    if custom_palette is not None and not isinstance(custom_palette, (dict, list, tuple, str, type(None))):\n",
     "        raise TypeError(\"The `custom_palette` must be either a dictionary, list, string, or `None`.\")\n",
     "    if isinstance(custom_palette, dict) and labels is None:\n",
     "        raise ValueError(\"The `labels` argument must be provided if `custom_palette` is a dictionary.\")\n",
+    "    if isinstance(custom_palette, (list, tuple)) and len(custom_palette) < number_of_curves_to_plot:\n",
+    "        raise ValueError(\"The `custom_palette` list/tuple must have the same length as the number of `data` provided.\")\n",
     "\n",
-    "\n",
-    "    # Halfviolin alpha and desat\n",
-    "    if not isinstance(halfviolin_alpha, float) or not 0 <= halfviolin_alpha <= 1:\n",
-    "        raise TypeError(\"`halfviolin_alpha` must be a float between 0 and 1.\")\n",
+    "    # Contrast alpha and desat\n",
+    "    if not isinstance(contrast_alpha, float) or not 0 <= contrast_alpha <= 1:\n",
+    "        raise TypeError(\"`contrast_alpha` must be a float between 0 and 1.\")\n",
     "    \n",
-    "    if not isinstance(halfviolin_desat, (float, int)) or not 0 <= halfviolin_desat <= 1:\n",
-    "        raise TypeError(\"`halfviolin_desat` must be a float between 0 and 1 or an int (1).\")\n",
+    "    if not isinstance(contrast_desat, (float, int)) or not 0 <= contrast_desat <= 1:\n",
+    "        raise TypeError(\"`contrast_desat` must be a float between 0 and 1 or an int (1).\")\n",
     "    \n",
     "\n",
     "    # Contrast labels\n",
     "    if labels is not None and not all(isinstance(label, str) for label in labels):\n",
     "        raise TypeError(\"The `labels` must be a list of strings or `None`.\")\n",
     "    \n",
-    "    number_of_curves_to_plot = sum([len(i) for i in idx]) if idx is not None else len(data)\n",
+    "    \n",
     "    if labels is not None and len(labels) != number_of_curves_to_plot:\n",
     "        raise ValueError(\"`labels` must match the number of `data` provided.\")\n",
     "    \n",
@@ -420,7 +439,7 @@
     "        custom_palette, \n",
     "        labels, \n",
     "        number_of_curves_to_plot,\n",
-    "        halfviolin_desat\n",
+    "        contrast_desat\n",
     "    ):\n",
     "    if custom_palette is not None:\n",
     "        if isinstance(custom_palette, dict):\n",
@@ -438,7 +457,7 @@
     "                )\n",
     "    else:\n",
     "        violin_colors = sns.color_palette(n_colors=number_of_curves_to_plot)\n",
-    "    violin_colors = [sns.desaturate(color, halfviolin_desat) for color in violin_colors]\n",
+    "    violin_colors = [sns.desaturate(color, contrast_desat) for color in violin_colors]\n",
     "    return violin_colors\n",
     "\n",
     "\n",
@@ -452,8 +471,8 @@
     "\n",
     "    marker_size: int = 10,\n",
     "    custom_palette: Optional[Union[dict, list, str]] = None,\n",
-    "    halfviolin_alpha: float = 0.8,\n",
-    "    halfviolin_desat: float = 1,\n",
+    "    contrast_alpha: float = 0.8,\n",
+    "    contrast_desat: float = 1,\n",
     "\n",
     "    labels: list[str] = None,\n",
     "    labels_rotation: int = None,\n",
@@ -502,9 +521,9 @@
     "        Marker size for plotting effect size dots.\n",
     "    custom_palette : Optional[Union[dict, list, str]], default=None\n",
     "        Custom color palette for the plot.\n",
-    "    halfviolin_alpha : float, default=0.8\n",
+    "    contrast_alpha : float, default=0.8\n",
     "        Transparency level for violin plots.\n",
-    "    halfviolin_desat : float, default=1\n",
+    "    contrast_desat : float, default=1\n",
     "        Saturation level for violin plots.\n",
     "    labels : List[str]\n",
     "        Labels for each contrast. If None, defaults to 'Contrast 1', 'Contrast 2', etc.\n",
@@ -528,9 +547,14 @@
     "        Custom y-tick labels for the plot.\n",
     "    remove_spines : bool, default=True\n",
     "        If True, removes plot spines (except the relevant dependent variable spine).\n",
-    "\n",
-    "\n",
-    "\n",
+    "    delta_text : bool, default=True\n",
+    "        If True, it adds text next to each curve representing the effect size value.\n",
+    "    delta_text_kwargs : dict, default=None\n",
+    "        Additional keyword arguments for the delta_text.\n",
+    "    contrast_bars : bool, default=True\n",
+    "        If True, it adds bars from the zeroline to the effect size curve.\n",
+    "    contrast_bars_kwargs : dict, default=None\n",
+    "        Additional keyword arguments for the contrast_bars.\n",
     "    violin_kwargs : Optional[dict], default=None\n",
     "        Additional arguments for violin plot customization.\n",
     "    zeroline_kwargs : Optional[dict], default=None\n",
@@ -558,8 +582,8 @@
     "                            horizontal = horizontal,\n",
     "                            marker_size = marker_size,\n",
     "                            custom_palette = custom_palette,\n",
-    "                            halfviolin_alpha = halfviolin_alpha,\n",
-    "                            halfviolin_desat = halfviolin_desat,\n",
+    "                            contrast_alpha = contrast_alpha,\n",
+    "                            contrast_desat = contrast_desat,\n",
     "                            labels = labels,\n",
     "                            labels_rotation = labels_rotation,\n",
     "                            labels_fontsize = labels_fontsize,\n",
@@ -611,7 +635,7 @@
     "    )\n",
     "    halfviolin(\n",
     "            v, \n",
-    "            alpha = halfviolin_alpha, \n",
+    "            alpha = contrast_alpha, \n",
     "            half = \"bottom\" if horizontal else \"right\",\n",
     "        )\n",
     "    \n",
@@ -630,7 +654,7 @@
     "                        custom_palette = custom_palette, \n",
     "                        labels = labels, \n",
     "                        number_of_curves_to_plot = number_of_curves_to_plot,\n",
-    "                        halfviolin_desat = halfviolin_desat\n",
+    "                        contrast_desat = contrast_desat\n",
     "                    )\n",
     "    \n",
     "    for patch, color in zip(v[\"bodies\"], violin_colors):\n",

nbs/tests/data/mocked_data_test_forestplot.py

@@ -48,7 +48,7 @@
     "marker_size": 20,  # Ensure it's a positive integer or float.
     "remove_spines": True,  # Ensure it's a boolean.
     "labels_rotation": 45,  # Ensure it's an integer or float between 0 and 360.
-    "halfviolin_alpha": 0.8,  # Ensure it's a float between 0 and 1.
+    "contrast_alpha": 0.8,  # Ensure it's a float between 0 and 1.
     "horizontal": False,  # Ensure it's a boolean.
 }
 

nbs/tests/mpl_image_tests/test_05_forest_plot.py

@@ -280,8 +280,8 @@ def test_509_deltadelta_halfviolin_aesthetics_forest():
     return forest_plot(
                 contrasts, 
                 labels=['Drug1', 'Drug2', 'Drug3'],
-                halfviolin_alpha=0.2,
-                halfviolin_desat=0.2
+                contrast_alpha=0.2,
+                contrast_desat=0.2
             )
 
 

nbs/tests/test_forest_plot.py

@@ -20,8 +20,8 @@ def test_forest_plot_no_input_parameters():
     ("horizontal", "sideways", "`horizontal` must be a boolean value.", TypeError),
     ("marker_size", "large", "`marker_size` must be a positive integer or float.", TypeError),
     ("custom_palette", 123, "The `custom_palette` must be either a dictionary, list, string, or `None`.", TypeError),
-    ("halfviolin_alpha", "opaque", "`halfviolin_alpha` must be a float between 0 and 1.", TypeError),
-    ("halfviolin_desat", "yes", "`halfviolin_desat` must be a float between 0 and 1 or an int (1).", TypeError),
+    ("contrast_alpha", "opaque", "`contrast_alpha` must be a float between 0 and 1.", TypeError),
+    ("contrast_desat", "yes", "`contrast_desat` must be a float between 0 and 1 or an int (1).", TypeError),
     ("labels", ["valid", 123], "The `labels` must be a list of strings or `None`.", TypeError),
     ("labels", ['valid', 'valid'], "`labels` must match the number of `data` provided.", ValueError),
     ("labels_fontsize", "big", "`labels_fontsize` must be an integer or float.", TypeError),

nbs/tutorials/07-forest_plot.ipynb

@@ -665,9 +665,9 @@
     "\n",
     "- `marker_size`: The size of the markers for the effect sizes. The default is 12.\n",
     "\n",
-    "- ``halfviolin_alpha``: Transparency level for violin plots. The default is 0.8.\n",
+    "- ``contrast_alpha``: Transparency level for violin plots. The default is 0.8.\n",
     "\n",
-    "- ``halfviolin_desat``: Saturation level for violin plots. The default is 1.\n",
+    "- ``contrast_desat``: Saturation level for violin plots. The default is 1.\n",
     "\n",
     "- `labels_rotation`: Rotation angle for contrast labels. The default is 45.\n",
     "\n",