Base Plot Configuration Pool#

This page documents utopya’s base plot configuration pool which is used for aggregating a plot configuration using multiple inheritance.

The entries below are sorted by segments and are using dantro’s naming convention. Some sections are still empty, meaning that utopya does not define new entries there.

Note

Important: All entries here are in addition to the dantro base plots configuration pool.

More precisely, the utopya base plots config pool requires the dantro base plots config, as it inherits some entries using based_on.

Hint

To quickly search for individual entries, the search functionality of your browser (Cmd + F) may be very helpful. Note that some entries (like those of the YAML anchors) may only be found if the complete file reference is expanded.

.defaults: default entries#

# This section defines defaults that are (meant to be) used in all plots.
# These find their way into the plot configuration via the `.creator` configs.

# .. Aggregated defaults ......................................................
.defaults:
  based_on:
    - .defaults  # dantro .defaults
    - .defaults.style
    - .defaults.file_ext


# .. Individual defaults ......................................................
.defaults.style:
  based_on: .defaults.style

.defaults.file_ext:
  file_ext: pdf

.creator: selecting a plot creator#

More information: Plot Creators

.creator.base:
  based_on:
    - .creator.base
    - .defaults

.creator.pyplot:
  based_on:
    - .creator.pyplot
    - .defaults

.creator.universe:
  based_on:
    - .creator.universe
    - .defaults

.creator.multiverse:
  based_on:
    - .creator.multiverse
    - .defaults

.plot: selecting a plot function#

More information:

# -- Cellular Automaton plots -------------------------------------------------
# A plot function specialized for Cellular Automata snapshots or animations.
# Unlike its predecessor, it supports the data transformation framework.
.plot.ca:
  based_on:
    - .animation.defaults

  module: !add [*utopya_plots, .ca]
  plot_func: caplot

  compute_only: all

  default_imshow_kwargs:
    interpolation: 'none'

  suptitle_fstr: "{}: {:>5}"
  suptitle_kwargs:
    fontsize: x-large
    fontfamily: monospace

  style:
    figure.constrained_layout.use: true

.plot.ca.snapshot:
  based_on:
    # - .plot.ca  # do not inherit again, would cause overwriting downstream
    - .animation.disabled

  frames_isel: -1




# -- ABM plots ----------------------------------------------------------------
# A plot function specialized for ABMs: snapshots or animations of agents
# embedded in a spatial (2D) domain.
.plot.abm:
  based_on:
    - .animation.defaults

  module: !add [*utopya_plots, .abm]
  plot_func: abmplot

  compute_only: all

  suptitle_fstr: "{dim:} = {val:>5}"
  suptitle_kwargs:
    fontsize: x-large
    fontfamily: monospace

  style:
    figure.constrained_layout.use: true

  helpers:
    save_figure:
      bbox_inches: ~

.plot.abm.snapshot:
  based_on:
    # - .plot.abm  # do not inherit again, would cause overwriting downstream
    - .animation.disabled

  frames_isel: -1






# -- FacetGrid extensions -----------------------------------------------------

.plot.facet_grid.imshow_hexagonal:
  based_on: .plot.facet_grid
  kind: imshow_hexagonal

  style:
    axes.grid: false



# -- Seaborn plots ------------------------------------------------------------
.plot.snsplot:
  module: !add [*utopya_plots, .snsplot]
  plot_func: snsplot



# -- Graph plots --------------------------------------------------------------
.plot.graph:
  module: !add [*utopya_plots, .graph]
  plot_func: draw_graph

  graph_drawing:
    nodes:
      colorbar:
        fraction: 0.05
        pad: 0.02
    edges:
      colorbar:
        fraction: 0.05
        pad: 0.02



# -- Distributions ------------------------------------------------------------
.plot.histogram:
  module: !add [*utopya_plots, .distributions]
  plot_func: histogram




# -- A (non-faceting) time series plot ----------------------------------------
# NOTE Use .plot.facet_grid.line for a more general implementation
.plot.time_series:
  module: !add [*utopya_plots, .time_series]
  plot_func: time_series



# -- Bifurcation diagrams -----------------------------------------------------
# NOTE This is not a DAG-based plot
.plot.bifurcation_diagram:
  based_on:
    - .creator.multiverse

  module: !add [*utopya_plots, .attractor]
  plot_func: bifurcation_diagram

  analysis_kwargs: ~

  # Disable grid
  style:
    axes.grid: false



# -- Benchmark plots ----------------------------------------------------------
# These are ready-to-use with minimal input

# A multiverse plot of total run times
# TODO Fix barplot stuff and make it prettier
.plot.benchmark.total:
  based_on:
    - .creator.multiverse
    - .plot.snsplot

  dag_options:
    define:
      model_name: SET_MODEL_NAME_IN_YOUR_PLOT_CONFIG

      rotate_x_ticklabels:
        - lambda: "lambda ax: ax.xaxis.set_tick_params(rotation=90)"

  select_and_combine:
    fields:
      data:
        path: data
        transform:
          - getitem: [!dag_prev , !dag_tag model_name]
          - getitem: [!dag_prev , benchmark]
          - getitem: [!dag_prev , total]

  sns_kind: catplot

  free_indices: [total]
  optional_free_indices: [seed]

  auto_encoding: true
  x: label
  y: total

  # kind: bar  # FIXME this does not work, probably need different indexing ...

  helpers:
    set_labels:
      x: " "
      y: total walltime [s]
    set_limits:
      y: [0, ~]
    call:
      functions:
        - function: !dag_result rotate_x_ticklabels
          pass_axis_object_as: ax


# A multiverse plot of cumulative run times
.plot.benchmark.cumulative:
  based_on:
    - .creator.multiverse
    - .plot.facet_grid.line
    - .plot.facet_grid.with_auto_encoding
    - .hlpr.limits.x.min_max
    - .hlpr.limits.y.from_zero

  dag_options:
    define:
      model_name: SET_MODEL_NAME_IN_YOUR_PLOT_CONFIG

  select_and_combine:
    fields:
      data:
        path: data
        transform:
          - getitem: [!dag_prev , !dag_tag model_name]
          - getitem: [!dag_prev , benchmark]
          - getitem: [!dag_prev , cumulative]

  x: n_iterations

  helpers:
    set_labels:
      x: time [#iterations]
      y: cumulative walltime [s]



# -- DEPRECATED PLOTS ---------------------------------------------------------
# NOTE This is the legacy plot function, will be removed; use .plot.ca instead!
.ca.state:
  based_on:
    - .creator.universe  # does not work with anything else
    - .animation.disabled

  module: !add [*utopya_plots, .ca]
  plot_func: state

  file_ext: pdf

  default_imshow_kwargs:
    interpolation: 'none'

  # Can use constrained layout, because axis labels don't change
  style:
    figure.constrained_layout.use: true



# .. .ca.state specializations for different animation writers ................
.ca.state.anim_frames:
  based_on:
    - .ca.state
    - .animation.frames

  time_idx: 0  # ignored in animations, but required

.ca.state.anim_ffmpeg:
  based_on:
    - .ca.state
    - .animation.ffmpeg

  time_idx: 0  # ignored in animations, but required

.style: choosing plot style#

More information: Adjusting a Plot’s Style

# More information:
#   https://matplotlib.org/gallery/style_sheets/style_sheets_reference.html
#   https://matplotlib.org/stable/tutorials/introductory/customizing.html


.style.no_spines:
  style:
    axes.spines.left: false
    axes.spines.right: false
    axes.spines.bottom: false
    axes.spines.top: false

.hlpr: invoking individual plot helper functions#

More information: The PlotHelper

.animation: controlling animation#

More information: Animations

.animation.defaults:
  based_on:
    - .animation.defaults  # from dantro
    - .animation.high_dpi  # from dantro


# Aliases (with slightly different names) for setting the animation writer
# and enabling animation. Unlike those in dantro, these *include* the defaults.
.animation.ffmpeg:
  based_on:
    - .animation.defaults
    - .animation.enabled
    - .animation.use_ffmpeg

.animation.frames:
  based_on:
    - .animation.defaults
    - .animation.enabled
    - .animation.use_frames

.dag: configuring the DAG framework#

More information:

# -- Options ------------------------------------------------------------------
# .. Aggregated DAG default options ...........................................
.dag.defaults:
  based_on: .dag.defaults



# -- Visualization ------------------------------------------------------------
# Parameters controlling DAG visualization
.dag.vis.defaults:
  based_on: .dag.vis.defaults



# -- Definitions --------------------------------------------------------------
# The entries below set certain tags using the `dag_options.define` argument.
# This should not be confused with the .dag.meta_ops defined below.

.dag.define.defaults:
  based_on: .dag.define.defaults


# The code constants from matplotlib.path.Path, used for defining paths
.dag.define.mpl.Path.codes:
  dag_options:
    define:
      STOP:
        - import: [matplotlib.path, Path]
        - getattr: [!dag_prev , STOP]
      MOVETO:
        - import: [matplotlib.path, Path]
        - getattr: [!dag_prev , MOVETO]
      LINETO:
        - import: [matplotlib.path, Path]
        - getattr: [!dag_prev , LINETO]
      CURVE3:
        - import: [matplotlib.path, Path]
        - getattr: [!dag_prev , CURVE3]
      CURVE4:
        - import: [matplotlib.path, Path]
        - getattr: [!dag_prev , CURVE4]
      CLOSEPOLY:
        - import: [matplotlib.path, Path]
        - getattr: [!dag_prev , CLOSEPOLY]

.dag.meta_ops: meta operations#

The following entries can be included into a plot configuration to make pre-defined meta-operations available for the data transformation framework.

# The following entries can be included into a plot configuration to make
# certain meta-operations available for the data transformation framework.

Complete File Reference#

# This file provides the base plot configuration pool for utopya
#
# It assumes that the dantro base plot configuration pool is available:
#     https://dantro.readthedocs.io/en/latest/plotting/base_plots.html
#
# Many base plot config entries here inherit from existing dantro base plot
# config entries of the same name. This is to allow overwriting of some of the
# default values, e.g. for the `.creator.<name>` entries.
#
# For the plot functions defined here in utopya, additional entries of the form
# `.plot.<name>` are added.
#
# There is room to add more configurations here; they should be sorted into the
# respective sections and adhere to the naming conventions (see dantro docs).
---
# YAML variable definitions that are used below to avoid repetition
_:
  variables:
    dantro_plots:       &dantro_plots           dantro.plot.funcs
    plots_module:       &utopya_plots           utopya.eval.plots

  aesthetics:
    hvline: &style_hvline
      linestyle: solid
      color: grey
      alpha: .4
      linewidth: 2.
      zorder: -42

    # Defaults for a colorbar
    # https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.colorbar.html
    cbar_kwargs: &cbar_kwargs
      shrink: .65
      aspect: 30
      orientation: vertical
      pad: 0.05



# =============================================================================
#  ╔╦╗╔═╗╔═╗╔═╗╦ ╦╦ ╔╦╗╔═╗
#   ║║║╣ ╠╣ ╠═╣║ ║║  ║ ╚═╗
#  ═╩╝╚═╝╚  ╩ ╩╚═╝╩═╝╩ ╚═╝
# =============================================================================
# start: .defaults
# This section defines defaults that are (meant to be) used in all plots.
# These find their way into the plot configuration via the `.creator` configs.

# .. Aggregated defaults ......................................................
.defaults:
  based_on:
    - .defaults  # dantro .defaults
    - .defaults.style
    - .defaults.file_ext


# .. Individual defaults ......................................................
.defaults.style:
  based_on: .defaults.style

.defaults.file_ext:
  file_ext: pdf







# =============================================================================
#  ╔═╗╦  ╔═╗╔╦╗  ╔═╗╦═╗╔═╗╔═╗╔╦╗╔═╗╦═╗╔═╗
#  ╠═╝║  ║ ║ ║   ║  ╠╦╝║╣ ╠═╣ ║ ║ ║╠╦╝╚═╗
#  ╩  ╩═╝╚═╝ ╩   ╚═╝╩╚═╚═╝╩ ╩ ╩ ╚═╝╩╚═╚═╝
# =============================================================================
# start: .creator
.creator.base:
  based_on:
    - .creator.base
    - .defaults

.creator.pyplot:
  based_on:
    - .creator.pyplot
    - .defaults

.creator.universe:
  based_on:
    - .creator.universe
    - .defaults

.creator.multiverse:
  based_on:
    - .creator.multiverse
    - .defaults





# =============================================================================
#  ╔═╗╦  ╔═╗╔╦╗  ╔═╗╦ ╦╔╗╔╔═╗╔╦╗╦╔═╗╔╗╔╔═╗
#  ╠═╝║  ║ ║ ║   ╠╣ ║ ║║║║║   ║ ║║ ║║║║╚═╗
#  ╩  ╩═╝╚═╝ ╩   ╚  ╚═╝╝╚╝╚═╝ ╩ ╩╚═╝╝╚╝╚═╝
# =============================================================================
# start: .plot
# -- Cellular Automaton plots -------------------------------------------------
# A plot function specialized for Cellular Automata snapshots or animations.
# Unlike its predecessor, it supports the data transformation framework.
.plot.ca:
  based_on:
    - .animation.defaults

  module: !add [*utopya_plots, .ca]
  plot_func: caplot

  compute_only: all

  default_imshow_kwargs:
    interpolation: 'none'

  suptitle_fstr: "{}: {:>5}"
  suptitle_kwargs:
    fontsize: x-large
    fontfamily: monospace

  style:
    figure.constrained_layout.use: true

.plot.ca.snapshot:
  based_on:
    # - .plot.ca  # do not inherit again, would cause overwriting downstream
    - .animation.disabled

  frames_isel: -1




# -- ABM plots ----------------------------------------------------------------
# A plot function specialized for ABMs: snapshots or animations of agents
# embedded in a spatial (2D) domain.
.plot.abm:
  based_on:
    - .animation.defaults

  module: !add [*utopya_plots, .abm]
  plot_func: abmplot

  compute_only: all

  suptitle_fstr: "{dim:} = {val:>5}"
  suptitle_kwargs:
    fontsize: x-large
    fontfamily: monospace

  style:
    figure.constrained_layout.use: true

  helpers:
    save_figure:
      bbox_inches: ~

.plot.abm.snapshot:
  based_on:
    # - .plot.abm  # do not inherit again, would cause overwriting downstream
    - .animation.disabled

  frames_isel: -1






# -- FacetGrid extensions -----------------------------------------------------

.plot.facet_grid.imshow_hexagonal:
  based_on: .plot.facet_grid
  kind: imshow_hexagonal

  style:
    axes.grid: false



# -- Seaborn plots ------------------------------------------------------------
.plot.snsplot:
  module: !add [*utopya_plots, .snsplot]
  plot_func: snsplot



# -- Graph plots --------------------------------------------------------------
.plot.graph:
  module: !add [*utopya_plots, .graph]
  plot_func: draw_graph

  graph_drawing:
    nodes:
      colorbar:
        fraction: 0.05
        pad: 0.02
    edges:
      colorbar:
        fraction: 0.05
        pad: 0.02



# -- Distributions ------------------------------------------------------------
.plot.histogram:
  module: !add [*utopya_plots, .distributions]
  plot_func: histogram




# -- A (non-faceting) time series plot ----------------------------------------
# NOTE Use .plot.facet_grid.line for a more general implementation
.plot.time_series:
  module: !add [*utopya_plots, .time_series]
  plot_func: time_series



# -- Bifurcation diagrams -----------------------------------------------------
# NOTE This is not a DAG-based plot
.plot.bifurcation_diagram:
  based_on:
    - .creator.multiverse

  module: !add [*utopya_plots, .attractor]
  plot_func: bifurcation_diagram

  analysis_kwargs: ~

  # Disable grid
  style:
    axes.grid: false



# -- Benchmark plots ----------------------------------------------------------
# These are ready-to-use with minimal input

# A multiverse plot of total run times
# TODO Fix barplot stuff and make it prettier
.plot.benchmark.total:
  based_on:
    - .creator.multiverse
    - .plot.snsplot

  dag_options:
    define:
      model_name: SET_MODEL_NAME_IN_YOUR_PLOT_CONFIG

      rotate_x_ticklabels:
        - lambda: "lambda ax: ax.xaxis.set_tick_params(rotation=90)"

  select_and_combine:
    fields:
      data:
        path: data
        transform:
          - getitem: [!dag_prev , !dag_tag model_name]
          - getitem: [!dag_prev , benchmark]
          - getitem: [!dag_prev , total]

  sns_kind: catplot

  free_indices: [total]
  optional_free_indices: [seed]

  auto_encoding: true
  x: label
  y: total

  # kind: bar  # FIXME this does not work, probably need different indexing ...

  helpers:
    set_labels:
      x: " "
      y: total walltime [s]
    set_limits:
      y: [0, ~]
    call:
      functions:
        - function: !dag_result rotate_x_ticklabels
          pass_axis_object_as: ax


# A multiverse plot of cumulative run times
.plot.benchmark.cumulative:
  based_on:
    - .creator.multiverse
    - .plot.facet_grid.line
    - .plot.facet_grid.with_auto_encoding
    - .hlpr.limits.x.min_max
    - .hlpr.limits.y.from_zero

  dag_options:
    define:
      model_name: SET_MODEL_NAME_IN_YOUR_PLOT_CONFIG

  select_and_combine:
    fields:
      data:
        path: data
        transform:
          - getitem: [!dag_prev , !dag_tag model_name]
          - getitem: [!dag_prev , benchmark]
          - getitem: [!dag_prev , cumulative]

  x: n_iterations

  helpers:
    set_labels:
      x: time [#iterations]
      y: cumulative walltime [s]



# -- DEPRECATED PLOTS ---------------------------------------------------------
# NOTE This is the legacy plot function, will be removed; use .plot.ca instead!
.ca.state:
  based_on:
    - .creator.universe  # does not work with anything else
    - .animation.disabled

  module: !add [*utopya_plots, .ca]
  plot_func: state

  file_ext: pdf

  default_imshow_kwargs:
    interpolation: 'none'

  # Can use constrained layout, because axis labels don't change
  style:
    figure.constrained_layout.use: true



# .. .ca.state specializations for different animation writers ................
.ca.state.anim_frames:
  based_on:
    - .ca.state
    - .animation.frames

  time_idx: 0  # ignored in animations, but required

.ca.state.anim_ffmpeg:
  based_on:
    - .ca.state
    - .animation.ffmpeg

  time_idx: 0  # ignored in animations, but required







# =============================================================================
#  ╔═╗╔╦╗╦ ╦╦  ╔═╗
#  ╚═╗ ║ ╚╦╝║  ║╣
#  ╚═╝ ╩  ╩ ╩═╝╚═╝
# =============================================================================
# start: .style
# More information:
#   https://matplotlib.org/gallery/style_sheets/style_sheets_reference.html
#   https://matplotlib.org/stable/tutorials/introductory/customizing.html


.style.no_spines:
  style:
    axes.spines.left: false
    axes.spines.right: false
    axes.spines.bottom: false
    axes.spines.top: false




# =============================================================================
#  ╔═╗╦  ╔═╗╔╦╗  ╦ ╦╔═╗╦  ╔═╗╔═╗╦═╗╔═╗
#  ╠═╝║  ║ ║ ║   ╠═╣║╣ ║  ╠═╝║╣ ╠╦╝╚═╗
#  ╩  ╩═╝╚═╝ ╩   ╩ ╩╚═╝╩═╝╩  ╚═╝╩╚═╚═╝
# =============================================================================
# start: .hlpr






# =============================================================================
#  ╔═╗╔╗╔╦╔╦╗╔═╗╔╦╗╦╔═╗╔╗╔
#  ╠═╣║║║║║║║╠═╣ ║ ║║ ║║║║
#  ╩ ╩╝╚╝╩╩ ╩╩ ╩ ╩ ╩╚═╝╝╚╝
# =============================================================================
# start: .animation

.animation.defaults:
  based_on:
    - .animation.defaults  # from dantro
    - .animation.high_dpi  # from dantro


# Aliases (with slightly different names) for setting the animation writer
# and enabling animation. Unlike those in dantro, these *include* the defaults.
.animation.ffmpeg:
  based_on:
    - .animation.defaults
    - .animation.enabled
    - .animation.use_ffmpeg

.animation.frames:
  based_on:
    - .animation.defaults
    - .animation.enabled
    - .animation.use_frames






# =============================================================================
#  ╔╦╗╔═╗╔═╗  ╔═╗╦═╗╔═╗╔╦╗╔═╗╦ ╦╔═╗╦═╗╦╔═
#   ║║╠═╣║ ╦  ╠╣ ╠╦╝╠═╣║║║║╣ ║║║║ ║╠╦╝╠╩╗
#  ═╩╝╩ ╩╚═╝  ╚  ╩╚═╩ ╩╩ ╩╚═╝╚╩╝╚═╝╩╚═╩ ╩
# =============================================================================
# start: .dag
# -- Options ------------------------------------------------------------------
# .. Aggregated DAG default options ...........................................
.dag.defaults:
  based_on: .dag.defaults



# -- Visualization ------------------------------------------------------------
# Parameters controlling DAG visualization
.dag.vis.defaults:
  based_on: .dag.vis.defaults



# -- Definitions --------------------------------------------------------------
# The entries below set certain tags using the `dag_options.define` argument.
# This should not be confused with the .dag.meta_ops defined below.

.dag.define.defaults:
  based_on: .dag.define.defaults


# The code constants from matplotlib.path.Path, used for defining paths
.dag.define.mpl.Path.codes:
  dag_options:
    define:
      STOP:
        - import: [matplotlib.path, Path]
        - getattr: [!dag_prev , STOP]
      MOVETO:
        - import: [matplotlib.path, Path]
        - getattr: [!dag_prev , MOVETO]
      LINETO:
        - import: [matplotlib.path, Path]
        - getattr: [!dag_prev , LINETO]
      CURVE3:
        - import: [matplotlib.path, Path]
        - getattr: [!dag_prev , CURVE3]
      CURVE4:
        - import: [matplotlib.path, Path]
        - getattr: [!dag_prev , CURVE4]
      CLOSEPOLY:
        - import: [matplotlib.path, Path]
        - getattr: [!dag_prev , CLOSEPOLY]







# =============================================================================
#  ╔╦╗╔═╗╔═╗  ╔╦╗╔═╗╔╦╗╔═╗  ╔═╗╔═╗╔═╗╦═╗╔═╗╔╦╗╦╔═╗╔╗╔╔═╗
#   ║║╠═╣║ ╦  ║║║║╣  ║ ╠═╣  ║ ║╠═╝║╣ ╠╦╝╠═╣ ║ ║║ ║║║║╚═╗
#  ═╩╝╩ ╩╚═╝  ╩ ╩╚═╝ ╩ ╩ ╩  ╚═╝╩  ╚═╝╩╚═╩ ╩ ╩ ╩╚═╝╝╚╝╚═╝
# =============================================================================
# start: .dag.meta_ops
# The following entries can be included into a plot configuration to make
# certain meta-operations available for the data transformation framework.





# =============================================================================