matplotlib · mdboom · Nov 18, 2013 · Jul 21, 2013 · Jul 21, 2013 · Jul 21, 2013
diff --git a/doc/conf.py b/doc/conf.py
@@ -28,7 +28,8 @@
 extensions = ['matplotlib.sphinxext.mathmpl', 'sphinxext.math_symbol_table',
               'sphinx.ext.autodoc', 'matplotlib.sphinxext.only_directives',
               'sphinx.ext.doctest', 'sphinx.ext.autosummary',
-              'matplotlib.sphinxext.plot_directive', 'sphinx.ext.inheritance_diagram',
+              'matplotlib.sphinxext.plot_directive',
+              'sphinx.ext.inheritance_diagram',
               'sphinxext.gen_gallery', 'sphinxext.gen_rst',
               'matplotlib.sphinxext.ipython_console_highlighting',
               'sphinxext.github',
@@ -117,6 +118,7 @@
     ('text_labels_and_annotations', 'Text, labels, and annotations'),
     ('ticks_and_spines', 'Ticks and spines'),
     ('subplots_axes_and_figures', 'Subplots, axes, and figures'),
+    ('style_sheets', 'Style sheets'),
     ('specialty_plots', 'Specialty plots'),
     ('showcase', 'Showcase'),
     ('api', 'API'),

diff --git a/doc/users/beginner.rst b/doc/users/beginner.rst
@@ -13,6 +13,7 @@ Beginner's Guide
     :maxdepth: 2
 
     pyplot_tutorial.rst
+    style_sheets.rst
     navigation_toolbar.rst
     index_text.rst
     image_tutorial.rst

diff --git a/doc/users/style_sheets.rst b/doc/users/style_sheets.rst
@@ -0,0 +1,89 @@
+.. _style-sheets
+
+***********************************
+Customizing plots with style sheets
+***********************************
+
+
+The ``style`` package adds support for easy-to-switch plotting "styles" with
+the same parameters as a matplotlibrc_ file.
+
+There are a number of pre-defined styles provided by matplotlib. For
+example, there's a pre-defined style called "ggplot", which emulates the
+aesthetics of ggplot_ (a popular plotting package for R_). To use this style,
+just add::
+
+   >>> import matplotlib.pyplot as plt
+   >>> plt.style.use('ggplot')
+
+To list all available styles, use::
+
+   >>> print plt.style.available
+
+
+Defining your own style
+=======================
+
+You can create custom styles and use them by calling ``style.use`` with the
+path or URL to the style sheet. Alternatively, if you add your
+``<style-name>.mplstyle`` file to ``~/.matplotlib/stylelib`` (you may need to
+create this directory), you can reuse your custom style sheet with a call to
+``style.use(<style-name>)``. Note that a custom style sheet in
+``~/.matplotlib/stylelib`` will override a style sheet defined by matplotlib if
+the styles have the same name.
+
+For example, you might want to create
+``~/.matplotlib/stylelib/presentation.mplstyle`` with the following::
+
+   axes.titlesize : 24
+   axes.labelsize : 20
+   lines.linewidth : 3
+   lines.markersize : 10
+   xtick.labelsize : 16
+   ytick.labelsize : 16
+
+Then, when you want to adapt a plot designed for a paper to one that looks
+good in a presentation, you can just add::
+
+   >>> import matplotlib.pyplot as plt
+   >>> plt.style.use('presentation')
+
+
+Composing styles
+================
+
+Style sheets are designed to be composed together. So you can have a style
+sheet that customizes colors and a separate style sheet that alters element
+sizes for presentations. These styles can easily be combined by passing
+a list of styles::
+
+   >>> import matplotlib.pyplot as plt
+   >>> plt.style.use(['dark_background', 'presentation'])
+
+Note that styles further to the right will overwrite values that are already
+defined by styles on the right.
+
+
+Temporary styling
+=================
+
+If you only want to use a style for a specific block of code but don't want
+to change the global styling, the style package provides a context manager
+for limiting your changes to a specific scope. To isolate the your styling
+changes, you can write something like the following::
+
+
+   >>> import numpy as np
+   >>> import matplotlib.pyplot as plt
+   >>>
+   >>> with plt.style.context(('dark_background')):
+   >>>     plt.plot(np.sin(np.linspace(0, 2*np.pi)), 'r-o')
+   >>>
+   >>> # Some plotting code with the default style
+   >>>
+   >>> plt.show()
+
+
+.. _matplotlibrc: http://matplotlib.sourceforge.net/users/customizing.html
+.. _ggplot: http://had.co.nz/ggplot/
+.. _R: http://www.r-project.org/
diff --git a/doc/users/whats_new.rst b/doc/users/whats_new.rst
@@ -98,6 +98,26 @@ an offset will be determined such that the tick labels are
 meaningful. If `False` then the full number will be formatted in all
 conditions.
 
+``style`` package added
+```````````````````````
+You can now easily switch between different styles using the new ``style``
+package::
+
+   >>> from matplotlib import style
+   >>> style.use('dark_background')
+
+Subsequent plots will use updated colors, sizes, etc. To list all available
+styles, use::
+
+   >>> print style.available
+
+You can add your own custom ``<style name>.mplstyle`` files to
+``~/.matplotlib/stylelib`` or call ``use`` with a URL pointing to a file with
+``matplotlibrc`` settings.
+
+*Note that this is an experimental feature*, and the interface may change as
+users test out this new feature.
+
 .. _whats-new-1-3:
 
 new in matplotlib-1.3

diff --git a/examples/style_sheets/plot_dark_background.py b/examples/style_sheets/plot_dark_background.py
@@ -0,0 +1,23 @@
+"""
+This example demonstrates the "dark_background" style, which uses white for
+elements that are typically black (text, borders, etc). Note, however, that not
+all plot elements default to colors defined by an rc parameter.
+
+"""
+import numpy as np
+import matplotlib.pyplot as plt
+
+
+plt.style.use('dark_background')
+
+L = 6
+x = np.linspace(0, L)
+ncolors = len(plt.rcParams['axes.color_cycle'])
+shift = np.linspace(0, L, ncolors, endpoint=False)
+for s in shift:
+    plt.plot(x, np.sin(x + s), 'o-')
+plt.xlabel('x-axis')
+plt.ylabel('y-axis')
+plt.title('title')
+
+plt.show()
diff --git a/examples/style_sheets/plot_ggplot.py b/examples/style_sheets/plot_ggplot.py
@@ -0,0 +1,50 @@
+"""
+This example demonstrates the "ggplot" style, which adjusts the style to
+emulate ggplot_ (a popular plotting package for R_).
+
+These settings were shamelessly stolen from [1]_ (with permission).
+
+.. [1] http://www.huyng.com/posts/sane-color-scheme-for-matplotlib/
+
+.. _ggplot: http://had.co.nz/ggplot/
+.. _R: http://www.r-project.org/
+
+"""
+import numpy as np
+import matplotlib.pyplot as plt
+
+plt.style.use('ggplot')
+
+fig, axes = plt.subplots(ncols=2, nrows=2)
+ax1, ax2, ax3, ax4 = axes.ravel()
+
+# scatter plot (Note: `plt.scatter` doesn't use default colors)
+x, y = np.random.normal(size=(2, 200))
+ax1.plot(x, y, 'o')
+
+# sinusoidal lines with colors from default color cycle
+L = 2*np.pi
+x = np.linspace(0, L)
+ncolors = len(plt.rcParams['axes.color_cycle'])
+shift = np.linspace(0, L, ncolors, endpoint=False)
+for s in shift:
+    ax2.plot(x, np.sin(x + s), '-')
+ax2.margins(0)
+
+# bar graphs
+x = np.arange(5)
+y1, y2 = np.random.randint(1, 25, size=(2, 5))
+width = 0.25
+ax3.bar(x, y1, width)
+ax3.bar(x+width, y2, width, color=plt.rcParams['axes.color_cycle'][2])
+ax3.set_xticks(x+width)
+ax3.set_xticklabels(['a', 'b', 'c', 'd', 'e'])
+
+# circles with colors from default color cycle
+for i, color in enumerate(plt.rcParams['axes.color_cycle']):
+    xy = np.random.normal(size=2)
+    ax4.add_patch(plt.Circle(xy, radius=0.3, color=color))
+ax4.axis('equal')
+ax4.margins(0)
+
+plt.show()
diff --git a/examples/style_sheets/plot_grayscale.py b/examples/style_sheets/plot_grayscale.py
@@ -0,0 +1,32 @@
+"""
+This example demonstrates the "grayscale" style sheet, which changes all colors
+that are defined as rc parameters to grayscale. Note, however, that not all
+plot elements default to colors defined by an rc parameter.
+
+"""
+import numpy as np
+import matplotlib.pyplot as plt
+
+
+def color_cycle_example(ax):
+    L = 6
+    x = np.linspace(0, L)
+    ncolors = len(plt.rcParams['axes.color_cycle'])
+    shift = np.linspace(0, L, ncolors, endpoint=False)
+    for s in shift:
+        ax.plot(x, np.sin(x + s), 'o-')
+
+def image_and_patch_example(ax):
+    ax.imshow(np.random.random(size=(20, 20)), interpolation='none')
+    c = plt.Circle((5, 5), radius=5, label='patch')
+    ax.add_patch(c)
+
+
+plt.style.use('grayscale')
+
+fig, (ax1, ax2) = plt.subplots(ncols=2)
+
+color_cycle_example(ax1)
+image_and_patch_example(ax2)
+
+plt.show()