vdmtools.plotting.IStrategyPlugin

class vdmtools.plotting.IStrategyPlugin(child: IStrategyPlugin, file_suffix: str = '', output_folder: Path = PosixPath('plots'), save_pickle: bool = False)

Plugin contract for all VdM plotting strategies.

This class offers the interface that all VdM plotting strategies adhere to. Strategies are handed over to the VdMPlotter class and are responsible for intructing the plotter on how to plot the data.

Note

Communication between the strategy and the plotter is done through the context object. This object is given to the plotter by the user and in turn, the plotter forwards it to all the hooks in the strategy.

Children of this class are given full control over the plotting process. This includes:

The loop structure: How many loops are there? What are the iterators? What is the order of the loops? All of these questions are answered by the strategy via the iterations attribute.
The hook scheme: Where and when should the hooks be called? This is specified by the strategy via the hook_scheme attribute.
The plotting logic: Is there a preperation step? How should the data be plotted? How should the plot be styled? How (and where) should the plot be saved? All of these questions are answered by the strategy via the implementation of the prepare(), plot(), style() and save() methods.

Important

The strategy has full control over the plotting process. This also gives it full responsibility on how to use the data and context objects. The VdMPlotter class does not make any assumptions about the data or context objects.

Tip

Given the enourmous responsibility that the strategy has, each child class should be well documented on how to use it. This includes:

What is the data: Is the data a list? A dictionary? A tuple? A numpy array? A pandas dataframe? Whatever it is, the developer should document it. This will help the user understand how to use the organize the data before passing it to the plotter via the run() method.
What is the context: Once again, is the context a plain dictionary? A custom object? This should be clearly documented. What additional context is needed/permitted to be set by the user? This should also be documented since it will help the user how to use the construct the context object before passing it to the plotter via the run() method.

iterations

Specifies the loop structure of the plotting process.

Each element in this list represents one loop in the plotting process. A loop is defined by:

An iterator id (str): This is the id of the iterator. It is used to identify the current value of the iterator in the context object. For example, if the iterator is fits, then the current value of the iterator will be set in the context under the key current_fit.
Filters (Iterator[FilterCallable]): These filters are used to filter out certain values from the iterator. For example, when plotting the ratio of a quantity between two detectors (given one as a reference), we want to skip a detector if its name is the same as the reference.

Important

The order of the elements in this list is the order in which the loops will be executed. The first element will be the outermost loop and the last element will be the innermost loop.

An example of this attribute is:

# This filter assumes the strategy has a 'reference_detector' attribute
# which is the name of the reference detector for the ratio
def filter_same_detector(strategy, detector, context):
    return detector == strategy.reference_detector

iterations = [
    ("fits", []), # No filters
    ("corrections", []), # No filters
    ("detectors", [filter_same_detector]) # One filter
]

Type:: List[Tuple[str, Iterator[FilterCallable]]]

hook_scheme

Specifies when and where the hooks should be called.

The hook scheme is used to specify where and when the hooks should be called. The keys of the dictionary are the HookType which can be either CALL_ON_ENTRY or CALL_ON_EXIT. The values of the dictionary are dictionaries themselves. The keys of these dictionaries are the iterator ids specified in the iterations attribute. The values of these dictionaries are lists of strings. These strings are the names of the methods that will be called when the hook is called.

For example, the following hook scheme:

hook_scheme = {
    HookType.CALL_ON_ENTRY: {
        "corrections": ["prepare"],
        "detectors": ["plot", "style"]
    },
    HookType.CALL_ON_EXIT: {
        "detectos": ["save"]
    }
}

This scheme specifies that the following hooks will be called:

prepare and plot will be called when the every time the correction loop is entered.
plot and style will be called when the every time the detector loop is entered.
save will be called when the detector loop is exited.

Refer to the Hook Table for an ilustration of when the hooks will be called.

Type:: Dict[HookType, Dict[str, Iterator[str]]]

unique_folder_name

The unique folder name is used to specify the name of the folder that the plot will be saved in.

Tip

It is recommended that the name of the folder be the name of the strategy class.

Type:: str

data_description

The strategy data description. Every subclass must implement this attribute and it must describe the type of data that the subclass accepts. This is used to help the user understand how to use the strategy.

Type:: str

args_description

The strategy arguments description. Every subclass must implement this attribute and it must describe all the arguments that the subclass accepts in its constructor.

Type:: Dict[str, str]

reserved_context_keys

The reserved context keys. Every subclass must implement this attribute and it must describe all the keys that the subclass uses in the context object. This is used to prevent the user from overwriting keys that the subclass uses.

Type:: Dict[str, str]

Note

iterations, hook_scheme and unique_folder_name must be set by the subclass and cannot be changed via the constructor. This design choice allows for the user to now have to worry about setting these attributes when creating a new instance of the subclass.

file_suffix

The suffix that will be appended to the name of the plot file.

Type:: str

output_folder

The path to the folder that the plot will be saved in.

Type:: Path

save_pickle

Whether or not to save the plot as a pickle file.

Type:: bool

Methods

`get_iterators`(data)	Get the iterators for the strategy.
`plot`(i, data, context)	Plot the data.
`prepare`(i, data, context)	Prepare the plot.
`save`(i, data, context)	Save the plot.
`style`(i, data, context)	Style the plot.

get_iterators(data) → Dict[str, Iterator[str]]

Get the iterators for the strategy.

This method is responsible for returning a dictionary of iterators that will be used by the strategy. The keys of the dictionary are the iterator ids as specified in the iterations attribute. The values of the dictionary are the actual iterators. The way these iterators are obtained will depend on the type of data. Each subclass is responsible for implementing this method and returning the correct iterators.

Parameters:: data (Any) – The data that will be used for plotting. Each subclass is responsible for implementing this method and returning the correct iterators.
Returns:: The dictionary of iterators that will be used by the strategy.
Return type:: Dict[str, Iterator[str]]

plot(i, data, context)

Plot the data.

This method is responsible for plotting the data. The calling of this method is controlled by the hook_scheme attribute.

Parameters:

i (int) – The index of the current value of the iterator.
data (Any) – The data used for plotting.
context (MutableMapping[str, Any]) – The plot context up to this point.

Note

This method is called after the prepare() method and before the style() method.

prepare(i, data, context)

Prepare the plot.

This method is called before the plotting starts. It is responsible for doing any preparation that is needed before the plotting starts. The calling of this method is controlled by the hook_scheme attribute.

Parameters:

i (int) – The index of the current value of the iterator.
data (Any) – The data used for plotting.
context (MutableMapping[str, Any]) – The plot context up to this point.

Note

This method is called before the plot() method.

save(i, data, context)

Save the plot.

This method is responsible for saving the plot. The calling of this method is controlled by the hook_scheme attribute.

Parameters:

i (int) – The index of the current value of the iterator.
data (Any) – The data used for plotting.
context (MutableMapping[str, Any]) – The plot context up to this point.

Note

This method is called after the style() method.

style(i, data, context)

Style the plot.

This method is responsible for styling the plot. The calling of this method is controlled by the hook_scheme attribute.

Parameters:

i (int) – The index of the current value of the iterator.
data (Any) – The data used for plotting.
context (MutableMapping[str, Any]) – The plot context up to this point.

Note

This method is called after the plot() method and before the save() method.