categorical variable example

choldgraf · choldgraf · commit aa88faea6fde · 2017-05-07T10:18:35.000-07:00
diff --git a/doc/api/pyplot_summary.rst b/doc/api/pyplot_summary.rst
@@ -1,14 +1,24 @@
-Plotting commands summary
-=========================
+Below we describe several common approaches to plotting with Matplotlib.
+
+.. contents::
+
+The Pyplot API
+--------------
 
 The :mod:`matplotlib.pyplot` module contains functions that allow you to generate
 many kinds of plots quickly. For examples that showcase the use
 of the :mod:`matplotlib.pyplot` module, see the
 :ref:`sphx_glr_tutorials_01_introductory_pyplot.py`
-or the :ref:`pyplots_examples`.
+or the :ref:`pyplots_examples`. We also recommend that you look into
+the object-oriented approach to plotting, described below.
+
+.. currentmodule:: matplotlib.pyplot
+
+.. autofunction:: plotting
 
 The Object-Oriented API
 -----------------------
+
 Most of these functions also exist as methods in the
 :class:`matplotlib.axes.Axes` class. You can use them with the
 so-called "Object Oriented" approach to Matplotlib.
@@ -19,11 +29,13 @@ we recommend using the object-oriented approach for more control
 and customization of your plots. For some examples of the OO approach
 to Matplotlib, see the :ref:`api_examples` examples.
 
-The Pyplot API
---------------
+Colors in Matplotlib
+--------------------
 
-.. currentmodule:: matplotlib.pyplot
+There are many colormaps you can use to map data onto color values.
+Below we list several ways in which color can be utilized in Matplotlib.
 
-.. autofunction:: plotting
+For a more in-depth look at colormaps, see the
+:ref:`sphx_glr_tutorials_colors_colormaps.py` tutorial.
 
 .. autofunction:: colormaps
diff --git a/examples/lines_bars_and_markers/categorical_variables.py b/examples/lines_bars_and_markers/categorical_variables.py
@@ -0,0 +1,25 @@
+"""
+==============================
+Plotting categorical variables
+==============================
+
+How to use categorical variables in matplotlib.
+
+Many times you want to create a plot that uses categorical variables
+in Matplotlib. For example, your data may naturally fall into
+several "bins" and you're interested in summarizing the data per
+bin. Matplotlib allows you to pass categorical variables directly to
+many plotting functions.
+"""
+import matplotlib.pyplot as plt
+
+names = ['group_a', 'group_b', 'group_c']
+values = [1, 10, 100]
+
+fig, axs = plt.subplots(1, 3, figsize=(9, 3))
+axs[0].bar(names, values)
+axs[1].scatter(names, values)
+axs[2].plot(names, values)
+fig.suptitle('Categorical Plotting')
+
+plt.show()
diff --git a/tutorials/01_introductory/pyplot.py b/tutorials/01_introductory/pyplot.py
@@ -118,6 +118,26 @@
 plt.ylabel('entry b')
 plt.show()
 
+###############################################################################
+# .. _plotting-with-categorical-vars:
+#
+# Plotting with categorical variables
+# ===================================
+#
+# It is also possible to create a plot using categorical variables
+# Matplotlib allows you to pass categorical variables directly to
+# many plotting functions. For example:
+
+names = ['group_a', 'group_b', 'group_c']
+values = [1, 10, 100]
+
+fig, axs = plt.subplots(1, 3, figsize=(9, 3))
+axs[0].bar(names, values)
+axs[1].scatter(names, values)
+axs[2].plot(names, values)
+fig.suptitle('Categorical Plotting')
+plt.show()
+
 ###############################################################################
 # .. _controlling-line-properties:
 #
