DOC: docstrings for errorbar examples

phobson · phobson · commit b97c8a3d74db · 2016-10-22T09:26:18.000-07:00
diff --git a/examples/statistics/errorbar_demo.py b/examples/statistics/errorbar_demo.py
@@ -1,12 +1,17 @@
+"""Demo of the errorbar function.
+
+This exhibits the most basic use of of the error bar method.
+In this case, constant values are provided for both the error
+in the x- and y-directions.
 """
-Demo of the errorbar function.
-"""
+
 import numpy as np
 import matplotlib.pyplot as plt
 
 # example data
 x = np.arange(0.1, 4, 0.5)
 y = np.exp(-x)
 
-plt.errorbar(x, y, xerr=0.2, yerr=0.4)
+fig, ax = plt.subplots()
+ax.errorbar(x, y, xerr=0.2, yerr=0.4)
 plt.show()
diff --git a/examples/statistics/errorbar_demo_features.py b/examples/statistics/errorbar_demo_features.py
@@ -1,37 +1,41 @@
-"""
-Demo of errorbar function with different ways of specifying error bars.
+"""Demo of the different ways of specifying error bars.
 
-Errors can be specified as a constant value (as shown in `errorbar_demo.py`),
-or as demonstrated in this example, they can be specified by an N x 1 or 2 x N,
-where N is the number of data points.
+Errors can be specified as a constant value (as shown in
+`errorbar_demo.py`), or as demonstrated in this example, they can be
+specified by an N x 1 or 2 x N, where N is the number of data points.
 
 N x 1:
-    Error varies for each point, but the error values are symmetric (i.e. the
-    lower and upper values are equal).
+    Error varies for each point, but the error values are
+    symmetric (i.e. the lower and upper values are equal).
 
 2 x N:
-    Error varies for each point, and the lower and upper limits (in that order)
-    are different (asymmetric case)
+    Error varies for each point, and the lower and upper limits
+    (in that order) are different (asymmetric case)
 
-In addition, this example demonstrates how to use log scale with errorbar.
+In addition, this example demonstrates how to use log
+scale with error bars.
 """
+
 import numpy as np
 import matplotlib.pyplot as plt
 
 # example data
 x = np.arange(0.1, 4, 0.5)
 y = np.exp(-x)
+
 # example error bar values that vary with x-position
 error = 0.1 + 0.2 * x
-# error bar values w/ different -/+ errors
-lower_error = 0.4 * error
-upper_error = error
-asymmetric_error = [lower_error, upper_error]
 
 fig, (ax0, ax1) = plt.subplots(nrows=2, sharex=True)
 ax0.errorbar(x, y, yerr=error, fmt='-o')
 ax0.set_title('variable, symmetric error')
 
+# error bar values w/ different -/+ errors that
+# also vary with the x-position
+lower_error = 0.4 * error
+upper_error = error
+asymmetric_error = [lower_error, upper_error]
+
 ax1.errorbar(x, y, xerr=asymmetric_error, fmt='o')
 ax1.set_title('variable, asymmetric error')
 ax1.set_yscale('log')
diff --git a/examples/statistics/errorbar_limits.py b/examples/statistics/errorbar_limits.py
@@ -1,50 +1,74 @@
+"""Demo of how to include upper and lower limits in error bars
+
+In matplotlib, errors bars can have "limits". Applying limits to the
+error bars essentially makes the error unidirectional. Because of that,
+upper and lower limits can be applied in both the y- and x-directions
+via the `uplims`, `lolims`, `xuplims`, and `xlolims` parameters,
+respectively. This parameters can be scalar or boolean arrays.
+
+For example, if `xlolims` is `True`, the x-error bars will only extend
+from the data towards increasing values. If `uplims` is an array filled
+with `False` except for the 3rd and 5th values, all of the y-error bars
+will be bi-directional, except the 3rd and 5th bars, which will extend
+from the data towards decreasing y-values.
 """
-Demo of the errorbar function, including upper and lower limits
-"""
+
 import numpy as np
 import matplotlib.pyplot as plt
 
 # example data
-x = np.arange(0.5, 5.5, 0.5)
+x = np.array([0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0])
 y = np.exp(-x)
 xerr = 0.1
 yerr = 0.2
+
+# lower & upper limits of the error
+lolims = np.array([0, 0, 1, 0, 1, 0, 0, 0, 1, 0], dtype=bool)
+uplims = np.array([0, 1, 0, 0, 0, 1, 0, 0, 0, 1], dtype=bool)
 ls = 'dotted'
 
 fig = plt.figure()
 ax = fig.add_subplot(1, 1, 1)
 
 # standard error bars
-plt.errorbar(x, y, xerr=xerr, yerr=yerr, ls=ls)
+ax.errorbar(x, y, xerr=xerr, yerr=yerr, linestyle=ls)
 
 # including upper limits
-uplims = np.zeros(x.shape)
-uplims[[1, 5, 9]] = True
-plt.errorbar(x, y + 0.5, xerr=xerr, yerr=yerr, uplims=uplims, ls=ls)
+ax.errorbar(x, y + 0.5, xerr=xerr, yerr=yerr, uplims=uplims,
+			linestyle=ls)
 
 # including lower limits
-lolims = np.zeros(x.shape)
-lolims[[2, 4, 8]] = True
-plt.errorbar(x, y + 1.0, xerr=xerr, yerr=yerr, lolims=lolims, ls=ls)
+ax.errorbar(x, y + 1.0, xerr=xerr, yerr=yerr, lolims=lolims,
+			linestyle=ls)
 
 # including upper and lower limits
-plt.errorbar(x, y + 1.5, marker='o', ms=8, xerr=xerr, yerr=yerr,
-             lolims=lolims, uplims=uplims, ls=ls)
+ax.errorbar(x, y + 1.5, xerr=xerr, yerr=yerr,
+            lolims=lolims, uplims=uplims,
+            marker='o', markersize=8,
+            linestyle=ls)
 
-# including xlower and xupper limits
+## Plot a series with lower and upper limits in both x & y
+# constant x-error with varying y-error
 xerr = 0.2
 yerr = np.zeros(x.shape) + 0.2
 yerr[[3, 6]] = 0.3
+
+# mock up some limits by modifying previous data
 xlolims = lolims
 xuplims = uplims
 lolims = np.zeros(x.shape)
 uplims = np.zeros(x.shape)
-lolims[[6]] = True
-uplims[[3]] = True
-plt.errorbar(x, y + 2.1, marker='o', ms=8, xerr=xerr, yerr=yerr,
-             xlolims=xlolims, xuplims=xuplims, uplims=uplims, lolims=lolims,
-             ls='none')
+lolims[[6]] = True  # only limited at this index
+uplims[[3]] = True  # only limited at this index
+
+# do the plotting
+ax.errorbar(x, y + 2.1, xerr=xerr, yerr=yerr,
+            xlolims=xlolims, xuplims=xuplims,
+            uplims=uplims, lolims=lolims,
+            marker='o', markersize=8,
+            linestyle='none')
 
+# tidy up the figure
 ax.set_xlim((0, 5.5))
 ax.set_title('Errorbar upper and lower limits')
 plt.show()
diff --git a/examples/statistics/errorbars_and_boxes.py b/examples/statistics/errorbars_and_boxes.py
@@ -1,6 +1,21 @@
-'''
-Example to create boxes from error using PatchCollection
-'''
+"""Demo on creating boxes from error bars using PatchCollection
+
+In this example, we snazz up a pretty standard error bar plot by adding
+a rectangle patch defined by the limits of the bars in both the x- and
+y- directions. Do this, we have to write our own custom function called
+`make_error_boxes`. Close inspection of this function will reveal the
+preferred pattern in writting functions for matplotlib:
+
+  1. an `Axes` object is passed directly to the function
+  2. the function operates on the `Axes` methods directly, not through
+     the `pyplot` interface
+  3. plotting kwargs that could be abbreviated are spelled out for
+     better code readability in the figure (for example we use
+     `facecolor` instead of `fc`)
+  4. the artists returned by the `Axes` plotting methods are then
+     returned by the function so that, if desired, their styles
+     can be modified later (they are not modified in this example).
+"""
 
 import numpy as np
 import matplotlib.pyplot as plt
@@ -11,38 +26,43 @@
 n = 5
 
 # Dummy data
+np.random.seed(0)
 x = np.arange(0, n, 1)
-y = np.random.rand(n)*5.
+y = np.random.rand(n) * 5.
 
 # Dummy errors (above and below)
 xerr = np.random.rand(2, n)
 yerr = np.random.rand(2, n)
 
-# Create figure and axes
-fig, ax = plt.subplots(1)
-
-
-def make_error_boxes(ax, xdata, ydata, xerror, yerror, fc='r', ec='None', alpha=0.5):
+def make_error_boxes(ax, xdata, ydata, xerror, yerror, facecolor='r',
+                     edgecolor='None', alpha=0.5):
 
     # Create list for all the error patches
     errorboxes = []
 
     # Loop over data points; create box from errors at each point
-    for xc, yc, xe, ye in zip(xdata, ydata, xerror.T, yerror.T):
-        rect = Rectangle((xc-xe[0], yc-ye[0]), xe.sum(), ye.sum())
+    for x, y, xe, ye in zip(xdata, ydata, xerror.T, yerror.T):
+        rect = Rectangle((x - xe[0], y - ye[0]), xe.sum(), ye.sum())
         errorboxes.append(rect)
 
     # Create patch collection with specified colour/alpha
-    pc = PatchCollection(errorboxes, facecolor=fc, alpha=alpha, edgecolor=ec)
+    pc = PatchCollection(errorboxes, facecolor=facecolor, alpha=alpha,
+                         edgecolor=edgecolor)
 
     # Add collection to axes
     ax.add_collection(pc)
 
     # Plot errorbars
-    ax.errorbar(xdata, ydata, xerr=xerror, yerr=yerror, fmt='None', ecolor='k')
+    artists = ax.errorbar(xdata, ydata, xerr=xerror, yerr=yerror,
+                          fmt='None', ecolor='k')
+
+    return artists
+
 
+# Create figure and axes
+fig, ax = plt.subplots(1)
 
 # Call function to create error boxes
-make_error_boxes(ax, x, y, xerr, yerr)
+_ = make_error_boxes(ax, x, y, xerr, yerr)
 
 plt.show()
