Delta-Delta Tests and Docs

1.  added doc string to class DeltaDelta and corrected typos
2. changed delta-delta tests and utils.py to mutant-drug configuration
3. generated test images for delta-delta tests
4. added tutorial page deltadelta.rst to include calculations and example plots
5. modified index.rst to include deltadelta
6. modified api.rst to include deltadelta
7. updated tutorial images for deltadelta

Author: sangyu

dabest/_classes.py

@@ -857,7 +857,65 @@ def _all_plot_groups(self):
 
 class DeltaDelta(object):
     """
-    A class to compute and store the delta-delta statistics.
+    A class to compute and store the delta-delta statistics. In a 2-by-2 arrangement where two independent variables, A and B, each have two categorical values, two primary deltas are first calculated with one independent variable and a delta-delta effect size is calculated as a difference between the two primary deltas.
+
+    .. math::
+
+        \\hat{\\theta}_{B1} = \\overline{X}_{A2, B1} - \\overline{X}_{A1, B1}
+
+        \\hat{\\theta}_{B2} = \\overline{X}_{A2, B2} - \\overline{X}_{A1, B2}
+    
+    .. math::
+
+        \\hat{\\theta}_{\\theta} = \\hat{\\theta}_{B2} - \\hat{\\theta}_{B1}
+    
+    and:
+
+    .. math::
+
+        s_{\\theta} = \\frac{(n_{A2, B1}-1)s_{A2, B1}^2+(n_{A1, B1}-1)s_{A1, B1}^2+(n_{A2, B2}-1)s_{A2, B2}^2+(n_{A1, B2}-1)s_{A1, B2}^2}{(n_{A2, B1} - 1) + (n_{A1, B1} - 1) + (n_{A2, B2} - 1) + (n_{A1, B2} - 1)}
+
+    Example
+    -------
+    >>> import numpy as np
+    >>> import pandas as pd
+    >>> from scipy.stats import norm # Used in generation of populations.
+    >>> np.random.seed(9999) # Fix the seed so the results are replicable.
+    >>> from scipy.stats import norm # Used in generation of populations.
+    >>> N = 20
+    >>> # Create samples
+    >>> y = norm.rvs(loc=3, scale=0.4, size=N*4)
+    >>> y[N:2*N] = y[N:2*N]+1
+    >>> y[2*N:3*N] = y[2*N:3*N]-0.5
+    >>> # Add drug column
+    >>> t1 = np.repeat('Placebo', N*2).tolist()
+    >>> t2 = np.repeat('Drug', N*2).tolist()
+    >>> treatment = t1 + t2 
+    >>> # Add a `rep` column as the first variable for the 2 replicates of experiments done
+    >>> rep = []
+    >>> for i in range(N*2):
+    >>>     rep.append('Rep1')
+    >>>     rep.append('Rep2')
+    >>> # Add a `genotype` column as the second variable
+    >>> wt = np.repeat('W', N).tolist()
+    >>> mt = np.repeat('M', N).tolist()
+    >>> wt2 = np.repeat('W', N).tolist()
+    >>> mt2 = np.repeat('M', N).tolist()
+    >>> genotype = wt + mt + wt2 + mt2
+    >>> # Add an `id` column for paired data plotting.
+    >>> id = list(range(0, N*2))
+    >>> id_col = id + id 
+    >>> # Combine all columns into a DataFrame.
+    >>> df_delta2 = pd.DataFrame({'ID'        : id_col,
+    >>>                   'Rep'      : rep,
+    >>>                    'Genotype'  : genotype, 
+    >>>                    'Drug': treatment,
+    >>>                    'Y'         : y
+    >>>                 })
+
+
+
+
     """
 
     def __init__(self, effectsizedataframe, permutation_count,
@@ -1014,8 +1072,8 @@ def __repr__(self, header=True, sigfig=3):
         bs2 = "the confidence interval is bias-corrected and accelerated."
         bs = bs1 + bs2
 
-        pval_def1 = "Any p-value reported is the probability of observing the" + \
-                    "effect size (or greater),\nassuming the null hypothesis of" + \
+        pval_def1 = "Any p-value reported is the probability of observing the " + \
+                    "effect size (or greater),\nassuming the null hypothesis of " + \
                     "zero difference is true."
         pval_def2 = "\nFor each p-value, 5000 reshuffles of the " + \
                     "control and test labels were performed."

dabest/tests/baseline_images/test_47_cummings_unpaired_delta_delta_meandiff.png

@@ -22,21 +22,26 @@
 
 df = create_demo_dataset_delta()
 
-unpaired = load(data = df, x = ["Light", "Genotype"], y = "Y", delta2 = True, 
-                experiment = "Experiment")
+unpaired = load(data = df, x = ["Genotype", "Genotype"], y = "Y", delta2 = True, 
+                experiment = "Treatment")
 
-baseline = load(data = df, x = ["Light", "Genotype"], y = "Y", delta2 = True, 
-                experiment = "Experiment",
+unpaired_specified = load(data = df, x = ["Genotype", "Genotype"], y = "Y", 
+					delta2 = True, experiment = "Treatment",
+                                        experiment_label = ["Drug", "Placebo"],
+                                        x1_level = ["M", "W"])
+
+baseline = load(data = df, x = ["Treatment", "Rep"], y = "Y", delta2 = True, 
+                experiment = "Genotype",
                 paired="baseline", id_col="ID")
 
-sequential = load(data = df, x = ["Light", "Genotype"], y = "Y", delta2 = True, 
-                experiment = "Experiment",
+sequential = load(data = df, x = ["Treatment", "Rep"], y = "Y", delta2 = True, 
+                experiment = "Genotype",
                 paired="sequential", id_col="ID")
 
 
 @pytest.mark.mpl_image_compare(tolerance=10)
 def test_47_cummings_unpaired_delta_delta_meandiff():
-    return unpaired.mean_diff.plot(fig_size=(12, 8), raw_marker_size=4);
+    return unpaired.mean_diff.plot();
 
 
 @pytest.mark.mpl_image_compare(tolerance=10)
@@ -62,14 +67,13 @@ def test_51_delta_plot_change_palette_a():
 
 
 @pytest.mark.mpl_image_compare(tolerance=10)
-def test_52_delta_dot_sizes():
-    return sequential.mean_diff.plot(show_pairs=False,raw_marker_size=3,
-                                       es_marker_size=12);
+def test_52_delta_specified():
+    return unpaired_specified.mean_diff.plot();
 
 
 @pytest.mark.mpl_image_compare(tolerance=10)
 def test_53_delta_change_ylims():
-    return sequential.mean_diff.plot(swarm_ylim=(0, 5),
+    return sequential.mean_diff.plot(swarm_ylim=(0, 9),
                                        contrast_ylim=(-2, 2),
                                        fig_size=(15,6));
 

dabest/tests/baseline_images/test_48_cummings_sequential_delta_delta_meandiff.png

@@ -98,39 +98,42 @@ def create_demo_dataset_delta(seed=9999, N=20):
     from scipy.stats import norm # Used in generation of populations.
 
     # Create samples
-    y = norm.rvs(loc=3, scale=0.4, size=N*2)
+    y = norm.rvs(loc=3, scale=0.4, size=N*4)
+    y[N:2*N] = y[N:2*N]+1
+    y[2*N:3*N] = y[2*N:3*N]-0.5
 
-    # Add experiment column
-    e1 = np.repeat('Control', N).tolist()
-    e2 = np.repeat('Test', N).tolist()
-    experiment = e1 + e2 
+    # Add drug column
+    t1 = np.repeat('Placebo', N*2).tolist()
+    t2 = np.repeat('Drug', N*2).tolist()
+    treatment = t1 + t2 
 
-    # Add a `Light` column as the first variable
-    light = []
-    for i in range(N):
-        light.append('L1')
-        light.append('L2')
+    # Add a `rep` column as the first variable for the 2 replicates of experiments done
+    rep = []
+    for i in range(N*2):
+        rep.append('Rep1')
+        rep.append('Rep2')
 
     # Add a `genotype` column as the second variable
-    g1 = np.repeat('G1', N/2).tolist()
-    g2 = np.repeat('G2', N/2).tolist()
-    g3 = np.repeat('G3', N).tolist()
-    genotype = g1 + g2 + g3
+    wt = np.repeat('W', N).tolist()
+    mt = np.repeat('M', N).tolist()
+    wt2 = np.repeat('W', N).tolist()
+    mt2 = np.repeat('M', N).tolist()
+
+
+    genotype = wt + mt + wt2 + mt2
 
     # Add an `id` column for paired data plotting.
-    id_col = []
-    for i in range(N):
-        id_col.append(i)
-        id_col.append(i)
+    id = list(range(0, N*2))
+    id_col = id + id 
 
-    # Combine samples and gender into a DataFrame.
+
+    # Combine all columns into a DataFrame.
     df = pd.DataFrame({'ID'        : id_col,
-                      'Light'      : light,
+                      'Rep'      : rep,
                        'Genotype'  : genotype, 
-                       'Experiment': experiment,
+                       'Treatment': treatment,
                        'Y'         : y
                     })
-                      
     return df
 
 

dabest/tests/baseline_images/test_49_cummings_baseline_delta_delta_meandiff.png

@@ -24,6 +24,8 @@ Computing Effect Sizes
 .. autoclass:: dabest._classes.MiniMetaDelta
   :members: difference, bca_low, bca_high, bootstraps, to_dict
 
+.. autoclass:: dabest._classes.DeltaDelta
+  :members: difference, bca_low, bca_high, bootstraps, bootstraps_delta_delta, to_dict
 
 Plotting Data
 -------------