<a id="api-esmvaltool-diag-scripts-portrait-plot"></a>

# Portrait Plot

Portrait Plot Diagnostic.

Plot performance metrics of multiple datasets vs up to four references
A [documented example recipe](../recipes/recipe_portrait.html.md) to use this
diagnostic is provided as `recipes/recipe_portrait_CMIP.yml`.

## Description

This diagnostic provides plot functionalities for performance metrics,
and is written to be as flexible as possible to be adaptable to further use
cases. X and Y axis, grouping parameter and splits for each rectangle can be
configured in the recipe. All `*_by` parameters can be set to any metadata
key. To split by ‘reference’ this key needs to be set as extra_facet in recipe.

## Authors

- Lukas Lindenlaub (Universität Bremen, Germany)
- Diego Cammarano

## Configuration parameters through recipe:

axes_properties: dict, optional
: Dictionary that gets passed to [`matplotlib.axes.Axes.set()`](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set.html#matplotlib.axes.Axes.set).
  Subplots can be widely customized.
  E.g. xlabel, ylabel, yticklabels, xmargin…
  By default {}.

cbar_kwargs: dict, optional
: Dictionary that gets passed to `matplotlib.pyplot.colorbar()`.
  E.g. label, ticks…
  By default {}.

default_split: str, optional
: Data labeled with this string, will be used as main rectangles. All other
  splits will be plotted as overlays. This can be used to choose the base
  reference, while all references are labeled for the legend. If None, the
  first split will be used as default.
  By default None.

dpi: int, optional
: Dots per inch for the figure. By default 300.

domain: str, optional
: Domain for provenance. By default ‘global’.

figsize: tuple of float, optional
: [width, height] of the figure in inches. The final figure will be saved
  with bbox_inches=”tight”, which can change the resulting aspect ratio.
  By default [7.5, 3.5].

group_by: str, optional
: Split portrait groups into multiple groups (one matrix per group).
  By default ‘project’.

legend: dict, optional
: Customize, if, how and where the legend is plotted. The ‘best’ position
  and size of the legend depends on multiple parameters of the figure
  (i.e. lengths of labels, aspect ratio of the plots…). Might require
  manual adjustment of `x`, `y` and `size` to fit the figure layout.
  Keys (each optional) that will be handled are:
  <br/>
  position: str or None, optional
  : Position of the legend. Can be ‘right’ or ‘left’.
    Or set to None to disable plotting the legend. By default ‘right’.
  <br/>
  size: float, optional
  : Size of the legend in Inches. By default 0.3.
  <br/>
  x_offset: float, optional
  : Manually adjust horizontal position to save space or fix overlap.
    Number given in Inches. By default 0.
  <br/>
  y_offset: float, optional
  : Manually adjust vertical position to save space or fix overlap.
    Number given in Inches. By default 0.

matplotlib_rc_params: dict, optional
: Optional [`matplotlib.RcParams`](https://matplotlib.org/stable/api/matplotlib_configuration_api.html#matplotlib.RcParams) used to customize the portrait plot.
  Options given here will be passed to [`matplotlib.rc_context()`](https://matplotlib.org/stable/api/matplotlib_configuration_api.html#matplotlib.rc_context).

nan_color: str or None, optional
: Matplotlib named color or hexcode for NaN values. If set to None,
  no triangles are plotted for NaN values.
  By default ‘white’.

normalize: str or None, optional
: (‘mean’, ‘median’, ‘centered_mean’, ‘centered_median’, None).
  Divide by median or mean if not None. Subtract median/mean afterwards if
  centered.
  By default ‘centered_median’.

plot_kwargs: dict, optional
: Dictionary that gets passed as kwargs to
  [`matplotlib.axes.Axes.imshow()`](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.imshow.html#matplotlib.axes.Axes.imshow). Colormaps will be converted to 11
  discrete steps automatically.
  Default colormap is `cmap='RdYlBu_r'` with limits `vmin=-0.5` and
  `vmax=0.5`.

plot_legend: bool, optional
: If True, a legend is plotted, when multiple splits are given.
  By default True.

split_by: str, optional
: The rectangles can be split into 2-4 triangles. This is used to show
  metrics for different references. For this case there is no need to change
  this parameter. Multiple variables can be set in the recipe with `split`
  assigned as extra_facet to label the different references. Data without
  a split assigned will be plotted as main rectangles, this can be changed
  by setting default_split parameter.
  By default ‘split’.

x_by: str, optional
: Metadata key for x coordinate.
  By default ‘alias’.

y_by: str, optional
: Metadata key for y coordinate.
  By default ‘variable_group’.
