Merge pull request #133 from maiyishan/v0.4dev

1. classes.py: added MiniMetaDelta, fixed Cohen's h function signatures
2. Added Cohen's h and minimeta function signatures to api.rst
3. Added minimetadelta.rst tutorial page, split repeated measures and plot aesthetics into their own pages
4. Added release notes to release-notes.rst & updated index.rst (landing page)
5. Changed version #s in documentation to v2023.02.14
6. Added upcoming release announcement to README.md, changed pictures to have white backgrounds

Author: maiyishan

README.md

@@ -6,6 +6,21 @@
 [![Free-to-view citation](https://zenodo.org/badge/DOI/10.1038/s41592-019-0470-3.svg)](https://rdcu.be/bHhJ4)
 [![License](https://img.shields.io/badge/License-BSD%203--Clause--Clear-orange.svg)](https://spdx.org/licenses/BSD-3-Clause-Clear.html)
 
+## Upcoming Version Update
+
+On 20 March 2023, we will be officially releasing **DABEST v2023.02.14 for Python**. This new version will provide the following new features:
+
+1. **Repeated measures.** Augments the prior function for plotting (independent) multiple test groups versus a shared control; it can now do the same for repeated-measures experimental designs. Thus, together, these two methods can be used to replace both flavors of the 1-way ANOVA with an estimation analysis.
+
+2. **Proportional data.** Generates proportional bar plots, proportional differences, and calculates Cohen's h. Also enables plotting Sankey diagrams for paired binary data. This is the estimation equivalent to a bar chart with Fischer's exact test.
+
+3. **The ∆∆ plot.** Calculates the delta-delta (∆∆) for 2 × 2 experimental designs and plots the four groups with their relevant effect sizes. This design can be used as a replacement for the 2 × 2 ANOVA.
+
+4. **Mini-meta.** Calculates and plots a weighted delta (∆) for meta-analysis of experimental replicates. Useful for summarizing data from multiple replicated experiments, for example by different scientists in the same lab, or the same scientist at different times. When the observed values are known (and share a common metric), this makes meta-analysis available as a routinely accessible tool.
+
+Prior to the official update, users keen to try these features now are invited to download the v0.4dev branch. After 20 March 2023, the new version will be the one we recommend for all users.
+
+
 ## Contents
 <!-- TOC depthFrom:1 depthTo:2 withLinks:1 updateOnSave:1 orderedList:0 -->
 - [About](#about)
@@ -32,7 +47,7 @@ An estimation plot has two key features.
 
 2. It presents the effect size as a **bootstrap 95% confidence interval** on a **separate but aligned axes**.
 
-![The five kinds of estimation plots](docs/source/_images/showpiece.png?raw=true "The five kinds of estimation plots.")
+![The five kinds of estimation plots](docs/source/_images/showpiece.png "The five kinds of estimation plots.")
 
 DABEST powers [estimationstats.com](https://www.estimationstats.com/), allowing everyone access to high-quality estimation plots.
 
@@ -78,7 +93,7 @@ iris_dabest = dabest.load(data=iris, x="species", y="petal_width",
 # Produce a Cumming estimation plot.
 iris_dabest.mean_diff.plot();
 ```
-![A Cumming estimation plot of petal width from the iris dataset](https://github.com/ACCLAB/DABEST-python/blob/master/iris.png)
+![A Cumming estimation plot of petal width from the iris dataset](iris.png)
 
 Please refer to the official [tutorial](https://acclab.github.io/DABEST-python-docs/tutorial.html) for more useful code snippets.
 
@@ -108,11 +123,11 @@ We also have a [Code of Conduct](https://github.com/ACCLAB/DABEST-python/blob/ma
 ### A wish list for new features
 Currently, DABEST offers functions to handle data traditionally analyzed with Student’s paired and unpaired t-tests. It also offers plots for multiplexed versions of these, and the estimation counterpart to a 1-way analysis of variance (ANOVA), the shared-control design. While these five functions execute a large fraction of common biomedical data analyses, there remain three others: 2-way data, time-series group data, and proportional data. We aim to add these new functions to both the R and Python libraries.
 
-● In many experiments, four groups are investigate to isolate an interaction, for example: a genotype × drug effect. Here, wild-type and mutant animals are each subjected to drug or sham treatments; the data are traditionally analysed with a 2×2 ANOVA. We have received requests by email, Twitter, and GitHub to implement an estimation counterpart to the 2-way ANOVA. To do this, we will implement ∆∆ plots, in which the difference of means (∆) of two groups is subtracted from a second two-group ∆. 
+● In many experiments, four groups are investigate to isolate an interaction, for example: a genotype × drug effect. Here, wild-type and mutant animals are each subjected to drug or sham treatments; the data are traditionally analysed with a 2×2 ANOVA. We have received requests by email, Twitter, and GitHub to implement an estimation counterpart to the 2-way ANOVA. To do this, we will implement ∆∆ plots, in which the difference of means (∆) of two groups is subtracted from a second two-group ∆. **Implemented in v2023.02.14.**
 
-● Currently, DABEST can analyse multiple paired data in a single plot, and multiple groups with a common, shared control. However, a common design in biomedical science is to follow the same group of subjects over multiple, successive time points. An estimation plot for this would combine elements of the two other designs, and could be used in place of a repeated-measures ANOVA. 
+● Currently, DABEST can analyse multiple paired data in a single plot, and multiple groups with a common, shared control. However, a common design in biomedical science is to follow the same group of subjects over multiple, successive time points. An estimation plot for this would combine elements of the two other designs, and could be used in place of a repeated-measures ANOVA. **Implemented in v2023.02.14**
 
-● We have observed that proportional data are often analyzed in neuroscience and other areas of biomedical research. However, compared to other data types, the charts are frequently impoverished: often, they omit error bars, sample sizes, and even P values—let alone effect sizes. We would like DABEST to feature proportion charts, with error bars and a curve for the distribution of the proportional differences.
+● We have observed that proportional data are often analyzed in neuroscience and other areas of biomedical research. However, compared to other data types, the charts are frequently impoverished: often, they omit error bars, sample sizes, and even P values—let alone effect sizes. We would like DABEST to feature proportion charts, with error bars and a curve for the distribution of the proportional differences. **Implemented in v2023.02.14**
 
 We encourage contributions for the above features. 
 

dabest/_api.py

@@ -88,6 +88,7 @@ def load(data, idx=None, x=None, y=None, paired=None, id_col=None,
     >>> my_data = dabest.load(df, idx=("Control 1", "Test 1"))
 
     For proportion plot.
+
     >>> np.random.seed(88888)
     >>> N = 10
     >>> c1 = np.random.binomial(1, 0.2, size=N)

dabest/_classes.py

@@ -572,18 +572,19 @@ def cohens_h(self):
 
         Notes
         -----
-        Cohen's 'h' uses the information of proportion in the control and test groups to calculate the distance between two proportions.
+        Cohen's *h* uses the information of proportion in the control and test groups to calculate the distance between two proportions.
         It can be used to describe the difference between two proportions as "small", "medium", or "large".
         It can be used to determine if the difference between two proportions is "meaningful".
 
-        A directional Cohen's 'h' is computed with the following equation:
+        A directional Cohen's *h* is computed with the following equation:
 
         .. math::
             h = 2 * \\arcsin{\\sqrt{proportion_{Test}}} - 2 * \\arcsin{\\sqrt{proportion_{Control}}}
 
-        For a non-directional Cohen's 'h', the equation is:
+        For a non-directional Cohen's *h*, the equation is:
+
         .. math::
-            h = \\abs{2 * \\arcsin{\\sqrt{proportion_{Test}}}} - \\abs{2 * \\arcsin{\\sqrt{proportion_{Control}}}}
+            h = |2 * \\arcsin{\\sqrt{proportion_{Test}}} - 2 * \\arcsin{\\sqrt{proportion_{Control}}}|
         
         References:
             https://en.wikipedia.org/wiki/Cohen%27s_h
@@ -1201,7 +1202,55 @@ def permutations_delta_delta(self):
 
 class MiniMetaDelta(object):
     """
-    A class to compute and store the weighted mean differences.
+    A class to compute and store the weighted delta.
+    A weighted delta is calculated if the argument ``mini_meta=True`` is passed during ``dabest.load()``.
+
+    The weighted delta is calcuated as follows:
+
+    .. math::
+	\\theta_{\\text{weighted}} = \\frac{\\Sigma\\hat{\\theta_{i}}w_{i}}{{\\Sigma}w_{i}}
+    
+    where:
+
+    .. math::
+	\\hat{\\theta_{i}} = \\text{Mean difference for replicate }i
+
+    .. math::
+	w_{i} = \\text{Weight for replicate }i = \\frac{1}{s_{i}^2} 
+
+    .. math::
+	s_{i}^2 = \\text{Pooled variance for replicate }i = \\frac{(n_{test}-1)s_{test}^2+(n_{control}-1)s_{control}^2}{n_{test}+n_{control}-2}
+
+    .. math::
+	n = \\text{sample size and }s^2 = \\text{variance for control/test.}
+
+
+    Example
+    -------
+    >>> from scipy.stats import norm
+    >>> import pandas as pd
+    >>> import dabest
+    >>> c1 = norm.rvs(loc=3, scale=0.4, size=Ns)
+    >>> c2 = norm.rvs(loc=3.5, scale=0.75, size=Ns)
+    >>> c3 = norm.rvs(loc=3.25, scale=0.4, size=Ns)
+
+    >>> t1 = norm.rvs(loc=3.5, scale=0.5, size=Ns)
+    >>> t2 = norm.rvs(loc=2.5, scale=0.6, size=Ns)
+    >>> t3 = norm.rvs(loc=3, scale=0.75, size=Ns)
+    >>> my_df   = pd.DataFrame({'Control 1' : c1,     'Test 1' : t1,
+                       'Control 2' : c2,     'Test 2' : t2,
+                       'Control 3' : c3,     'Test 3' : t3})
+    >>> my_dabest_object = dabest.load(df, idx=(("Control 1", "Test 1"), ("Control 2", "Test 2"), ("Control 3", "Test 3")), mini_meta=True)
+    >>> my_dabest_object.mean_diff.mini_meta_delta
+
+    Notes
+    -----
+    As of version 2023.02.14, weighted delta can only be calculated for mean difference, and not for standardized measures such as Cohen's *d*.
+
+    Details about the calculated weighted delta are accessed as attributes of the ``mini_meta_delta`` class. See the :doc:`minimetadelta` for details on usage.
+
+    Refer to Chapter 10 of the Cochrane handbook for further information on meta-analysis: https://training.cochrane.org/handbook/current/chapter-10
+		
     """
 
     def __init__(self, effectsizedataframe, permutation_count,

docs/source/_images/showpiece.png

@@ -2,6 +2,7 @@
 
 .. currentmodule:: dabest
 
+===
 API
 ===
 
@@ -15,11 +16,14 @@ Computing Effect Sizes
 ----------------------
 
 .. autoclass:: dabest._classes.Dabest
-  :members: mean_diff, median_diff, cohens_d, hedges_g, cliffs_delta
+  :members: mean_diff, median_diff, cohens_d, hedges_g, cliffs_delta, cohens_h
   :member-order: bysource
 
 .. .. autoclass:: dabest._classes.TwoGroupsEffectSize
 
+.. autoclass:: dabest._classes.MiniMetaDelta
+  :members: difference, bca_low, bca_high, bootstraps, to_dict
+
 
 Plotting Data
 -------------

docs/source/_images/tutorial_100_1.png

@@ -1,4 +1,4 @@
-.. _Bootstrap Confidence Intervals:
+.. _bootstraps:
 
 
 ==============================

docs/source/api.rst

@@ -67,7 +67,7 @@
 
 # General information about the project.
 project = 'dabest'
-copyright = '2017-2023, Joses W. Ho'
+copyright = '2016-2023, Joses W. Ho'
 author = 'Joses W. Ho'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -84,7 +84,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/source/bootstraps.rst

@@ -1,4 +1,4 @@
-.. _Getting Started:
+.. _getting-started:
 
 ===============
 Getting Started

docs/source/conf.py

@@ -6,6 +6,21 @@
 DABEST
 ======
 
+Update
+------
+**DABEST version 2023.02.14** has been released: 
+:doc:`release-notes`
+
+Briefly, this release introduces several new functions:
+
+  - Additional plotting functions for repeated measures experimental designs
+  - Calculating of Cohen's *h* and proportional plots for binary data
+  - Calculating and plotting delta-deltas for 2x2 experimental designs
+  - Calculating and plotting of weighted deltas for mini-meta-analysis of experimental replicates
+
+Refer to :doc:`release-notes` for full details.
+
+
 -----------------------------------------------
 Data Analysis with Bootstrap-coupled ESTimation
 -----------------------------------------------
@@ -18,8 +33,16 @@ Analyze your data with estimation statistics!
 
 News
 ----
+March 2023:
+  - **v2023.02.14** released. The following features have been added:
+     - Additional plotting functions for repeated measures experimental designs
+     - Calculating of Cohen's *h* and proportional plots for binary data
+     - Calculating and plotting delta-deltas for 2x2 experimental designs
+     - Calculating and plotting of weighted deltas for mini-meta-analysis of experimental replicates
+  - See :doc:`release-notes` for more details.
+
 October 2020:
-  - v0.3.1 released. The minimal versions of dependencies have been upgraded. Also, the minimal version of Python required is now 3.5.
+  - v0.3.1 released. The minimal versions of dependencies have been upgraded. Also, the minimal version of Python required is now 3.6.
 
 January 2020:
  - v0.3.0 released. Approximate permutation tests have been added, and are now the default p-values reported in the textual output. The LqRT tests were also refactored to a user-callable property. For more information, see the :doc:`release-notes`.
@@ -29,7 +52,7 @@ December 2019:
 
 October 2019:
   - v0.2.7 released. A minor bugfix in the handling of wide datasets with unequal Ns in each group.
-  - v0.2.6 released. This release has one new feature (plotting of estimation plot inside any :py:mod:`matplotlib` :py:class:`Axes`; see the section on :ref:`inset plot` in the :doc:`tutorial`). There are also two bug patches for the handling of bootstrap plotting, and of dependency installation.
+  - v0.2.6 released. This release has one new feature (plotting of estimation plot inside any :py:mod:`matplotlib` :py:class:`Axes`; see the section on :ref:`inset plot` in the :doc:`plotaesthetics`). There are also two bug patches for the handling of bootstrap plotting, and of dependency installation.
 
 September 2019:
   - v0.2.5 released. This release addresses two feature requests, and also patches two bugs: one affecting the paired difference CIs, and one involving NaNs in unused/irrelevant columns.
@@ -56,7 +79,10 @@ Contents
   bootstraps
   getting-started
   tutorial
+  repeatedmeasures
   proportion-plot
+  minimetadelta
+  plotaesthetics
   release-notes
   api
   about