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, 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() 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 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() 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() (dict key query) and 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() 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() 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 (e.g., scatterplot(), lineplot()), a seaborn.FacetGrid (e.g., relplot(), displot()), a seaborn.JointGrid (e.g., jointplot()), or a seaborn.PairGrid (e.g., pairplot()). Dictionary keys are method names, dictionary values function arguments (use a dict to specify keyword arguments). Example (for 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(). 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.

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() (affects all plots).

suptitle: str or None, optional (default: None)

Suptitle for the plot (see 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.