BornAgain ≻ git-develop ≻ Documentation ≻ Reference ≻ Plotting ≻ Configuration

Plot configuration

Pass each plotting function its own named options. Its docstring, available through help(), describes the exact parameters and defaults. The rules below help when combining several plots.

Subplots, labels, and styles

Pass ax to draw into a subplot you created. The single-field and curve helpers (plot_datafield, plot_array, plot_heatmap, plot_curve, and plot_multicurve) preserve its font sizes unless you supply fontsize; without ax, they use size 16. Curve helpers also preserve the tick directions of a supplied subplot.

For these functions, xlabel=None and ylabel=None choose automatic axis labels; an empty string clears the corresponding label.

For curves, use lineargs for simulated lines and pointargs for measured points and error bars:

ba.plot_curve(
    simulated, measured=experimental,
    lineargs={'linestyle': '--'}, pointargs={'markersize': 3})

plot_material_profile accepts line styles directly, for example linewidth=2. Row and grid helpers create their own subplots and use size 16 unless another fontsize is supplied.

Legends and colorbars

Curve helpers create a legend when ax is omitted. For several calls on one subplot, pass ax each time and finish with ax.legend(). with_legend overrides automatic legend creation.

A single heat map gets a colorbar by default when ax is omitted. Use with_cb=True to request one on a supplied subplot. zlabel sets its label; zlabel="" leaves it unlabelled. Rows and grids share one colorbar.

Intensity range

intensity_min and intensity_max set vertical limits for curves or color limits for heat maps. log_range sets the number of decades below the upper limit; an explicit intensity_min takes precedence.

With no range options, curves use MatPlotLib autoscaling or the caller’s fixed limits. A single heat map spans six decades below its data maximum; rows and grids span eight below their common maximum.

Curve scales are logarithmic by default. Use yscale='linear' on plot_curve or plot_multicurve for signed values. log_range applies only to logarithmic curves; it does not change the scale.

For a custom heat-map color scale, pass norm instead of intensity limits. See Heat map for sharing a scale across separate plots.

Aspect ratio

By default, 2D plots draw square pixels, so their shape follows the number of detector bins. To control it, choose one of:

  • unit_aspect=1: equal physical distances along the two axes have equal displayed lengths.
  • frame_aspect=1: the data area is square, independent of the physical ranges and bin counts.

Do not combine unit_aspect and frame_aspect. Other positive values select other aspect ratios.

Command-line options

parse_commandline reads supplied key=value arguments into a dictionary, converting numeric values to integers or floating-point numbers. Use it when a script should accept plot options without editing its source:

plotargs = ba.parse_commandline()
figfile = plotargs.pop('figfile', None)
ba.plot_datafield(result, **plotargs)
ba.export(figfile)

figfile belongs to export, not to the plotting function. For example:

python3 script.py fontsize=12 intensity_min=1e-9 figfile=result.svg

Only pass options accepted by the function that receives them. For boolean options, use 0 or 1. Supply objects such as subplots and normalizations directly in Python.