Plotting¶

Many of the readers and containers in this project have plot routines to quickly visualize relevant data. The goal for these plots is to quickly provide presentation-worthy plots by default, with options for formatting via additional arguments. This document serves as a guide for writing plot functions that have a cohesive syntax across the project and require little to no knowledge of matplotlib to make a fantastic plot.

Note

Plot functions should contain sufficient formatting such that, with minimal user input, processional and publishable plots are produced.

This cohesion is accomplished by decorating plot routines with the magicPlotDocDecorator() and by supporting a collection of additional arguments used for formatting the plot. These magic strings are detailed in Magic Plot Decorator Options and can be included in any function decorated by magicPlotDocDecorator() as {legend}.

When appropriate, plot functions should accept a matplotlib.axes.Axes argument on which to plot the data. This is useful for subplotting, or for creating a plot and then continuing the plotting inside this function. If not given, the function should create a new matplotlib.axes.Axes object. All plotting should be done on this axes object, such as:

def plot(ax=None):
    ax = ax or pyplot.axes()
    ax.plot([1,2,3])
    return ax

By returning the axes object, users can further apply labels, place the plot into subplots, or more.

Axes for all plots should be labeled without user intervention, but should support user-defined labels. This process can be expedited by utilizing formatPlot() as the last stage of the plotting process. This function accepts a variety of keyword arguments that are used to set axis labels or scaling, even placing the legend outside the plot. Taking the simple plot method from above, we can modify this method to accept user arguments for labels, but also have default labels should the user not provide them:

def plot(ax=None, xlabel=None, ylabel=None):
    ax = ax or pyplot.axes()
    ax.plot([1, 2, 3])
    xlabel = xlabel or "Default x label"
    ax = formatPlot(ax, xlabel=xlabel,
                    ylabel=ylabel or "Y axis")
    return ax

Plotting Utilities¶

Plot Functions¶

The serpentTools.plot module contains some functions to assist in plotting and for describing plot functions. These are not required for use, but their behavior, and the advice given in Plotting, should be followed. This will yield a consistent and flexible plotting environment to the user without having to dive deep into the matplotlib framework.

`cartMeshPlot`	Create a cartesian mesh plot of the data
`plot`	Shortcut plot for plotting series of labeled data onto a plot

Plot Formatters¶

The following functions can be used to tidy up a plot given our wide-range of supported arguments.

`formatPlot`	Apply a range of formatting options to the plot.
`placeLegend`	Add a legend to the axes instance.
`setAx_xlims`	Set the x limits on an Axes object
`setAx_ylims`	Set the y limits on an Axes object
`addColorbar`	Quick utility to add a colorbar to an axes object
`normalizerFactory`	Construct and return a `Normalize` for this data

Docstring Formatters for Plots¶

Many of the plot routines accept common parameters, such as logx for applying a log scale to the x-axis. To reduce the amount of repeated code, the following formatting functions operate on the docstrings of a plot function/method and save a lot of extra code.

See Magic Plot Decorator Options for a listing of what is replaced by what when calling serpentTools.plot.magicPlotDocDecorator().

serpentTools.utils.docstrings.magicPlotDocDecorator(f)¶

Decorator that replaces a lot magic strings used in plot functions.

Allows docstrings to contain keyword that will be replaced with a valid and proper explanation of the keyword. Keywords must be wrapped in single brackets, i.e. {x}

Magic Plot Decorator Options¶

Note

These keyword arguments should only be used when they are appropriate for the specific plot method. Colormaps don’t really make sense for line plots, but can be very useful for 2D contour and mesh plots. cmap should be a supported argument for most of these plot types, but not for line plots, unless it makes sense to do such.

ax: ax: matplotlib.axes.Axes or None
Ax on which to plot the data.
cmap: cmap: str or None
Valid Matplotlib colormap to apply to the plot.
kwargs: kwargs:
Addition keyword arguments to pass to
labels: labels: None or iterable
Labels to apply to each line drawn. This can be used to identify which bin is plotted as what line.
legend: legend: bool or str
Automatically label the plot. Pass one of the following values to place the legend outside the plot: above, right
loglog: loglog: bool
Apply a log scale to both axes.
logx: logx: bool
Apply a log scale to x axis.
logy: logy: bool
Apply a log scale to y axis.
matLabelFmt: labelFmt: str or None
Formattable string for labeling the individual plots. If not given, just label as isotope name, e.g. 'U235'. Will make the following substitutions on the labelFmt string, if given:

Keyword

Replacement

'mat'

name of this material

'iso'

specific isotope name

'zai'

specific isotope ZZAAAI
ncol: ncol: int
Integer number of columns to apply to the legend.
rax: matplotlib.axes.Axes
Ax on which the data was plotted.
sigma: sigma: int
Confidence interval to apply to errors. If not given or 0, no errors will be drawn.
title: title: str
Title to apply to the figure.
xlabel: xlabel: str or None
Label for x-axis.
ylabel: yabel: str or None
Label for y-axis.

Keyword	Replacement
`'mat'`	name of this material
`'iso'`	specific isotope name
`'zai'`	specific isotope ZZAAAI