Advanced API usage

The Pipeline object is the most automatized way to apply a series of transformations to a stack. By the way it does not allow to have a low level interaction with the individual plugins. This can be important for example to control the result of a certain transformation on a stack, without applying a full pipeline of transformation. In bmiptools a ‘low-level’ interaction with the plugins is possible.

Initialize a plugin

In bmiptools the default plugins can be found in bmiptools.transformation. A list of the possible available plugins can be found in the PLUGINS dictionary of the bmiptools.setting.installed_plugins module (as explained here), which contains also the plugins installed locally by the user (see here for more details)

from bmiptools.setting.installed_plugins import PLUGIN

print(PLUGINS.keys())

Every plugin in bmiptools are initialized with a dictionary, called transformation dictionary, which contains all the plugin parameters. Typically a plugin has many parameters and the transformation dictionary need to have a specific structure. For this reason every plugin is equipped with a global attribute called .empty_transformation_dictionary which can be read without initializing the plugin. The value stored in this dictionary are the default parameters of the plugin, which can be used for generic tasks.

from bmiptools.transformation import Destriper

# get the default transformation dictionary
transformation_dictionary = Destriper.empty_transformation_dictionary
print(transformation_dictionary)

This system can be used also to set the parameters without the need to reproduce the transformation dictionary structure so that the plugin can be initialized with the desired setting easily.

# set a parameter in the transformation dictionary
transformation_dictionary['optimization_setting']['opt_bounding_box']['use_bounding_box'] = False

# initialize the plugin
destriper = Destriper(transformation_dictionary)

The transformation dictionary has a common structure, whose explanation can be found in General information about plugins (together with general information about the plugins), while all the plugin-specific parameters are explained in the corresponding plugin documentation.

Note

Once that the plugin is initialized, the initialized plugin acquires a series of attributes having the same name of the parameter in the transformation dictionary. Therefore one can check the parameters value after the initialization simply by checking the corresponding class attributes.

# check the value of the parameter 'use_bounding_box'
print(destriper.use_bounding_box)

These attributes can also be used to change the parameters after the plugin initialization.

# set parameter value after initialization
destriper.use_bounding_box = True
print(destriper.use_bounding_box)

Plugin optimization

Many plugin can be optimized. The optimization can be run by calling the method .fit which is present in any plugin (but only when the plugin can be optimized, this method actually do something). This method takes always as input the stack on which the optimization have to be done (for the meaning of plugin optimization see here). The optimization of the plugin can be done with the following line of code

# load/create a stack on which the plugin is applied
# stack = ...

# fit the previously initialized plugin
destriper.fit(stack)

Attention

At the end of the optimization the result of the optimization (i.e. the parameters value found) are stored in the corresponding attributes of the plugin class, overwriting the initial value assigned during the optimization.

Apply a plugin

The application of the plugin can be done with the method .transform, which takes a stack input the stack on which the plugin is applied.

# in place application of a plugin
destriper.transform(stack)

It is important to know that the content of the stack is overwritten with the result of the plugin application, i.e. at the end of the transformation application, the content of the initial stack is updated with th result of the transformations. This is the default behavior, however this feature can be changed by setting inplace=False.

result = destriper.transform(stack,inplace=False)

In this case, stack is not overwritten and still contain the initial data. The transformation result is stored in the numpy array result.

Attention

If the field auto_optimize = True in the transformation dictionary of a plugin that can be optimized, when the .transform methods is called but the plugin was still not optimized (i.e. the .fit method was not called), the optimization is executed automatically (i.e. the .fit method is called internally before the application of the transformation).

Get plugin parameters

It is possible to get the transformation dictionary with the actual status of all the plugin parameters with a single command. this cna be done calling the .get_transformation_dictionary. This is particularly useful to get access to all the parameters of a plugin at the end of the optimization procedure.

current_transformation_dictionary = destriper.get_transformation_dictionary()
print(current_transformation_dictionary)