+++
title = "Configuration"
weight = 50
+++

# Plot configuration

Images in BornAgain examples are generated using the Python library
[MatPlotLib](https://matplotlib.org).

Default settings can be overridden
by function arguments or MatPlotLib ressources.

Exceptionally, [heat map](heatmap) supports an environment variable.

### Parameterization with plotargs

In the functions
```
plot_datafield(result, **plotargs)
plot_heatmap(result, **plotargs)
plot_multicurve(results, **plotargs)
plot2d_to_grid(results, ncol, **plotargs)
plot2d_to_row(results, **plotargs)
```
the placeholder `**plotargs` stands for optional keyword arguments.
These can be supplied in three ways:

(1) Directly like in
```python
    bp.plot_datafield(result, cmap='viridis', intensity_min=1e-6)
    bp.plt.show()
```

(2) Through a dictionary variable like in
```python
    plotargs = {}
    plotargs['intensity_min'] = 1e-12
    plotargs['intensity_max'] = 1e2
    bp.plot_datafield(result, **plotargs)
    bp.plt.show()
```

(3) If a script contains the lines
```python
    plotargs = bp.parse_commandline()
    bp.plot_datafield(result, **plotargs)
```

then parameters can be passed from the command line, like
```bash
python3 <script> intensity_min=1e-9
```

### Supported arguments

Supported keyword arguments include:

* `cmap`: colormap, see [heat map](heatmap).
* `figfile`: graphics output file path, see [Export](export).
* `fontsize`: font size for labels.
* `frame_aspect`: plot frame width:height ratio, see [Aspect ratio](#aspect-ratio).
* `intensity_max`: maximum intensity value for color scale.
* `intensity_min`: minimum intensity value for color scale.
* `legendloc`: legend location (for `plot_multicurve`).
* `log_range`: decades to show below maximum (for `plot2d_to_grid`).
* `normalized_cb`: normalize colorbar to 1 (for `plot2d_to_grid`).
* `spacing`: tuple (wspace, hspace) for subplot spacing (for `plot2d_to_grid`).
* `title`: plot title.
* `unit_aspect`: aspect ratio based on axis units, see [Aspect ratio](#aspect-ratio).
* `with_cb`: whether to show colorbar (default: True).
* `xlabel`: x-axis label.
* `ylabel`: y-axis label.
* `zlabel`: colorbar label (default: "Intensity").

### Aspect ratio

In 2D intensity plots, pixels are always square by default.
The aspect ratio of the plot is therefore determined by the number of
detector bins in each direction.

To override the default aspect ratio, use one of these arguments:

* `unit_aspect`: The aspect ratio is based on axis ranges only, ignoring
  the number of bins. With `unit_aspect=1`, equal axis ranges produce a
  square plot. This is the default for GISAS (scatter2d) examples.
  ```python
  bp.plot_datafield(result, unit_aspect=1)
  ```

* `frame_aspect`: Directly sets the width:height ratio of the plot frame.
  ```python
  bp.plot_datafield(result, frame_aspect=1.618)
  ```

At most one of `frame_aspect` and `unit_aspect` may be specified.
The colorbar height automatically matches the plot frame height.

For other optional arguments that may or may not be respected, see
the [MatPlotLib customizing tutorial](https://matplotlib.org/stable/tutorials/introductory/customizing.html).
