The plugins sub-package

class pydidas.plugins.plugin_collection.PluginRegistry(**kwargs: dict)

Class to hold references of plugins.

Plugins can be accessed by their class names or by their plugin_name properties. For details, please refer to the individual methods.

Note that the PluginRegistry is a class which should not normally be accessed directly but generally through its ‘PluginCollection’ singleton.

Parameters:

**kwargs (dict) –

Supported kwargs are:

plugin_pathUnion[str, list[Path], None], optional

The search directory for plugins. A single path can be supplies as string. Multiple paths can be supplied in a single string separated by “;;” or as a list. None will call to the default paths. The default is None.

force_initializationbool, optional

Keyword to force initialization at creation. By default, the PluginCollection is initialized the first time it is used. The default is False.

check_and_register_class(class_: type, reload: bool = False)

Check whether a class is a valid plugin and register it.

Parameters:

• class (type) – The class object.

• reload (bool) – Flag to enable reloading of plugins. If True, new plugins will overwrite older stored plugins. The default is False.

clear_collection(confirmation: bool = False)

Clear the collection and remove all registered plugins.

Parameters:

confirmation (bool, optional) – Confirmation flag which needs to be True to proceed. The default is False.

find_and_register_plugins(*plugin_paths: tuple[Path], reload: bool = True)

Find plugins in the given path(s) and register them in the PluginCollection.

Parameters:

• plugin_paths (tuple[Path]) – Any number of file system paths.

• reload (bool, optional) – Flag to handle reloading of plugins if a plugin with an identical name is encountered. If False, these plugins will be skipped.

get_all_plugin_names() → list[str]

Get a list of all the plugin names currently registered.

Returns:

names – The list of all the plugin names.

Return type:

list

get_all_plugins() → list[type]

Get a list of all plugins.

Returns:

A list with all the Plugin classes.

Return type:

list

get_all_plugins_of_type(plugin_type: Literal['base', 'input', 'proc', 'output'])

Get all Plugins of a specific type (base, input, proc, or output).

Parameters:

plugin_type (Literal["base", "input", "proc", "output"]) – The type of the demanded plugins.

Returns:

A list with all Plugins which have the specified type.

Return type:

list

get_plugin_by_name(name: str) → type

Get a plugin by its class name.

Parameters:

name (str) – The class name of the plugin.

Returns:

plugin – The Plugin class.

Return type:

pydidas.plugins.BasePlugin

get_plugin_by_plugin_name(plugin_name: str) → type

Get a plugin by its plugin name.

Parameters:

plugin_name (str) – The plugin_name property of the class.

Returns:

plugin – The Plugin class.

Return type:

pydidas.plugins.BasePlugin

get_q_settings_plugin_paths() → list[Path]

Get the plugin path from the global QSettings.

This method also strips non-existent paths from the list of results.

Returns:

A list with all stored path entries.

Return type:

list[Path]

property registered_paths: list[Path]

Get all the paths which have been registered in the PluginCollection.

Returns:

The list of all registered paths.

Return type:

list[Path]

remove_plugin_from_collection(class_: type)

Remove a Plugin from the PluginCollection.

Parameters:

class (type) – The class object to be removed.

unregister_all_paths(confirmation: bool = False)

Unregister all paths.

Parameters:

confirmation (bool, optional) – Confirmation flag to prevent accidentally unregistering all paths. The default is False.

unregister_plugin_path(path: str | Path)

Unregister the given path from the PluginCollection.

Parameters:

path (Union[str, Path]) – The path to the directory containing the plugins.

Raises:

UserConfigError – If the given path is not registered.

verify_is_initialized()

Verify that the instance is initialized.

During initialization, the PluginCollection processes all specified paths.

This method is called internally in every public method to make sure that the PluginCollection is always initialized before any user interaction occurs.

The pydidas.plugins subpackage includes the base classes for plugins as well as the PluginCollection singleton which holds all registered plugins and allows to get new instances of these plugins.

class pydidas.plugins.BaseFitPlugin(*args, **kwargs)

Fit a single peak to the input data.

This plugin allows to fit the input data with any function defined in the pydidas.core.fitting package.

calculate_result_shape()

Calculate the shape of the Plugin results.

check_center_positions() → bool

Check the fitted center position.

Returns:

Flag whether all centers are in the input x range.

Return type:

bool

check_min_peak_height() → bool

Check the minimum peak height and return the flag whether it is okay.

Returns:

Flag whether the input data has a sufficiently large peak.

Return type:

bool

create_detailed_results(results: Dataset, start_fit_params: List) → dict

Create the detailed results for a single fit.

This method will return detailed information to display for the user. The return format is a dictionary with four keys: First, “n_plots” which determines the number of plots. Second, “plot_titles” gives a title for each subplot. Third, “plot_ylabels” gives a y axis label for each subplot. Fourth, “items” provides a list with the different items to be plotted. Each list entry must be a dictionary with the following keys: “plot” [to detemine the plot number], “label” [for the legend label] and “data” with the actual data.

Parameters:

• results (pydidas.core.Dataset) – The Dataset with the regular results.

• start_fit_params (list) – The list with the starting fit params.

Returns:

The dictionary with the detailed results in the format expected by pydidas.

Return type:

dict

create_fit_start_param_dict()

Create a dictionary with preset fit starting values.

create_result_dataset(valid: bool = True)

Create a new Dataset from the original data and the data fit including all the old metadata.

Note that this method does not update the new metadata with the fit parameters. The new dataset includes a second dimensions with entries for the raw data, the data fit and the residual.

Parameters:

valid (bool, optional) – Flat to confirm the results are valid. The default is True.

Returns:

new_data – The new dataset.

Return type:

pydidas.core.Dataset

property detailed_results

Get the detailed results for the FitSinglePeak plugin.

Returns:

The dictionary with detailed results.

Return type:

dict

execute(data: Dataset, **kwargs: dict) → tuple[Dataset, dict]

Fit a peak to the data.

Note that the results includes the original data, the fitted data and the residual and that the fit Parameters are included in the kwarg metadata.

Parameters:

• data (pydidas.core.Dataset) – The input Dataset

• **kwargs (dict) – Any calling keyword arguments.

Returns:

• _data (pydidas.core.Dataset) – The image data.

• kwargs (dict) – Any calling kwargs, appended by any changes in the function.

get_parameter_config_widget() → QWidget

Get the unique configuration widget associated with this Plugin.

Returns:

The unique ParameterConfig widget

Return type:

QtWidgets.QWidget

pre_execute()

Set up the required functions and fit variable labels.

prepare_input_data(data: Dataset)

Prepare and store the input data.

Parameters:

data (Dataset) – The input data.

property result_shape: tuple[int, ...]

Get the shape of the plugin result.

Returns:

The shape of the results with a value for each dimension. Unknown dimensions are represented as -1 value.

Return type:

tuple[int, …]

update_fit_param_bounds()

Update the fitting bounds from Parameters.

Dictionary keys can be any key given in the param_labels. Values must be tuple pairs of low, high boundary values. None is allowed to ignore setting a particular boundary.

Parameters:

**kwargs (Dict) – Dictionary with key, value pairs for the

class pydidas.plugins.BasePlugin(*args, **kwargs)

The base plugin class from which all plugins inherit.

Class attributes are used in the descriptions of individual plugins and all these attributes should be re-defined in individual plugins to prevent falling back to the base class attributes:

basic_pluginbool

A keyword to mark basic plugin classes.

plugin_typeint

A key to discriminate between the different types of plugins (input, processing, output)

plugin_namestr

The plugin name key in human-readable form for referencing the plugin.

default_paramsParameterCollection, optional

A ParameterCollection with the class parameters which are required to use the plugin. The default is an empty ParameterCollection.

generic_paramsParameterCollection, optional

A ParameterCollection with the generic parameters for all plugins of a specific type. The default are the Parameters “keep_results” and “label” for all plugins.

input_data_dimint, optional

The dimensionality of the input data. Use -1 for arbitrary dimensionality or None if the plugin does not accept any input data. The default is -1.

output_data_dimint, optional

The dimensionality of the output data. Use -1 for arbitrary dimensionality or None if the plugin does not create any output data. The default is -1.

output_data_labelstr, optional

The label for the output Dataset. The default is an empty string.

output_data_unitstr, optional

The unit of the output Dataset. The default is an empty string.

new_datasetbool

Keyword that the Plugin creates a new dataset. This will trigger a re-evaluation of the output data shape.

has_unique_parameter_config_widgetbool, optional

Flag to use a unique ParameterConfigWidget for this plugin. The widget must be made accessible through the “get_parameter_config_widget” method. the default is False.

advanced_parameterslist[str, …], optional

A list with the keys of “advanced parameters”. These Parameters are hidden in the plugin’s Parameter configuration widget be default and can be accessed through the associated button for “advances parameters” not to overwhelm users with too many options. The default is an empty list [].

apply_legacy_image_ops_to_data(data: ndarray) → ndarray

Apply the legacy image operations to a new data frame.

Parameters:

data (np.ndarray) – The input data frame.

Returns:

new_data – The updated data frame with ROI and binning applied.

Return type:

np.ndarray

calculate_result_shape()

Calculate the shape of the results based on the Plugin processing and the input data shape.

This method only updates the shape and stores it internally. Use the “result_shape” property to access the Plugin’s result_shape. The generic implementation assumes the output shape to be equal to the input shape.

copy() → Self

Create a copy of itself.

Returns:

The plugin’s copy.

Return type:

BasePlugin

execute(data: int | Dataset, **kwargs: dict)

Execute the processing step.

Parameters:

• data (Union[int, Dataset]) – The input data to be processed.

• kwargs (dict) – Keyword arguments passed to the processing.

classmethod get_class_description() → str

Get a description of the plugin as a multi-line string.

This method can generate a description of the plugin with name, plugin type, class name and Parameters and the docstring. The return is a formatted string.

Returns:

The descripion of the plugin.

Return type:

str

classmethod get_class_description_as_dict() → dict

Get a description of the plugin as a dictionary of entries.

This method can generate a description of the plugin with name, plugin type, class name and Parameters and the docstring. The return is a dictionary of entries.

Returns:

The description of the plugin.

Return type:

dict

get_parameter_config_widget()

Get the unique configuration widget associated with this Plugin.

This method is useful if the configuration widget should have any non-standard items, e.g. sliders or interactive capability.

Raises:

NotImplementedError – This method is not implemented in the BasePlugin and needs to be implemented in the concrete subclass, if required.

Returns:

The unique ParameterConfig widget

Return type:

QtWidgets.QWidget

get_single_ops_from_legacy() → tuple[tuple[slice, ...], int]

Get the parameters for a single ROI and binning operation.

This method combines all legacy operations on the data into one set of operations to be applied.

Returns:

• roi (tuple[slice, …]) – The ROI which needs to be applied to the original image.

• binning (int) – The binning factor which needs to be applied to the original image.

property input_data: int | Dataset

Get the current input data.

Returns:

The input data passed to the plugin.

Return type:

Union[int, pydidas.core.Dataset]

classmethod input_data_dim_str() → str

Get the input data dimensionality as string.

Returns:

The formatted input data dimensionality.

Return type:

str

property input_shape: tuple | None

Get the shape of the Plugin’s input.

Returns:

The shape of the plugin’s input.

Return type:

Union[tuple, None]

classmethod output_data_dim_str() → str

Get the output data dimensionality as string.

Returns:

The formatted input data dimensionality.

Return type:

str

pre_execute()

Run the pre-execution code before processing individual datapoints.

property result_data_label: str

Get the combined result data label, consisting of the formatted output_data_label and output_data_unit.

Returns:

The formatted data label.

Return type:

str

property result_shape: tuple | None

Get the shape of the plugin result.

Note that this property will always perform an update of the value before returning a result.

Any plugin that knows the shape of its results will return the value as a tuple with one entry for every dimension. If a Plugin knows the dimensionality of its results but not the size of each dimension, a -1 is returned for each unknown dimension.

Returns:

The shape of the results with a value for each dimension. Unknown dimensions are represented as -1 value. If no result shape has been calculated yet, return None.

Return type:

Union[tuple, None]

property result_title: str

Get the formatted title of the plugin’s results.

Returns:

The formatted result title.

Return type:

str

store_input_data_copy(data: Dataset, **kwargs: dict)

Store a copy of the input data internally in the plugin.

Parameters:

• data (Union[int, np.ndarray]) – The input data for the plugin.

• **kwargs (dict) – The calling keyword arguments

update_legacy_image_ops_with_this_plugin()

Update the legacy image operations list with any ROI and binning operations performed in this plugin.

class pydidas.plugins.FitMultiPeak(*args, **kwargs)

Fit multiple peaks to the input data.

This plugin allows to fit the input data with any function defined in the pydidas.core.fitting package.

calculate_result_shape()

Calculate the shape of the Plugin results.

check_center_positions() → bool

Check the fitted center positions.

Returns:

Flag whether all centers are in the input x range.

Return type:

bool

class pydidas.plugins.InputPlugin(*args: tuple, **kwargs: dict)

The base plugin class for input plugins.

calculate_result_shape()

Calculate the shape of the Plugin’s results.

execute(index: int, **kwargs: dict) → tuple[Dataset, dict]

Import the data and pass it on after (optionally) handling image multiplicity.

Parameters:

• index (int) – The index of the scan point.

• **kwargs (dict) – Keyword arguments passed to the execute method.

Returns:

• pydidas.core.Dataset – The image data frame.

• kwargs (dict) – The updated kwargs.

get_filename(frame_index: int) → str

Get the filename of the file associated with the frame index.

Parameters:

index (frame) – The index of the frame to be processed.

Returns:

The filename.

Return type:

str

get_first_file_size() → int

Get the size of the first file to be processed.

Returns:

The file size in bytes.

Return type:

int

get_frame(frame_index: int, **kwargs: dict) → Dataset

Get the specified image frame (which does not necessarily correspond to the scan point index).

Parameters:

• frame_index (int) – The index of the specific frame to be loaded.

• **kwargs (dict) – Keyword arguments passed for loading the frame.

Returns:

The image data frame.

Return type:

pydidas.core.Dataset

handle_multi_image(index: int, **kwargs: dict) → tuple[Dataset, dict]

Handle frames with an image multiplicity.

Parameters:

• index (int) – The scan index.

• **kwargs (dict) – Keyword arguments for the get_frame method.

Returns:

• pydidas.core.Dataset – The image data frame.

• kwargs (dict) – The updated kwargs.

input_available(index: int) → bool

Check whether a new input file is available.

Note: This function returns False by default. It is intended to be used only for checks during live processing.

Parameters:

index (int) – The frame index.

Returns:

flag whether the file for the frame #<index> is ready for reading.

Return type:

bool

pre_execute()

Run generic pre-execution routines.

prepare_carryon_check()

Prepare the checks of the multiprocessing carryon.

By default, this gets and stores the file target size for live processing.

update_filename_string()

Set up the generator that can create the full file names to load images.

The generic implementation only joins the base directory and filename pattern, as defined in the ScanContext class.

update_required_kwargs(kwargs: dict)

Update the kwargs dict in place.

class pydidas.plugins.InputPlugin1d(*args: tuple, **kwargs: dict)

The base plugin class for input plugins.

calculate_result_shape()

Calculate the shape of the Plugin’s results.

get_raw_input_size()

Get the number of data points in the raw input.

Raises:

NotImplementedError – This method needs to be implemented by the concrete subclass.

Returns:

The raw input size in data points.

Return type:

int

pre_execute()

Run generic pre-execution routines.

update_required_kwargs(kwargs: dict)

Update the kwargs dict in place.

class pydidas.plugins.OutputPlugin(*args, **kwargs)

The base class for output (file saving / plotting) plugins.

get_output_filename(extension: str = 'txt') → str

Get the output filename from the global frame index and the Plugin label.

Parameters:

extension (str, optional) – The file extension. The default is txt.

Returns:

The full filename and path.

Return type:

str

pre_execute()

Prepare loading images from a file series.

class pydidas.plugins.ProcPlugin(*args, **kwargs)

The base plugin class for processing plugins.

This class updates the “plugin_type” and “plugin_subtype” attributes.

pydidas.plugins.plugin_getter(plugin_name: str) → BasePlugin

Get a new Plugin instance from a Plugin name.

Parameters:

plugin_name (str) – The Plugin class name.

Returns:

plugin – The new Plugin instance.

Return type:

pydidas.plugins.BasePlugin

class pydidas.plugins.pyFAIintegrationBase(*args: tuple, **kwargs: dict)

Provide basic functionality for the concrete integration plugins.

calculate_result_shape()

Get the shape of the integrated dataset to set up the CRS / LUT.

Returns:

The new shape. For 1-dimensional integration, a single integer is returned. For 2-dimensional integrations a tuple of two integers is returned.

Return type:

Union[int, tuple[int, int]]

check_and_set_custom_mask(**kwargs: dict)

Check the kwargs for a custom mask and set it, if available.

Parameters:

**kwargs (dict) – Any keyword arguments.

convert_radial_range_values(from_unit: Literal['2theta / deg', 'Q / nm^-1', 'r / mm'], to_unit: Literal['2theta / deg', 'Q / nm^-1', 'r / mm'])

Convert and store the radial range values from the given unit to the given unit.

Parameters:

• from_unit (Literal["2theta / deg", "Q / nm^-1", "r / mm"]) – The previous unit.

• to_unit (Literal["2theta / deg", "Q / nm^-1", "r / mm"]) – The new unit.

execute(data: ndarray, **kwargs: dict)

To be implemented by the concrete subclass.

get_azimuthal_range_in_deg() → None | tuple[float, float]

Get the azimuthal range from the Parameters in degree.

If use_azimuthal_range is True and both the lower and upper range limits are larger than zero, the tuple with both values is returned. Otherwise, the return is None which corresponds to pyFAI auto ranges.

Returns:

The azimuthal range for the pyFAI integration in degrees.

Return type:

Union[None, tuple[float, float]]

get_azimuthal_range_in_rad() → None | tuple[float, float]

Get the azimuthal range from the Parameters in radians.

If use_azimuthal_range is True and both the lower and upper range limits are larger than zero, the tuple with both values is returned. Otherwise, the return is None which corresponds to pyFAI auto ranges.

Returns:

The azimuthal range for the pyFAI integration in radian.

Return type:

Union[None, tuple[float, float]]

get_azimuthal_range_native() → None | tuple[float, float]

Get the azimuthal range from the Parameters in native units.

If use_azimuthal_range is True and both the lower and upper range limits are larger than zero, the tuple with both values is returned. Otherwise, the return is None which corresponds to pyFAI auto ranges.

Returns:

The azimuthal range for the pyFAI integration.

Return type:

Union[None, tuple[float, float]]

get_parameter_config_widget() → QWidget

Get the unique configuration widget associated with this Plugin.

Returns:

The unique ParameterConfig widget

Return type:

QtWidgets.QWidget

get_pyFAI_unit_from_param(param_name: str) → str

Get the unit of the Parameter called param_name in pyFAI notation.

Parameters:

param_name (str) – The reference key of the Parameter with the unit.

Returns:

The unit in pyFAI notation.

Return type:

str

get_radial_range() → tuple[float, float, None]

Get the radial range from the Parameters.

If use_radial_range is True and both the lower and upper range limits are larger than zero, the tuple with both values is returned. Otherwise, the return is None which corresponds to pyFAI auto ranges.

Returns:

The radial range for the pyFAI integration.

Return type:

Union[tuple[float, float, None]]

get_radial_range_as_2theta(unit: Literal['deg', 'rad'] = 'deg') → tuple[float, float, None]

Get the radial range converted to 2 theta.

Parameters:

unit (Literal["deg", "rad"], optional) – The unit of the range. Must be either “rad” or “deg”. The default is “deg”.

Returns:

range – If no range has been set, returns None. Otherwise, the range limits are given as tuple.

Return type:

Union[None, tuple[float, float]]

get_radial_range_as_q() → tuple[float, float, None]

Get the radial range as q in nm^-1.

Returns:

range – If no range has been set, returns None. Otherwise, the range limits are given as tuple.

Return type:

Union[None, tuple[float, float]]

get_radial_range_as_r() → tuple[float, float, None]

Get the radial range as radius in mm.

Returns:

range – If no range has been set, returns None. Otherwise, the range limits are given as tuple.

Return type:

Union[None, tuple[float, float]]

is_range_valid() → bool

Check whether the plugin’s range is valid.

Parameters:

azi_range (tuple) – The azimuthal range.

Returns:

Flag whether the range is valid or not.

Return type:

bool

load_and_set_mask()

Load and store the mask.

If defined (and the file exists), the locally defined detector mask Parameter will be used. If not, the global QSetting detector mask will be used.

modulate_and_store_azi_range()

Try to modulate the azimuthal range to be compatible with pyFAI.

pre_execute()

Check and load the mask and set up the AzimuthalIntegrator.