Refactored axes.violinplot into cbook.violin_stats (arranges violin plot data for drawing), axes.violin (draws pre-arranged violin plot data), and axes.violinplot (uses cbook.violin_stats to draw violin plots via axes.violin)

solvents · solvents · commit b8db6d24f659 · 2014-05-24T16:48:00.000-04:00
Updated whats_new.rst.
Updated CHANGELOG.
diff --git a/CHANGELOG b/CHANGELOG
@@ -30,6 +30,10 @@
            interpolation = 'none' and interpolation = 'nearest' in
            `imshow()` when saving vector graphics files.
 
+2014-04-22 Added violin plotting functions. See `Axes.violinplot`,
+           `Axes.violin`, `cbook.violin_stats` and `mlab.GaussianKDE` for
+           details.
+
 2014-04-10 Fixed the triangular marker rendering error. The "Up" triangle was
            rendered instead of "Right" triangle and vice-versa.
 
diff --git a/doc/users/whats_new.rst b/doc/users/whats_new.rst
@@ -172,6 +172,27 @@ Added the Axes method :meth:`~matplotlib.axes.Axes.add_image` to put image
 handling on a par with artists, collections, containers, lines, patches,
 and tables.
 
+Violin Plots
+````````````
+Per Parker, Gregory Kelsie, Adam Ortiz, Kevin Chan, Geoffrey Lee, Deokjae
+Donald Seo, and Taesu Terry Lim added a basic implementation for violin
+plots. Violin plots can be used to represent the distribution of sample data.
+They are similar to box plots, but use a kernel density estimation function to
+present a smooth approximation of the data sample used. The added features are:
+
+:func:`~matplotlib.Axes.violin` - Renders a violin plot from a collection of
+statistics.
+:func:`~matplotlib.cbook.violin_stats` - Produces a collection of statistics
+suitable for rendering a violin plot.
+:func:`~matplotlib.pyplot.violinplot` - Creates a violin plot from a set of
+sample data. This method makes use of :func:`~matplotlib.cbook.violin_stats`
+to process the input data, and :func:`~matplotlib.cbook.violin_stats` to
+do the actual rendering. Users are also free to modify or replace the output of
+:func:`~matplotlib.cbook.violin_stats` in order to customize the violin plots
+to their liking.
+
+This feature was implemented for a software engineering course at the
+University of Toronto, Scarborough, run in Winter 2014 by Anya Tafliovich.
 
 More `markevery` options to show only a subset of markers
 `````````````````````````````````````````````````````````
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -6739,8 +6739,8 @@ def violinplot(self, dataset, positions=None, vert=True, widths=0.5,
 
         Make a violin plot for each column of *dataset* or each vector in
         sequence *dataset*.  Each filled area extends to represent the
-        entire data range, with three lines at the mean, the minimum, and
-        the maximum.
+        entire data range, with optional lines at the mean, the median,
+        the minimum, and the maximum.
 
         Parameters
         ----------
@@ -6778,7 +6778,7 @@ def violinplot(self, dataset, positions=None, vert=True, widths=0.5,
             The method used to calculate the estimator bandwidth.  This can be
             'scott', 'silverman', a scalar constant or a callable.  If a
             scalar, this will be used directly as `kde.factor`.  If a
-            callable, it should take a `GaussianKDE` instance as only
+            callable, it should take a `GaussianKDE` instance as its only
             parameter and return a scalar. If None (default), 'scott' is used.
 
         Returns
@@ -6806,6 +6806,91 @@ def violinplot(self, dataset, positions=None, vert=True, widths=0.5,
 
         """
 
+        def _kde_method(X, coords):
+            kde = mlab.GaussianKDE(X, bw_method)
+            return kde.evaluate(coords)
+
+        vpstats = cbook.violin_stats(dataset, _kde_method, points=points)
+        return self.violin(vpstats, positions=positions, vert=vert,
+                           widths=widths, showmeans=showmeans,
+                           showextrema=showextrema, showmedians=showmedians)
+
+    def violin(self, vpstats, positions=None, vert=True, widths=0.5,
+               showmeans=False, showextrema=True, showmedians=False):
+        """
+        Drawing function for violin plots.
+
+        Call signature::
+
+          violin(vpstats, positions=None, vert=True, widths=0.5,
+                 showmeans=False, showextrema=True, showmedians=False):
+
+        Draw a violin plot for each column of `vpstats`. Each filled area
+        extends to represent the entire data range, with optional lines at the
+        mean, the median, the minimum, and the maximum.
+
+        Parameters
+        ----------
+
+          vpstats : list of dicts
+            A list of dictionaries containing stats for each violin plot.
+            Required keys are:
+              - coords: A list of scalars containing the coordinates that
+                the violin's kernel density estimate were evaluated at.
+              - vals: A list of scalars containing the values of the kernel
+                density estimate at each of the coordinates given in `coords`.
+              - mean: The mean value for this violin's dataset.
+              - median: The median value for this violin's dataset.
+              - min: The minimum value for this violin's dataset.
+              - max: The maximum value for this violin's dataset.
+
+          positions : array-like, default = [1, 2, ..., n]
+            Sets the positions of the violins. The ticks and limits are
+            automatically set to match the positions.
+
+          vert : bool, default = True.
+            If true, plots the violins veritcally.
+            Otherwise, plots the violins horizontally.
+
+          widths : array-like, default = 0.5
+            Either a scalar or a vector that sets the maximal width of
+            each violin. The default is 0.5, which uses about half of the
+            available horizontal space.
+
+          showmeans : bool, default = False
+            If true, will toggle rendering of the means.
+
+          showextrema : bool, default = True
+            If true, will toggle rendering of the extrema.
+
+          showmedians : bool, default = False
+            If true, will toggle rendering of the medians.
+
+        Returns
+        -------
+
+        A dictionary mapping each component of the violinplot to a list of the
+        corresponding collection instances created. The dictionary has
+        the following keys:
+
+            - bodies: A list of the
+              :class:`matplotlib.collections.PolyCollection` instances
+              containing the filled area of each violin.
+            - means: A :class:`matplotlib.collections.LineCollection` instance
+              created to identify the mean values of each of the violin's
+              distribution.
+            - mins: A :class:`matplotlib.collections.LineCollection` instance
+              created to identify the bottom of each violin's distribution.
+            - maxes: A :class:`matplotlib.collections.LineCollection` instance
+              created to identify the top of each violin's distribution.
+            - bars: A :class:`matplotlib.collections.LineCollection` instance
+              created to identify the centers of each violin's distribution.
+            - medians: A :class:`matplotlib.collections.LineCollection`
+              instance created to identify the median values of each of the
+              violin's distribution.
+
+        """
+
         # Statistical quantities to be plotted on the violins
         means = []
         mins = []
@@ -6822,22 +6907,23 @@ def violinplot(self, dataset, positions=None, vert=True, widths=0.5,
             'cmedians': None
         }
 
+        N = len(vpstats)
         datashape_message = ("List of violinplot statistics and `{0}` "
                              "values must have the same length")
 
         # Validate positions
         if positions is None:
-            positions = range(1, len(dataset) + 1)
-        elif len(positions) != len(dataset):
+            positions = range(1, N + 1)
+        elif len(positions) != N:
             raise ValueError(datashape_message.format("positions"))
 
         # Validate widths
         if np.isscalar(widths):
-            widths = [widths] * len(dataset)
-        elif len(widths) != len(dataset):
+            widths = [widths] * N
+        elif len(widths) != N:
             raise ValueError(datashape_message.format("widths"))
 
-        # Calculate mins and maxes for statistics lines
+        # Calculate ranges for statistics lines
         pmins = -0.25 * np.array(widths) + positions
         pmaxes = 0.25 * np.array(widths) + positions
 
@@ -6857,33 +6943,20 @@ def violinplot(self, dataset, positions=None, vert=True, widths=0.5,
             blines = self.hlines
 
         # Render violins
-        for data, pos, width in zip(dataset, positions, widths):
-            # Calculate the kernel density
-            kde = mlab.GaussianKDE(data, bw_method)
-            min_val = kde.dataset.min()
-            max_val = kde.dataset.max()
-            mean = np.mean(kde.dataset)
-            median = np.median(kde.dataset)
-            coords = np.linspace(min_val, max_val, points)
-
-            vals = kde.evaluate(coords)
-
-            # Since each data point p is plotted from v-p to v+p,
-            # we need to scale it by an additional 0.5 factor so that we get
-            # correct width in the end.
-            vals = 0.5 * width * vals/vals.max()
-
-            # create the violin bodies
-            artists['bodies'] += [fill(coords,
+        for stats, pos, width in zip(vpstats, positions, widths):
+            # The 0.5 factor reflects the fact that we plot from v-p to
+            # v+p
+            vals = np.array(stats['vals'])
+            vals = 0.5 * width * vals / vals.max()
+            artists['bodies'] += [fill(stats['coords'],
                                        -vals + pos,
                                        vals + pos,
                                        facecolor='y',
                                        alpha=0.3)]
-
-            means.append(mean)
-            mins.append(min_val)
-            maxes.append(max_val)
-            medians.append(median)
+            means.append(stats['mean'])
+            mins.append(stats['min'])
+            maxes.append(stats['max'])
+            medians.append(stats['median'])
 
         # Render means
         if showmeans:
diff --git a/lib/matplotlib/cbook.py b/lib/matplotlib/cbook.py
@@ -1944,28 +1944,7 @@ def _compute_conf_interval(data, med, iqr, bootstrap):
     bxpstats = []
 
     # convert X to a list of lists
-    if hasattr(X, 'shape'):
-        # one item
-        if len(X.shape) == 1:
-            if hasattr(X[0], 'shape'):
-                X = list(X)
-            else:
-                X = [X, ]
-
-        # several items
-        elif len(X.shape) == 2:
-            nrows, ncols = X.shape
-            if nrows == 1:
-                X = [X]
-            elif ncols == 1:
-                X = [X.ravel()]
-            else:
-                X = [X[:, i] for i in xrange(ncols)]
-        else:
-            raise ValueError("input `X` must have 2 or fewer dimensions")
-
-    if not hasattr(X[0], '__len__'):
-        X = [X]
+    X = _reshape_2D(X)
 
     ncols = len(X)
     if labels is None:
@@ -1982,7 +1961,7 @@ def _compute_conf_interval(data, med, iqr, bootstrap):
         stats['mean'] = np.mean(x)
 
         # medians and quartiles
-        q1, med, q3 =  np.percentile(x, [25, 50, 75])
+        q1, med, q3 = np.percentile(x, [25, 50, 75])
 
         # interquartile range
         stats['iqr'] = q3 - q1
@@ -2004,7 +1983,7 @@ def _compute_conf_interval(data, med, iqr, bootstrap):
                 hival = np.max(x)
             else:
                 whismsg = ('whis must be a float, valid string, or '
-                          'list of percentiles')
+                           'list of percentiles')
                 raise ValueError(whismsg)
         else:
             loval = np.percentile(x, whis[0])
@@ -2157,6 +2136,104 @@ def is_math_text(s):
     return even_dollars
 
 
+def _reshape_2D(X):
+    if hasattr(X, 'shape'):
+        # one item
+        if len(X.shape) == 1:
+            if hasattr(X[0], 'shape'):
+                X = list(X)
+            else:
+                X = [X, ]
+
+        # several items
+        elif len(X.shape) == 2:
+            nrows, ncols = X.shape
+            if nrows == 1:
+                X = [X]
+            elif ncols == 1:
+                X = [X.ravel()]
+            else:
+                X = [X[:, i] for i in xrange(ncols)]
+        else:
+            raise ValueError("input `X` must have 2 or fewer dimensions")
+
+    if not hasattr(X[0], '__len__'):
+        X = [X]
+
+    return X
+
+
+def violin_stats(X, method, points=100):
+    '''
+    Returns a list of dictionaries of data which can be used to draw a series
+    of violin plots. See the `Returns` section below to view the required keys
+    of the dictionary. Users can skip this function and pass a user-defined set
+    of dictionaries to the `axes.vplot` method instead of using MPL to do the
+    calculations.
+
+    Parameters
+    ----------
+    X : array-like
+        Sample data that will be used to produce the gaussian kernel density
+        estimates. Must have 2 or fewer dimensions.
+
+    method : callable
+        The method used to calculate the kernel density estimate for each
+        column of data. When called via `method(v, coords)`, it should
+        return a vector of the values of the KDE evaluated at the values
+        specified in coords.
+
+    points : scalar, default = 100
+        Defines the number of points to evaluate each of the gaussian kernel
+        density estimates at.
+
+    Returns
+    -------
+
+    A list of dictionaries containing the results for each column of data.
+    The dictionaries contain at least the following:
+
+        - coords: A list of scalars containing the coordinates this particular
+          kernel density estimate was evaluated at.
+        - vals: A list of scalars containing the values of the kernel density
+          estimate at each of the coordinates given in `coords`.
+        - mean: The mean value for this column of data.
+        - median: The median value for this column of data.
+        - min: The minimum value for this column of data.
+        - max: The maximum value for this column of data.
+    '''
+
+    # List of dictionaries describing each of the violins.
+    vpstats = []
+
+    # Want X to be a list of data sequences
+    X = _reshape_2D(X)
+
+    for x in X:
+        # Dictionary of results for this distribution
+        stats = {}
+
+        # Calculate basic stats for the distribution
+        min_val = np.min(x)
+        max_val = np.max(x)
+
+        # Evaluate the kernel density estimate
+        coords = np.linspace(min_val, max_val, points)
+        stats['vals'] = method(x, coords)
+        stats['coords'] = coords
+
+        # Store additional statistics for this distribution
+        stats['mean'] = np.mean(x)
+        stats['median'] = np.median(x)
+        stats['min'] = min_val
+        stats['max'] = max_val
+
+        # Append to output
+        vpstats.append(stats)
+
+    return vpstats
+
+
 class _NestedClassGetter(object):
     # recipe from http://stackoverflow.com/a/11493777/741316
     """
