Merge pull request #6303 from discardthree/mplot3d-examples-MEP12

WeatherGod · WeatherGod · commit f00db67f496e · 2016-04-19T16:20:10.000-04:00
DOC Clean up on about half the Mplot3d examples
diff --git a/examples/mplot3d/2dcollections3d_demo.py b/examples/mplot3d/2dcollections3d_demo.py
@@ -1,23 +1,42 @@
+'''
+Demonstrates using ax.plot's zdir keyword to plot 2D scatterplot data on
+selective axes of a 3D plot.
+'''
+
 from mpl_toolkits.mplot3d import Axes3D
 import numpy as np
 import matplotlib.pyplot as plt
 
 fig = plt.figure()
 ax = fig.gca(projection='3d')
 
+# Plot a sin curve using the x and y axes.
 x = np.linspace(0, 1, 100)
 y = np.sin(x * 2 * np.pi) / 2 + 0.5
-ax.plot(x, y, zs=0, zdir='z', label='zs=0, zdir=z')
+ax.plot(x, y, zs=0, zdir='z', label='curve in (x,y)')
 
+# Plot scatterplot data (20 2D points per colour) on the x and z axes.
 colors = ('r', 'g', 'b', 'k')
+x = np.random.sample(20*len(colors))
+y = np.random.sample(20*len(colors))
+c_list = []
 for c in colors:
-    x = np.random.sample(20)
-    y = np.random.sample(20)
-    ax.scatter(x, y, 0, zdir='y', c=c)
+    c_list.append([c]*20)
+# By using zdir='y', the y value of these points is fixed to the zs value 0
+# and the (x,y) points are plotted on the x and z axes.
+ax.scatter(x, y, zs=0, zdir='y', c=c_list, label='points in (x,z)')
 
+# Make legend, set axes limits and labels
 ax.legend()
 ax.set_xlim3d(0, 1)
 ax.set_ylim3d(0, 1)
 ax.set_zlim3d(0, 1)
+ax.set_xlabel('X')
+ax.set_ylabel('Y')
+ax.set_zlabel('Z')
+
+# Customize the view angle so it's easier to see that the scatter points lie
+# on the plane y=0
+ax.view_init(elev=20., azim=-35)
 
 plt.show()
diff --git a/examples/mplot3d/bars3d_demo.py b/examples/mplot3d/bars3d_demo.py
@@ -1,21 +1,35 @@
+'''
+Demonstrates making a 3D plot which has 2D bar graphs projected onto
+planes y=0, y=1, etc.
+'''
+
 from mpl_toolkits.mplot3d import Axes3D
 import matplotlib.pyplot as plt
 import numpy as np
 
 fig = plt.figure()
 ax = fig.add_subplot(111, projection='3d')
-for c, z in zip(['r', 'g', 'b', 'y'], [30, 20, 10, 0]):
+
+colors = ['r', 'g', 'b', 'y']
+yticks = [3, 2, 1, 0]
+for c, k in zip(colors, yticks):
+    # Generate the random data for the y=k 'layer'.
     xs = np.arange(20)
     ys = np.random.rand(20)
 
-    # You can provide either a single color or an array. To demonstrate this,
-    # the first bar of each set will be colored cyan.
+    # You can provide either a single color or an array with the same length as
+    # xs and ys. To demonstrate this, we color the first bar of each set cyan.
     cs = [c] * len(xs)
     cs[0] = 'c'
-    ax.bar(xs, ys, zs=z, zdir='y', color=cs, alpha=0.8)
+
+    # Plot the bar graph given by xs and ys on the plane y=k with 80% opacity.
+    ax.bar(xs, ys, zs=k, zdir='y', color=cs, alpha=0.8)
 
 ax.set_xlabel('X')
 ax.set_ylabel('Y')
 ax.set_zlabel('Z')
 
+# On the y axis let's only label the discrete values that we have data for.
+ax.set_yticks(yticks)
+
 plt.show()
diff --git a/examples/mplot3d/contour3d_demo.py b/examples/mplot3d/contour3d_demo.py
@@ -1,11 +1,21 @@
+'''
+Demonstrates plotting contour (level) curves in 3D.
+
+This is like a contour plot in 2D except that the f(x,y)=c curve is plotted
+on the plane z=c.
+'''
+
 from mpl_toolkits.mplot3d import axes3d
 import matplotlib.pyplot as plt
 from matplotlib import cm
 
 fig = plt.figure()
-ax = fig.add_subplot(111, projection='3d')
+ax = fig.gca(projection='3d')
 X, Y, Z = axes3d.get_test_data(0.05)
+
+# Plot contour curves
 cset = ax.contour(X, Y, Z, cmap=cm.coolwarm)
+
 ax.clabel(cset, fontsize=9, inline=1)
 
 plt.show()
diff --git a/examples/mplot3d/contour3d_demo2.py b/examples/mplot3d/contour3d_demo2.py
@@ -1,11 +1,20 @@
+'''
+Demonstrates plotting contour (level) curves in 3D using the extend3d option.
+
+This modification of the contour3d_demo example uses extend3d=True to
+extend the curves vertically into 'ribbons'.
+'''
+
 from mpl_toolkits.mplot3d import axes3d
 import matplotlib.pyplot as plt
 from matplotlib import cm
 
 fig = plt.figure()
 ax = fig.gca(projection='3d')
 X, Y, Z = axes3d.get_test_data(0.05)
+
 cset = ax.contour(X, Y, Z, extend3d=True, cmap=cm.coolwarm)
+
 ax.clabel(cset, fontsize=9, inline=1)
 
 plt.show()
diff --git a/examples/mplot3d/contour3d_demo3.py b/examples/mplot3d/contour3d_demo3.py
@@ -1,20 +1,34 @@
+'''
+Demonstrates displaying a 3D surface while also projecting contour 'profiles'
+onto the 'walls' of the graph.
+
+See contourf3d_demo2 for the filled version.
+'''
+
 from mpl_toolkits.mplot3d import axes3d
 import matplotlib.pyplot as plt
 from matplotlib import cm
 
 fig = plt.figure()
 ax = fig.gca(projection='3d')
 X, Y, Z = axes3d.get_test_data(0.05)
+
+# Plot the 3D surface
 ax.plot_surface(X, Y, Z, rstride=8, cstride=8, alpha=0.3)
+
+# Plot projections of the contours for each dimension.  By choosing offsets
+# that match the appropriate axes limits, the projected contours will sit on
+# the 'walls' of the graph
 cset = ax.contour(X, Y, Z, zdir='z', offset=-100, cmap=cm.coolwarm)
 cset = ax.contour(X, Y, Z, zdir='x', offset=-40, cmap=cm.coolwarm)
 cset = ax.contour(X, Y, Z, zdir='y', offset=40, cmap=cm.coolwarm)
 
-ax.set_xlabel('X')
 ax.set_xlim(-40, 40)
-ax.set_ylabel('Y')
 ax.set_ylim(-40, 40)
-ax.set_zlabel('Z')
 ax.set_zlim(-100, 100)
 
+ax.set_xlabel('X')
+ax.set_ylabel('Y')
+ax.set_zlabel('Z')
+
 plt.show()
diff --git a/examples/mplot3d/contourf3d_demo.py b/examples/mplot3d/contourf3d_demo.py
@@ -1,11 +1,21 @@
+'''
+contourf differs from contour in that it creates filled contours, ie.
+a discrete number of colours are used to shade the domain.
+
+This is like a contourf plot in 2D except that the shaded region corresponding
+to the level c is graphed on the plane z=c.
+'''
+
 from mpl_toolkits.mplot3d import axes3d
 import matplotlib.pyplot as plt
 from matplotlib import cm
 
 fig = plt.figure()
 ax = fig.gca(projection='3d')
 X, Y, Z = axes3d.get_test_data(0.05)
+
 cset = ax.contourf(X, Y, Z, cmap=cm.coolwarm)
+
 ax.clabel(cset, fontsize=9, inline=1)
 
 plt.show()
diff --git a/examples/mplot3d/contourf3d_demo2.py b/examples/mplot3d/contourf3d_demo2.py
@@ -1,7 +1,9 @@
-"""
-.. versionadded:: 1.1.0
-   This demo depends on new features added to contourf3d.
-"""
+'''
+Demonstrates displaying a 3D surface while also projecting filled contour
+'profiles' onto the 'walls' of the graph.
+
+See contour3d_demo2 for the unfilled version.
+'''
 
 from mpl_toolkits.mplot3d import axes3d
 import matplotlib.pyplot as plt
@@ -10,16 +12,23 @@
 fig = plt.figure()
 ax = fig.gca(projection='3d')
 X, Y, Z = axes3d.get_test_data(0.05)
+
+# Plot the 3D surface
 ax.plot_surface(X, Y, Z, rstride=8, cstride=8, alpha=0.3)
+
+# Plot projections of the contours for each dimension.  By choosing offsets
+# that match the appropriate axes limits, the projected contours will sit on
+# the 'walls' of the graph
 cset = ax.contourf(X, Y, Z, zdir='z', offset=-100, cmap=cm.coolwarm)
 cset = ax.contourf(X, Y, Z, zdir='x', offset=-40, cmap=cm.coolwarm)
 cset = ax.contourf(X, Y, Z, zdir='y', offset=40, cmap=cm.coolwarm)
 
-ax.set_xlabel('X')
 ax.set_xlim(-40, 40)
-ax.set_ylabel('Y')
 ax.set_ylim(-40, 40)
-ax.set_zlabel('Z')
 ax.set_zlim(-100, 100)
 
+ax.set_xlabel('X')
+ax.set_ylabel('Y')
+ax.set_zlabel('Z')
+
 plt.show()
diff --git a/examples/mplot3d/custom_shaded_3d_surface.py b/examples/mplot3d/custom_shaded_3d_surface.py
@@ -1,13 +1,15 @@
 """
 Demonstrates using custom hillshading in a 3D surface plot.
 """
+
 from mpl_toolkits.mplot3d import Axes3D
 from matplotlib import cbook
 from matplotlib import cm
 from matplotlib.colors import LightSource
 import matplotlib.pyplot as plt
 import numpy as np
 
+# Load and format data
 filename = cbook.get_sample_data('jacksboro_fault_dem.npz', asfileobj=False)
 with np.load(filename) as dem:
     z = dem['elevation']
@@ -19,6 +21,7 @@
 region = np.s_[5:50, 5:50]
 x, y, z = x[region], y[region], z[region]
 
+# Set up plot
 fig, ax = plt.subplots(subplot_kw=dict(projection='3d'))
 
 ls = LightSource(270, 45)
diff --git a/examples/mplot3d/lines3d_demo.py b/examples/mplot3d/lines3d_demo.py
@@ -1,3 +1,7 @@
+'''
+Demonstrating plotting a parametric curve in 3D.
+'''
+
 import matplotlib as mpl
 from mpl_toolkits.mplot3d import Axes3D
 import numpy as np
@@ -7,11 +11,14 @@
 
 fig = plt.figure()
 ax = fig.gca(projection='3d')
+
+# Prepare arrays x, y, z
 theta = np.linspace(-4 * np.pi, 4 * np.pi, 100)
 z = np.linspace(-2, 2, 100)
 r = z**2 + 1
 x = r * np.sin(theta)
 y = r * np.cos(theta)
+
 ax.plot(x, y, z, label='parametric curve')
 ax.legend()
 
diff --git a/examples/mplot3d/lorenz_attractor.py b/examples/mplot3d/lorenz_attractor.py
@@ -1,42 +1,54 @@
-# Plot of the Lorenz Attractor based on Edward Lorenz's 1963 "Deterministic
-# Nonperiodic Flow" publication.
-# http://journals.ametsoc.org/doi/abs/10.1175/1520-0469%281963%29020%3C0130%3ADNF%3E2.0.CO%3B2
-#
-# Note: Because this is a simple non-linear ODE, it would be more easily
-#       done using SciPy's ode solver, but this approach depends only
-#       upon NumPy.
+'''
+Plot of the Lorenz Attractor based on Edward Lorenz's 1963 "Deterministic
+Nonperiodic Flow" publication.
+http://journals.ametsoc.org/doi/abs/10.1175/1520-0469%281963%29020%3C0130%3ADNF%3E2.0.CO%3B2
+
+Note: Because this is a simple non-linear ODE, it would be more easily
+      done using SciPy's ode solver, but this approach depends only
+      upon NumPy.
+'''
 
 import numpy as np
 import matplotlib.pyplot as plt
 from mpl_toolkits.mplot3d import Axes3D
 
 
 def lorenz(x, y, z, s=10, r=28, b=2.667):
+    '''
+    Given:
+       x, y, z: a point of interest in three dimensional space
+       s, r, b: parameters defining the lorenz attractor
+    Returns:
+       x_dot, y_dot, z_dot: values of the lorenz attractor's partial
+           derivatives at the point x, y, z
+    '''
     x_dot = s*(y - x)
     y_dot = r*x - y - x*z
     z_dot = x*y - b*z
     return x_dot, y_dot, z_dot
 
 
 dt = 0.01
-stepCnt = 10000
+num_steps = 10000
 
 # Need one more for the initial values
-xs = np.empty((stepCnt + 1,))
-ys = np.empty((stepCnt + 1,))
-zs = np.empty((stepCnt + 1,))
+xs = np.empty((num_steps + 1,))
+ys = np.empty((num_steps + 1,))
+zs = np.empty((num_steps + 1,))
 
-# Setting initial values
+# Set initial values
 xs[0], ys[0], zs[0] = (0., 1., 1.05)
 
-# Stepping through "time".
-for i in range(stepCnt):
-    # Derivatives of the X, Y, Z state
+# Step through "time", calculating the partial derivatives at the current point
+# and using them to estimate the next point
+for i in range(num_steps):
     x_dot, y_dot, z_dot = lorenz(xs[i], ys[i], zs[i])
     xs[i + 1] = xs[i] + (x_dot * dt)
     ys[i + 1] = ys[i] + (y_dot * dt)
     zs[i + 1] = zs[i] + (z_dot * dt)
 
+
+# Plot
 fig = plt.figure()
 ax = fig.gca(projection='3d')
 
diff --git a/examples/mplot3d/mixed_subplots_demo.py b/examples/mplot3d/mixed_subplots_demo.py
diff --git a/examples/mplot3d/offset_demo.py b/examples/mplot3d/offset_demo.py
diff --git a/examples/mplot3d/pathpatch3d_demo.py b/examples/mplot3d/pathpatch3d_demo.py
diff --git a/examples/mplot3d/polys3d_demo.py b/examples/mplot3d/polys3d_demo.py
