Plot Creator Auto Detection

Note

This page describes an advanced feature. Make sure to have read all about The PlotManager before diving into this.

Basic Idea

This feature aims to reduce the arguments that need to be defined in a plot configuration or when defining a plot function.

The PlotManager has as class variable a dictionary of CREATORS, which is a mapping of common name strings to plot creator types, i.e. AbstractPlotCreator-derived classes. Usually, the creator argument to the PlotManager’s plot() function is used to extract the plot creator type from that dictionary and then initialize the object.

However, the plot manager also has a auto_detect_creator feature. This boolean argument can be given both to __init__() as well as to plot() and it can also be part of the plot configuration passed to plot_from_cfg().

If set, the creator argument needs no longer be given in the plot configuration. By going through all registered CREATORS and instantiating them, it is found out if they declare that they can_plot() the given configuration. Each creator can implement this method as they see fit. In unambiguous cases, the manager then uses the single candidate creator and continues plotting with that creator.

Specializations

ExternalPlotCreator

The ExternalPlotCreator and derived classes try auto-detection by checking if it can use the given plot configuration to resolve a plotting function. Furthermore, it checks whether the plot function is marked with attributes that may specify which creator to use. The attributes that are looked at are, in this order:

  • creator_type: The type of the plot creator to use (or a parent type)

  • creator_name: The name of the plot creator as registered in the manager’s CREATORS dict

To conveniently add these attributes to the plot function, the is_plot_func() decorator can be used:

from dantro.plot_creators import is_plot_func

# Specify directly with the plot creator type
from dantro.plot_creators import MultiversePlotCreator

@is_plot_func(creator_type=MultiversePlotCreator)
def my_mv_plot_func(dm: DataManager, *, out_path: str, mv_data, **kwargs):
    # ...

# Alternatively: Specify only via the _name_ known to the PlotManager
@is_plot_func(creator_name="universe")
def my_uni_plot_func(dm: DataManager, *, out_path: str, uni, **kwargs):
    # ...

Hint

When using the data transformation framework, the signature of the plot functions is averse to the choice of a creator. This makes it possible to implement generic plotting functions, which can be used for all ExternalPlotCreator-derived plot creators.

In such cases, simply omit the creator_* argument to the decorator and specify the creator via the plot configuration.

Note

Setting only the creator_name is recommended for scenarios where the import of the creator type is not desired. In other scenarios, it’s best to use creator_type