Merge pull request #138 from ACCLAB/v2023.02.14

Merge v2023.02.14 into master branch

Author: maiyishan

.gitignore

@@ -122,3 +122,13 @@ fontList-v300.json
 # tex folders
 tex.cache/
 .Rproj.user
+testtt.py
+real.py
+0to2_beforeduringafter.csv
+
+TEST.ipynb
+TrhCsCh.csv
+Untitled.ipynb
+tt.py
+# Visual Studio
+.vscode/

LICENSE

@@ -1,6 +1,6 @@
 The Clear BSD License
 
-Copyright (c) 2016-2020 Joses W. Ho
+Copyright (c) 2016-2023 Joses W. Ho
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

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/__init__.py

@@ -23,4 +23,4 @@
 from ._stats_tools import effsize as effsize
 from ._classes import TwoGroupsEffectSize, PermutationTest
 
-__version__ = "0.3.1"
+__version__ = "2023.02.14"

dabest/_api.py

@@ -4,8 +4,10 @@
 # Email : joseshowh@gmail.com
 
 
-def load(data, idx, x=None, y=None, paired=False, id_col=None,
-        ci=95, resamples=5000, random_seed=12345):
+def load(data, idx=None, x=None, y=None, paired=None, id_col=None,
+        ci=95, resamples=5000, random_seed=12345, proportional=False, 
+        delta2 = False, experiment = None, experiment_label = None,
+        x1_level = None, mini_meta=False):
     '''
     Loads data in preparation for estimation statistics.
 
@@ -18,10 +20,19 @@ def load(data, idx, x=None, y=None, paired=False, id_col=None,
         List of column names (if 'x' is not supplied) or of category names
         (if 'x' is supplied). This can be expressed as a tuple of tuples,
         with each individual tuple producing its own contrast plot
-    x : string, default None
+    x : string or list, default None
+        Column name(s) of the independent variable. This can be expressed as
+        a list of 2 elements if and only if 'delta2' is True; otherwise it 
+        can only be a string.
     y : string, default None
         Column names for data to be plotted on the x-axis and y-axis.
-    paired : boolean, default False.
+    paired : string, default None
+        The type of the experiment under which the data are obtained. If 'paired' 
+        is None then the data will not be treated as paired data in the subsequent
+        calculations. If 'paired' is 'baseline', then in each tuple of x, other 
+        groups will be paired up with the first group (as control). If 'paired' is 
+        'sequential', then in each tuple of x, each group will be paired up with
+        its previous group (as control).
     id_col : default None.
         Required if `paired` is True.
     ci : integer, default 95
@@ -34,6 +45,28 @@ def load(data, idx, x=None, y=None, paired=False, id_col=None,
         This integer is used to seed the random number generator during
         bootstrap resampling, ensuring that the confidence intervals
         reported are replicable.
+    proportional : boolean, default False. 
+        An indicator of whether the data is binary or not. When set to True, it
+        specifies that the data consists of binary data, where the values are
+        limited to 0 and 1. The code is not suitable for analyzing proportion
+        data that contains non-numeric values, such as strings like ‘yes’ and ‘no’.
+        When False or not provided, the algorithm assumes that
+        the data is continuous and uses a non-proportional representation.
+    delta2 : boolean, default False
+        Indicator of delta-delta experiment
+    experiment : String, default None
+        The name of the column of the dataframe which contains the label of 
+        experiments
+    experiment_lab : list, default None
+        A list of String to specify the order of subplots for delta-delta plots.
+        This can be expressed as a list of 2 elements if and only if 'delta2' 
+        is True; otherwise it can only be a string. 
+    x1_level : list, default None
+        A list of String to specify the order of subplots for delta-delta plots.
+        This can be expressed as a list of 2 elements if and only if 'delta2' 
+        is True; otherwise it can only be a string. 
+    mini_meta : boolean, default False
+        Indicator of weighted delta calculation.
 
     Returns
     -------
@@ -59,7 +92,19 @@ def load(data, idx, x=None, y=None, paired=False, 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)
+    >>> t1 = np.random.binomial(1, 0.5, size=N)
+    >>> df = pd.DataFrame({'Control 1' : c1, 'Test 1': t1})
+    >>> my_data = dabest.load(df, idx=("Control 1", "Test 1"),proportional=True)
+
+
+
     '''
     from ._classes import Dabest
 
-    return Dabest(data, idx, x, y, paired, id_col, ci, resamples, random_seed)
+    return Dabest(data, idx, x, y, paired, id_col, ci, resamples, random_seed, proportional, delta2, experiment, experiment_label, x1_level, mini_meta)
+

dabest/_bootstrap_tools.py

@@ -18,8 +18,13 @@ class bootstrap:
             NaNs are automatically discarded.
 
         paired: boolean, default False
-            Whether or not x1 and x2 are paired samples.
-
+            Whether or not x1 and x2 are paired samples. If 'paired' is None then
+            the data will not be treated as paired data in the subsequent calculations. 
+            If 'paired' is 'baseline', then in each tuple of x, other groups will be
+            paired up with the first group (as control). If 'paired' is 'sequential', 
+            then in each tuple of x, each group will be paired up with the previous 
+            group (as control).
+            
         statfunction: callable, default np.mean
             The summary statistic called on data.
 
@@ -47,8 +52,8 @@ class bootstrap:
             Whether or not the summary is the difference between two groups.
             If False, only x1 was supplied.
 
-        is_paired: boolean
-            Whether or not the difference reported is between 2 paired groups.
+        is_paired : string, default None
+            The type of the experiment under which the data are obtained
 
         statistic: callable
             The function used to compute the summary.
@@ -85,19 +90,19 @@ class bootstrap:
 
         pvalue_2samp_ind_ttest: float
             P-value obtained from scipy.stats.ttest_ind.
-            If a single array was given (x1 only), or if `paired` is True,
+            If a single array was given (x1 only), or if `paired` is not None,
             returns 'NIL'.
             See https://docs.scipy.org/doc/scipy-1.0.0/reference/generated/scipy.stats.ttest_ind.html
 
         pvalue_2samp_related_ttest: float
             P-value obtained from scipy.stats.ttest_rel.
-            If a single array was given (x1 only), or if `paired` is False,
+            If a single array was given (x1 only), or if `paired` is None,
             returns 'NIL'.
             See https://docs.scipy.org/doc/scipy-1.0.0/reference/generated/scipy.stats.ttest_rel.html
 
         pvalue_wilcoxon: float
             P-value obtained from scipy.stats.wilcoxon.
-            If a single array was given (x1 only), or if `paired` is False,
+            If a single array was given (x1 only), or if `paired` is None,
             returns 'NIL'.
             The Wilcoxons signed-rank test is a nonparametric paired test of
             the null hypothesis that the related samples x1 and x2 are from
@@ -113,7 +118,7 @@ class bootstrap:
 
     '''
     def __init__(self, x1, x2=None,
-        paired=False,
+        paired=None,
         statfunction=None,
         smoothboot=False,
         alpha_level=0.05,
@@ -155,7 +160,7 @@ def __init__(self, x1, x2=None,
                 if len(x1) != len(x2):
                     raise ValueError('x1 and x2 are not the same length.')
 
-        if (x2 is None) or (paired is True) :
+        if (x2 is None) or (paired is not None) :
 
             if x2 is None:
                 tx = x1
@@ -165,7 +170,7 @@ def __init__(self, x1, x2=None,
                 ttest_2_paired = 'NIL'
                 wilcoxonresult = 'NIL'
 
-            elif paired is True:
+            elif paired is not None:
                 diff = True
                 tx = x2 - x1
                 ttest_single = 'NIL'
@@ -188,7 +193,7 @@ def __init__(self, x1, x2=None,
             pct_low_high = np.nan_to_num(pct_low_high).astype('int')
 
 
-        elif x2 is not None and paired is False:
+        elif x2 is not None and paired is None:
             diff = True
             x2 = pd.Series(x2).dropna()
             # Generate statarrays for both arrays.
@@ -268,7 +273,7 @@ def __repr__(self):
         else:
             stat = self.statistic
 
-        diff_types = {True: 'paired', False: 'unpaired'}
+        diff_types = {'sequential': 'paired', 'baseline': 'paired', None: 'unpaired'}
         if self.is_difference:
             a = 'The {} {} difference is {}.'.format(diff_types[self.is_paired],
                     stat, self.summary)