Module plottools.figure

Size and file names of a figure.

Patches matplotlib to provide the following features:

Figure size in centimeters

You can specify the figure size in centimeters:

fig = plt.figure(cmsize=(20.0, 16.0))         # in cm!
fig, ax = plt.subplots(cmsize=(16.0, 10.0))   # in cm!

Default file names for figures

If no file name or only a file extension is specified in fig.savefig(), then the file name of the main script is used. So you can call

fig.savefig()

and get a 'figure.pdf' file (if the python script was called 'figure.py'). If the file name just specifies a path that ends with '/', then the name of the main script is appended:

fig.savefig('plots/')

writes the file `plots/figure.pdf'.

If the file name specified in fig.savefig() starts with a '+', then this string without the plus is added to the name of the main script. This is usefull for saving several figures for a (LaTeX beamer) talk. For example, a python script named 'example.py'

fig1.savefig('+-one')
fig2.savefig('+-two')

generates the files 'example-one.pdf' and 'example-two.pdf' (or whatever file type was specified in rcParams['savefig.format']).

A '@' character in the file name is replaced by 'A', 'B', 'C', … according to how often fig.savefig() is called from within the same figure. If the '@' is the first character of the file name, it is added to the name of the main script. So in 'example.py' we can write

fig.savefig('@')
fig.savefig('@')
latex_include_figures()

This prints to the console

\includegraphics<1>{exampleA}
\includegraphics<2>{exampleB}

and generates the respective files. By setting rcParams['savefig.counter'] (counter argument in figure_params()) to 'A', 'a', or '1', '@' in file names is replaced 'A', 'B', 'C', …, 'a', 'b', 'c', … or '1', '2', '3', …, respectively.

Strip embedded fonts from pdf file

By setting stripfonts=True in savefig() or via rcParams['pdf.stripfonts'], figures saved as pdf files are run through ps2pdf in order to remove embedded fonts. This significantly reduces the file size of the generated figure files, and is in particular useful when using LaTeX mode and including the figures in a LaTeX document.

Functions

Figure member functions

Settings

mpl.rcParams defined by the figures module:

savefig.counter: 'A'
pdf.stripfonts: False

Install/uninstall figure functions

You usually do not need to call these functions. Upon loading the figure module, install_figure() is called automatically.

Functions

def cm_size(*args)

Convert dimensions from cm to inch.

Use this function to set the size of a figure in centimeter:

fig = plt.figure(figsize=cm_size(16.0, 10.0))

Parameters

args : one or many float
Size in centimeter.

Returns

inches : float or list of floats
Input arguments converted to inch.
def set_size_cm(fig, w, h=None, forward=True)

Set the figure size in centimeters.

Parameters

fig : matplotlib figure
The figure of which to set the size.
w : float or (float, float)
If h is not specified, width and height of the figure in centimeters, otherwise the width of the figure.
h : float or None
Height of the figure in centimeters.
forward : bool
If True, the canvas size is automatically updated, e.g., you can resize the figure window from the shell.
def get_savefig_count(fig)

Number of savefig() calls on the figure.

Parameters

fig : matplotlib.figure
The figure.

Returns

counter : int
The number of calls to fig.savefig() on this figure.
def latex_include_figures()

Print LaTeX \includegraphics<>{} commands for all saved files.

This can then be copied directly into you LaTeX document to include the generated figures. For multiple files from the same figure, beamer overlay specification are printed as well.

Examples

A python script named 'intro.py'

from plottools.figure import latex_include_figures
...
fig1.savefig('@')
fig1.savefig('@')
fig2.savefig('data')
latex_include_figures()

writes to console

\includegraphics<1>{introA}
\includegraphics<2>{introB}
\includegraphics{data}
def figure_params(color=None, format=None, counter=None, dpi=None, compression=None, fonttype=None, stripfonts=None, cmsize=None)

Set figure parameter.

Only parameters that are not None are updated.

Parameters

color : matplotlib color specification or 'none'
Background color for the whole figure. Sets rcParam figure.facecolor and savefig.facecolor. For setting the background color of a specific figure, use fig.set_facecolor(color) or pass it to the plt.figure() or plt.subplots() functions via the facecolorkeyword argument.
format : 'png', 'ps', 'pdf', 'svg'
File format of the saved figure. Sets rcParam savefig.format.
counter : 'A', 'a', or '1'
Specifies how a '@' character in the file name passed to fig.savefig() is translated into a string. Sets rcParam savefig.counter.
dpi : int
For pixel graphics the number of dots per inch.
compression : int
Compression level of pdf file from 0 to 9. Sets rcParam pdf.compression.
fonttype : 3 or 42
Type 3 (Type3) or Type 42 (TrueType) fonts. Sets rcParams pdf.fonttype and ps.fonttype. Type3 use less disk space but are less well editable, Type42 use more disk space but are better editable in vector graphics software (says the internet).
stripfonts : boolean
If output file format is pdf, then run ps2pdf on the generated pdf file to strip it from embedded fonts. This might then look ugly as a standalone figure, but results in nice plots within a latex documents at a fraction of the file size. Sets rcParam pdf.stripfonts.
cmsize : tuple of floats
Default width and height of a figure in centimeters.
def install_figure()

Install functions of the figure module in matplotlib.

Patches a few matplotlib functions (plt.figure(), plt.subplots(), fig.savefig(), plt.savefig()).

See Also

uninstall_figure()

def uninstall_figure()

Uninstall all code of the figure module from matplotlib.

See Also

install_figure()

def demo()

Run a demonstration of the figure module.