Customizing matplotlib's parameters per project

This recipe explains where the various configuration files are that matplotlib uses and why we want to use one or the other. Also, we explain what is in these configuration files.

Getting ready

If you don't want to configure matplotlib as the first step in your code every time you use it (as we did in the previous recipe), this recipe will explain how to have different default configurations of matplotlib for different projects. This way your code will not be cluttered with configuration data and, moreover, you can easily share configuration templates with your co-workers or even among other projects.

How to do it...

If you have a working project that always uses the same settings for certain parameters in matplotlib, you probably don't want to set them every time you want to add a new graph code. Instead, what you want is a permanent file, outside of your code, which sets defaults for matplotlib parameters.

matplotlib supports this via its matplotlibrc configuration file that contains most of the changeable properties of matplotlib.

How it works...

There are three different places where this file can reside and its location defines its usage. They are:

• Current working directory: This is where your code runs from. This is the place to customize matplotlib just for your current directory that might contain your current project code. The file is named matplotlibrc.
• Per user .matplotlib/matplotlibrc: This is usually in the user's $HOME directory (under Windows, this is your Documents and Settings directory). You can find out where your configuration directory is using the matplotlib.get_configdir() command. Check the next command.
• Per installation configuration file: This is usually in your Python site-packages. This is a system-wide configuration, but it will get overwritten every time you reinstall matplotlib; so, it is better to use a per user configuration file for more persistent customizations. The best usage so far for me was to use this as a default template, if I mess up my user's configuration file or if I need fresh configuration to customize for a different project.

The following one liner will print the location of your configuration directory and can be run from shell:

$ python -c 'import matplotlib as mpl; print mpl.get_configdir()'

The configuration file contains settings for:

• axes: This deals with face and edge color, tick sizes, and grid display.
• backend: This sets the target output: TkAgg and GTKAgg.
• figure: This deals with dpi, edge color, figure size, and subplot settings.
• font: This looks at font families, font size, and style settings.
• grid: This deals with grid color and line settings.
• legend: This specifies how legends and text inside will be displayed.
• lines: This checks for line (color, style, width, and so on) and markers settings.
• patch: These patches are graphical objects that fill 2D space, such as polygons and circles; set linewidth, color, antialiasing, and so on.
• savefig: There are separate settings for saved figures. For example, to make rendered files with a white background.
• text: This looks for text color, how to interpret text (plain versus latex markup) and similar.
• verbose: This checks how much information matplotlib gives during runtime: silent, helpful, debug, and debug annoying.
• xticks and yticks: These set the color, size, direction, and label size for major and minor ticks for the x and y axes.

There's more...

If you are interested in more details for every mentioned setting (and some that we did not mention here), the best place to go is the website of the matplotlib project where there is up-to-date API documentation. If it doesn't help, user and development lists are always good places to leave questions. See the back of this book for useful online resources.