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

# Seaborn Diagnostic

Create arbitrary Seaborn plots.

## Description

This diagnostic provides a high-level interface to Seaborn. For this, the input
data is arranged into a single [`pandas.DataFrame`](https://pandas.pydata.org/pandas-docs/dev/reference/api/pandas.DataFrame.html#pandas.DataFrame), which is then used as
input for the Seaborn function defined by the option seaborn_func.

## Caveats

All datasets of a given variable must have the same units (e.g., it is not
allowed to use datasets with units K and datasets with units °C for the
variable tas).

## Author

Manuel Schlund (DLR, Germany)

## Configuration options in recipe

add_ancillary_variables: bool, optional (default: False)
: Add [`ancillary_variables()`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.Cube.ancillary_variables) to the main data frame.
  Note that this will assume that ancillary variables are identical across
  cubes within a group (see option groupby_facet). This equality is not
  checked!

add_aux_coords: bool, optional (default: False)
: Add [`aux_coords`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.Cube.aux_coords) to the main data frame. Note that
  this will assume that auxiliary coordinates are identical across cubes
  within a group (see option groupby_facet). This equality is not checked!

add_cell_measures: bool, optional (default: False)
: Add [`cell_measures()`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.Cube.cell_measures) to the main data frame. Note that
  this will assume that cell measures are identical across cubes within a
  group (see option groupby_facet). This equality is not checked!

data_frame_ops: dict, optional
: Perform additional operations on the main data frame. Allowed operations
  are [`pandas.DataFrame.query()`](https://pandas.pydata.org/pandas-docs/dev/reference/api/pandas.DataFrame.query.html#pandas.DataFrame.query) (dict key query) and
  [`pandas.DataFrame.eval()`](https://pandas.pydata.org/pandas-docs/dev/reference/api/pandas.DataFrame.eval.html#pandas.DataFrame.eval) (dict key eval). Operations are defined by
  strings (dict values). Examples: `{'query': 'latitude > 80', 'eval':
  'longitude = longitude - 180.0'}`.

dropna_kwargs: dict, optional
: Optional keyword arguments for [`pandas.DataFrame.dropna()`](https://pandas.pydata.org/pandas-docs/dev/reference/api/pandas.DataFrame.dropna.html#pandas.DataFrame.dropna) to drop
  missing values in the input data. If not given, do not drop NaNs. Note:
  NaNs are dropped after potential data_frame_ops.

facets_as_columns: list of str, optional
: Facets that will be added as a columns to the main data frame. Values for
  these facets must be identical across all datasets within a group (see
  option groupby_facet).

groupby_facet: str, optional (default: ‘alias’)
: Facet which is used to group input datasets when creating the main data
  frame. All datasets within a group are expected to have the same index
  after calling [`iris.pandas.as_data_frame()`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.pandas.html#iris.pandas.as_data_frame) on them. These datasets
  within a group will then get merged (combined along axis 1, i.e., columns)
  into a single data frame per group. Finally, the data frames for all groups
  are concatenated (combined along axis 0, i.e., rows) into one main data
  frame. groupby_facet is also added as a column to this main data frame.

legend_title: str, optional (default: None)
: Title for legend. If `None`, Seaborn will determine the legend title (if
  possible).

plot_filename: str, optional
: Filename for the final plot. By default, uses ‘seaborn_(seaborn_func)’.

plot_object_methods: dict, optional
: Execute methods of the object returned by the plotting function
  (seaborn_func). This object will either be a
  [`matplotlib.axes.Axes`](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes) (e.g., [`scatterplot()`](https://seaborn.pydata.org/generated/seaborn.scatterplot.html#seaborn.scatterplot),
  [`lineplot()`](https://seaborn.pydata.org/generated/seaborn.lineplot.html#seaborn.lineplot)), a [`seaborn.FacetGrid`](https://seaborn.pydata.org/generated/seaborn.FacetGrid.html#seaborn.FacetGrid) (e.g.,
  [`relplot()`](https://seaborn.pydata.org/generated/seaborn.relplot.html#seaborn.relplot), [`displot()`](https://seaborn.pydata.org/generated/seaborn.displot.html#seaborn.displot)), a
  [`seaborn.JointGrid`](https://seaborn.pydata.org/generated/seaborn.JointGrid.html#seaborn.JointGrid) (e.g., [`jointplot()`](https://seaborn.pydata.org/generated/seaborn.jointplot.html#seaborn.jointplot)), or a
  [`seaborn.PairGrid`](https://seaborn.pydata.org/generated/seaborn.PairGrid.html#seaborn.PairGrid) (e.g., [`pairplot()`](https://seaborn.pydata.org/generated/seaborn.pairplot.html#seaborn.pairplot)). Dictionary
  keys are method names, dictionary values function arguments (use a
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) to specify keyword arguments). Example (for
  [`relplot()`](https://seaborn.pydata.org/generated/seaborn.relplot.html#seaborn.relplot)): `{'set': {'xlabel': 'X [km]'}, 'set_titles':
  'Model {col_name}'}`.

reset_index: bool, optional (default: False)
: Put coordinate information of datasets into columns instead of (multi-)
  indices. This avoids the deletion of coordinate information if different
  groups of datasets have different dimensions but increases the memory
  footprint of this diagnostic.

write_netcdf: bool, optional (default: False)
: Output netCDF file for plotted data. What is written into the file
  is decided based on the pandas data frame and the
  seaborn kwargs: “x”, “y”, “hue” and “col”.
  Because there is no direct way to write panda data frames into netCDF
  and to make data CF complient, the data frame is converted to an iris
  CubeList first. This is not possible for all data frames and often
  reset_index: true is required. Therefore the default is set to False.

savefig_kwargs: dict, optional
: Optional keyword arguments for [`matplotlib.pyplot.savefig()`](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.savefig.html#matplotlib.pyplot.savefig). By
  default, uses `bbox_inches: tight, dpi: 300, orientation: landscape`.

seaborn_func: str
: Function used to plot the data. Must be a function of Seaborn. An overview
  of Seaborn’s plotting functions is given [here](https://seaborn.pydata.org/tutorial/function_overview.html).

seaborn_kwargs: dict, optional
: Optional keyword arguments for the plotting function given by
  seaborn_func. Must not include an argument called data. Example:
  `{'x': 'variable_1', 'y': 'variable_2', 'hue': 'coord_1'}`. Note:
  variables (here: variable_1 and variable_2 are identified by their
  variable_group in the recipe, i.e., the keys that specify variable groups
  in variables.

seaborn_settings: dict, optional
: Options for [`seaborn.set_theme()`](https://seaborn.pydata.org/generated/seaborn.set_theme.html#seaborn.set_theme) (affects all plots).

suptitle: str or None, optional (default: None)
: Suptitle for the plot (see [`matplotlib.pyplot.suptitle()`](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.suptitle.html#matplotlib.pyplot.suptitle)). If
  `None`, do not create a suptitle. If the plot shows only a single panel,
  use plot_object_methods with `{'set': {'title': 'TITLE'}}` instead.
