updated tutorials, readme, and forest plot effect size options

> Updated Readme
> Updated Tutorials
> Added more effect size options to forest plot for delta plotting

Author: JAnns98

README.md

@@ -22,20 +22,20 @@ performance improvements. It’s a big one!
 
 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](../tutorials/08-horizontal_plot.html) tutorial
+    setting `horizontal=True` in the `.plot()` method. See the
+    [Horizontal Plots tutorial](../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](../tutorials/07-forest_plot.html) tutorial for more details.
+    without presenting the raw data. See the [Forest Plots
+    tutorial](../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](../tutorials/09-plot_aesthetics.html) tutorial for more
+    in the `.plot()` method. See the gridkey section in the [Plot
+    Aesthetics tutorial](../tutorials/09-plot_aesthetics.html) for more
     details.
 
 5.  **Other Visualization Improvements**:
@@ -53,15 +53,15 @@ performance improvements. It’s a big one!
         control) in the contrast axis. They provide a visual
         representation of the differences between groups.
 
-      - **Summary Bars**: Optional horizontal bars that can be added to
-        emphasize a specific effect size across the entire contrast
-        axis. Unlike raw and contrast bars, these span horizontally and
-        are not displayed by default.
+      - **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.
 
-        By default, plots show raw and contrast bars. Users can
-        customize these bars and add summary bars as needed. For
-        detailed customization instructions, please refer to the [Plot
-        Aesthetics](../tutorials/09-plot_aesthetics.html) tutorial.
+        Raw and contrast bars are shown by default. Users can customize
+        these bars and add summary bars 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
       adjusted the spacing of delta-delta and mini-meta plots to reduce
@@ -77,31 +77,30 @@ performance improvements. It’s a big one!
 
     - **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.
+      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 or off via 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 by the user (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.
+      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 or off via the `delta_text` parameter.
+      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
+      `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.
 
@@ -117,13 +116,14 @@ performance improvements. It’s a big one!
       code, we have made several updates to the documentation and
       terminology to improve clarity and consistency. For example:
 
-      - Many plot arguments have been adjusted to bring more clarity and
+      - 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

dabest/forest_plot.py

@@ -164,9 +164,9 @@ def check_for_errors(**kwargs):
         raise TypeError("`fig_size` must be a tuple or list of two positive integers.")
 
     # Effect size
-    effect_size_options = ['mean_diff', 'hedges_g', 'delta_g']
+    effect_size_options = ['mean_diff', 'median_diff', 'cohens_d', 'cohens_h', 'cliffs_delta', 'hedges_g', 'delta_g']
     if not isinstance(effect_size, str) or effect_size not in effect_size_options:
-        raise TypeError("The `effect_size` argument must be a string and please choose from the following effect sizes: `mean_diff`, `hedges_g`, or `delta_g`.")
+        raise TypeError("The `effect_size` argument must be a string and please choose from the following effect sizes: 'mean_diff', 'median_diff', 'cohens_d', 'cohens_h', 'cliffs_delta', 'hedges_g', 'delta_g'.")
     if data[0].is_mini_meta and effect_size != 'mean_diff':
         raise ValueError("The `effect_size` argument must be `mean_diff` for mini-meta analyses.")
     if data[0].delta2 and effect_size not in ['mean_diff', 'hedges_g', 'delta_g']:
@@ -646,6 +646,10 @@ def forest_plot(
     if ylabel is None:
         effect_attr_map = {
             "mean_diff": "Mean Difference",
+            "median_diff": "Median Difference", 
+            "cohens_d": "Cohen's d",
+            "cohens_h": "Cohen's h",
+            "cliffs_delta": "Cliff's delta",
             "hedges_g": "Hedges' g",
             "delta_g": "Delta g"
         }

nbs/01-getting_started.ipynb

@@ -64,7 +64,7 @@
    "source": [
     "\n",
     "\n",
-    "Python 3.11 is strongly recommended. DABEST has also been tested with Python 3.10 and onwards.\n",
+    "Python 3.11 is recommended. DABEST has also been tested with Python 3.10 and onwards.\n",
     "\n",
     "In addition, the following packages are also required (listed with their minimal versions):\n",
     "\n",

nbs/API/forest_plot.ipynb

@@ -224,9 +224,9 @@
     "        raise TypeError(\"`fig_size` must be a tuple or list of two positive integers.\")\n",
     "\n",
     "    # Effect size\n",
-    "    effect_size_options = ['mean_diff', 'hedges_g', 'delta_g']\n",
+    "    effect_size_options = ['mean_diff', 'median_diff', 'cohens_d', 'cohens_h', 'cliffs_delta', 'hedges_g', 'delta_g']\n",
     "    if not isinstance(effect_size, str) or effect_size not in effect_size_options:\n",
-    "        raise TypeError(\"The `effect_size` argument must be a string and please choose from the following effect sizes: `mean_diff`, `hedges_g`, or `delta_g`.\")\n",
+    "        raise TypeError(\"The `effect_size` argument must be a string and please choose from the following effect sizes: 'mean_diff', 'median_diff', 'cohens_d', 'cohens_h', 'cliffs_delta', 'hedges_g', 'delta_g'.\")\n",
     "    if data[0].is_mini_meta and effect_size != 'mean_diff':\n",
     "        raise ValueError(\"The `effect_size` argument must be `mean_diff` for mini-meta analyses.\")\n",
     "    if data[0].delta2 and effect_size not in ['mean_diff', 'hedges_g', 'delta_g']:\n",
@@ -706,6 +706,10 @@
     "    if ylabel is None:\n",
     "        effect_attr_map = {\n",
     "            \"mean_diff\": \"Mean Difference\",\n",
+    "            \"median_diff\": \"Median Difference\", \n",
+    "            \"cohens_d\": \"Cohen's d\",\n",
+    "            \"cohens_h\": \"Cohen's h\",\n",
+    "            \"cliffs_delta\": \"Cliff's delta\",\n",
     "            \"hedges_g\": \"Hedges' g\",\n",
     "            \"delta_g\": \"Delta g\"\n",
     "        }\n",

nbs/read_me.ipynb

@@ -33,45 +33,45 @@
     "\n",
     "1. **Python 3.13 Support**: DABEST now supports Python 3.10—3.13.\n",
     "\n",
-    "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](../tutorials/08-horizontal_plot.html) tutorial for more details.\n",
+    "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](../tutorials/08-horizontal_plot.html) for more details.\n",
     "\n",
-    "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](../tutorials/07-forest_plot.html) tutorial for more details.\n",
+    "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](../tutorials/07-forest_plot.html) for more details.\n",
     "\n",
-    "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](../tutorials/09-plot_aesthetics.html) tutorial for more details.\n",
+    "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](../tutorials/09-plot_aesthetics.html) for more details.\n",
     "\n",
     "5. **Other Visualization Improvements**:\n",
     "   - **Raw, Contrast, and Summary bars**: Our visualization package now includes three types of customizable bars to enhance data interpretation:\n",
     "     - **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.\n",
     "     - **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.\n",
-    "     - **Summary Bars**: Optional horizontal bars that can be added to emphasize a specific effect size across the entire contrast axis. Unlike raw and contrast bars, these span horizontally and are not displayed by default.\n",
+    "     - **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.\n",
     "\n",
-    "          By default, plots show raw and contrast bars. Users can customize these bars and add summary bars as needed. For detailed customization instructions, please refer to the [Plot Aesthetics](../tutorials/09-plot_aesthetics.html) tutorial.\n",
+    "          Raw and contrast bars are shown by default. Users can customize these bars and add summary bars as needed. For detailed customization instructions, please refer to the [Plot Aesthetics tutorial](../tutorials/09-plot_aesthetics.html).\n",
     "\n",
     "   - **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.\n",
     "\n",
     "   - **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.\n",
     "\n",
-    "   - **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.\n",
+    "   - **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.\n",
     "\n",
-    "   - **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 or off via the `contrast_paired_lines` parameter.\n",
+    "   - **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.\n",
     "\n",
-    "   - **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 by the user (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. \n",
+    "   - **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. \n",
     "\n",
-    "   - **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 or off via the `delta_text` parameter.\n",
+    "   - **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.\n",
     "\n",
-    "   - **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.\n",
+    "   - **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.\n",
     "\n",
     "6. **Miscellaneous Improvements & Adjustments**\n",
     "    - **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.\n",
     "  \n",
     "    - **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:\n",
-    "      - Many 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.\n",
+    "      - 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.\n",
+    "  \n",
     "      - 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).\n",
     "\n",
     "    - **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!\n",
     "\n",
-    "    - **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.\n",
-    "\n"
+    "    - **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."
    ]
   },
   {