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.


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()
    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.


Create a cartesian mesh plot of the data


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.


Apply a range of formatting options to the plot.


Add a legend to the axes instance.


Set the x limits on an Axes object


Set the y limits on an Axes object


Quick utility to add a colorbar to an axes object


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().


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


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.

  1. ax: ax: matplotlib.axes.Axes or None

    Ax on which to plot the data.

  2. cmap: cmap: str or None

    Valid Matplotlib colormap to apply to the plot.

  3. kwargs: kwargs:

    Addition keyword arguments to pass to

  4. 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.

  5. legend: legend: bool or str

    Automatically label the plot. Pass one of the following values to place the legend outside the plot: above, right

  6. loglog: loglog: bool

    Apply a log scale to both axes.

  7. logx: logx: bool

    Apply a log scale to x axis.

  8. logy: logy: bool

    Apply a log scale to y axis.

  9. 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:




    name of this material


    specific isotope name


    specific isotope ZZAAAI

  10. ncol: ncol: int

    Integer number of columns to apply to the legend.

  11. rax: matplotlib.axes.Axes

    Ax on which the data was plotted.

  12. sigma: sigma: int

    Confidence interval to apply to errors. If not given or 0, no errors will be drawn.

  13. title: title: str

    Title to apply to the figure.

  14. xlabel: xlabel: str or None

    Label for x-axis.

  15. ylabel: yabel: str or None

    Label for y-axis.