The contexts sub-package

class pydidas.contexts.diff_exp.DiffractionExperiment(*args: tuple, **kwargs: dict)

Bases: ObjectWithParameterCollection

Class which holds experimental settings for diffraction experiments.

This class must be used with care. Usually, the unique DiffractionExperimentContext should be used to access the active instance.

The singleton factory will allow access to the single instance through :py:class:` pydidas.contexts.diff_exp.DiffractionExperimentContext`.

add_param(param: Parameter)

Add a parameter to the ParameterCollection.

This is a wrapper for the ParameterCollection.add_parameter method.

Parameters:

param (Parameter) – An instance of a Parameter object.

add_params(*params: tuple[Parameter | dict | ParameterCollection])

Add parameters to the object.

This method adds Parameters to the ParameterCollection of the object. Parameters can be either supplies as args or a ParameterCollection or dictionary in the form of <ref_key>: <Parameter>. This method is explicitly separate from the __init__ method to allow subclasses full control over args and kwargs.

Parameters:

*params (Tuple[Union[Parameter, dict, ParameterCollection]]) – Any Parameter or ParameterCollection

as_fit2d_geometry_values() → dict

Get the DiffractionExperiment configuration as values in Fit2D geometry.

Returns:

The geometry in Fit2D nomenclature with center_x, center_y, det_dist, tilt and tilt_plane keys.

Return type:

dict

as_pyfai_geometry() → Geometry

Get an equivalent pyFAI Geometry object.

Returns:

The pyFAI geometry object corresponding to the DiffractionExperiment config.

Return type:

Geometry

property beamcenter: tuple[float, float]

Get the beamcenter in detector pixel coordinates.

Returns:

• center_x (float) – The beamcenter x coordinate (in pixels).

• center_y (float) – The beamcenter y coordinate (in pixels).

copy() → Self

Get a copy of the object.

Returns:

The object’s copy.

Return type:

ObjectWithParameterCollection

deepcopy() → Self

Get a deepcopy of the object.

Returns:

The object’s deepcopy.

Return type:

ObjectWithParameterCollection

property detector_is_valid: bool

Check if the detector definition is valid.

This is determined by checking that the detector pixel sizes and numbers of pixel are positive.

Returns:

Flag whether the detector definition is valid.

Return type:

bool

export_to_file(filename: str | Path, overwrite: bool = False)

Import DiffractionExperimentContext from a file.

Parameters:

• filename (Union[str, pathlib.Path]) – The full filename.

• overwrite (bool, optional) – Keyword to allow overwriting of existing files.

classmethod get_default_params_copy() → ParameterCollection

Get a copy of the default ParameterCollection.

Returns:

A copy of the default ParameterCollection.

Return type:

ParameterCollection

get_detector() → Detector

Get the pyFAI detector object.

If a pyFAI detector can be instantiated from the “detector” Parameter value, this object will be used. Otherwise, a new detector is created and values from the DiffractionExperimentContext are copied.

Returns:

det – The detector object.

Return type:

Detector

get_param(param_key: str) → Parameter

Get a parameter.

Note: This method returns the Parameter itself, not a copy.

Parameters:

param_key (str) – The key name of the Parameter.

Returns:

The Parameter object.

Return type:

Parameter

get_param_keys() → list[str]

Get the keys of all registered Parameters.

Returns:

The keys of all registered Parameters.

Return type:

list

get_param_value(param_key: str, *default: object, dtype: type | None = None, for_export: bool = False) → object

Get a Parameter value.

Parameters:

• param_key (str) – The key name of the Parameter.

• default (object) – The default value if the param_key does not exist.

• dtype (type, optional) – A datatype to convert the value into. If None, the native datatype is returned. The default is None.

• for_export (bool, optional) – An optional flag to force converting the Parameter value to an export-compatible format. This flag is not compatible with a specific dtype. The default is False.

Returns:

The value of the Parameter.

Return type:

object

get_param_values_as_dict(filter_types_for_export: bool = False) → dict

Get a dictionary with Parameter names and values only.

Parameters:

filter_types_for_export (bool) – Flag to return objects in types suitable for exporting (i.e. pickleable).

Returns:

name_val_pairs – The dictionary with Parameter <name>: <value> pairs.

Return type:

dict

get_params(*param_keys: tuple[str, ...]) → list[Parameter]

Get multiple parameters based on their reference keys.

Parameters:

*param_keys (Tuple[str, ...]) – Any number of reference keys.

Returns:

A list with the Parameter instances referenced by the supplied keys.

Return type:

list

import_from_file(filename: str | Path)

Import DiffractionExperimentContext from a file.

Parameters:

filename (Union[str, pathlib.Path]) – The full filename.

property param_keys: list[str]

Get the keys of all stored Parameters.

Returns:

The keys of all stored Parameters.

Return type:

list[str]

property param_values: dict

Get the values of all stored Parameters along with their refkeys.

Returns:

The refkey, value pairs for all stored Parameters.

Return type:

Dict

print_param_values()

Print the name and value of all Parameters.

q_settings_get(key: str, dtype: type | None = None, default: object | None = None) → object

Get the value from a QSetting key.

Parameters:

• key (str) – The QSetting reference key.

• dtype (Union[type, None], optional) – A return datatype. If not None, the output will be returned as dtype(value), otherwise, the generic string/int will be returned. The default is None.

• default (type, optional) – The default value which is returned if the key defaults to None. The default is None.

Returns:

value – The value, converted to the type associated with the Parameter referenced by param_key or dtype, if given.

Return type:

object

q_settings_set(key: str, value: object)

Set the value of a QSettings key.

Parameters:

• key (str) – The name of the key.

• value (object) – The value to be stored.

restore_all_defaults(confirm: bool = False)

Restore the default values to all entries.

Parameters:

confirm (bool) – Confirmation flag as safety feature.

set_beamcenter_from_fit2d_params(center_x: float, center_y: float, det_dist: float, **kwargs: dict)

Set the beamcenter in detector pixel coordinates.

The center_x and center_y parameters define the position of the beam center on the detector. The optional rot_x, rot_y and rot_beam allow to add a rotation around axes parallel to the detector x and y direction and around the beam. Following the pyFAI geometry, the order of rotations is:

R_pyfai = R_3(rot_beam) * R_2(-rot_x) * R_1(-rot_y)

Note that rot_x and rot_y directors are left-handed (i.e. inverted.)

Parameters:

• center_x (float) – The position of the x beam center in pixels.

• center_y (float) – The position of the y beam center in pixels.

• det_dist (float) – The distance between sample and detector beam center in meters.

• **kwargs (dict) –

  Supported keyword arguments are:

  tiltfloat, optional

  The tilt of the detector, given in rotation unit. The default is 0.

  tilt_plane: float, optional

  The rotation of the tile plane of the detector, given in rot unit. The default is 0.

  rot_unitstr, optional

  The unit of the rotation angles. Allowed choices are ‘degree’ and ‘rad’. The default is degree.

set_default_params()

Set default entries.

This method will go through the supplied defaults iterable. If there are no entries for the Parameter keys, it will add a Parameter with default value.

set_detector_params_from_name(det_name: str)

Set the detector parameters based on a detector name.

This method will query the pyFAI library for the detector parameters and update the internal Parameters.

Parameters:

det_name (str) – The pyFAI name for the detector.

Raises:

NameError – If the specified detector name is unknown by pyFAI.

set_param_value(param_key: str, value: object)

Set a Parameter value.

This method overloads the inherited set_param_value method to update the linked parameters of X-ray energy and wavelength.

Parameters:

• param_key (str) – The Parameter identifier key.

• value (object) – The new value for the parameter. Depending upon the parameter, value can take any form (number, string, object, …).

Raises:

KeyError – If the key does not exist.

set_param_values(**kwargs: dict)

Set multiple parameter values at once.

Parameters:

**kwargs (dict) – The reference key and value pairs for all Parameters to be set.

set_param_values_from_dict(value_dict: dict)

Set the Parameter values from a dict with name, value paris.

Parameters:

value_dict (dict) – The dictionary with the stored information.

update_from_diffraction_exp(diffraction_exp: Self)

Update this DiffractionExperiment object’s Parameters from another instance.

The purpose of this method is to “copy” the other DiffractionExperiment’s Parameter values while keeping the reference to this object.

Parameters:

diffraction_exp (DiffractionExperiment) – The other DiffractionExperiment from which the Parameters should be taken.

update_from_pyfai_geometry(geometry: Geometry)

Update this DiffractionExperiment from a pyFAI geometry.

Parameters:

geometry (Geometry) – The geometry to be used.

update_param_values_from_kwargs(**kwargs: dict)

Update the Parameter values corresponding to the given keys.

Parameters:

**kwargs (dict) – The dictionary with Parameter refkeys and values.

update_params_from_init(*args: tuple, **kwargs: dict)

Update the Parameters from the given init args and kwargs.

Parameters:

• *args (Tuple) – The input arguments.

• **kwargs (Dict) – The input keyword arguments.

class pydidas.contexts.scan.Scan

Bases: ObjectWithParameterCollection

Class which holds the settings for the scan.

This class should only be instanciated through its factory, therefore guaranteeing that only a single instance exists. Please instanciate Scan only directly if you explicitly need to.

add_param(param: Parameter)

Add a parameter to the ParameterCollection.

This is a wrapper for the ParameterCollection.add_parameter method.

Parameters:

param (Parameter) – An instance of a Parameter object.

add_params(*params: tuple[Parameter | dict | ParameterCollection])

Add parameters to the object.

This method adds Parameters to the ParameterCollection of the object. Parameters can be either supplies as args or a ParameterCollection or dictionary in the form of <ref_key>: <Parameter>. This method is explicitly separate from the __init__ method to allow subclasses full control over args and kwargs.

Parameters:

*params (Tuple[Union[Parameter, dict, ParameterCollection]]) – Any Parameter or ParameterCollection

copy() → Self

Get a copy of the object.

Returns:

The object’s copy.

Return type:

ObjectWithParameterCollection

deepcopy() → Self

Get a deepcopy of the object.

Returns:

The object’s deepcopy.

Return type:

ObjectWithParameterCollection

export_to_file(filename: str | Path, overwrite: bool = False)

Export ScanContext to a file.

Parameters:

• filename (Union[str, pathlib.Path]) – The full filename.

• overwrite (bool) – Keyword to allow overwriting of existing files. The default is False.

classmethod get_default_params_copy() → ParameterCollection

Get a copy of the default ParameterCollection.

Returns:

A copy of the default ParameterCollection.

Return type:

ParameterCollection

get_frame_from_indices(indices: tuple) → int

Get the frame number based on the scan indices.

Note: For an image multiplicity > 1, this frame number corresponds to the first frame at this scan position.

Parameters:

indices (Union[tuple, list, np.ndarray]) – The iterable with the scan position indices.

Returns:

The frame index in the scan.

Return type:

int

get_frame_position_in_scan(frame_index: int)

Get the position of a frame number on scan coordinates.

Parameters:

frame (int) – The frame number.

Returns:

indices – The indices for indexing the position of the frame in the scan. The length of indices is equal to the number of scan dimensions.

Return type:

tuple

get_index_of_frame(frame_index: int) → int

Get the scan point index of the given frame.

Parameters:

frame_index (int) – The frame index.

Returns:

The scan point index.

Return type:

int

get_index_position_in_scan(index: int) → tuple

Get the scan coordinates of the given input index.

Parameters:

index (int) – The index of the scan point (i.e. the position in the ‘timeline’)

Returns:

The indices for indexing the position of the frame in the scan. The length of indices is equal to the number of scan dimensions.

Return type:

tuple

get_metadata_for_dim(index: int) → Tuple[str, str, ndarray]

Get the label, unit and range of the specified scan dimension.

Note: The scan dimensions are 0 .. 3 and follow the python convention of starting with zero.

Parameters:

index (Union[0, 1, 2, 3]) – The index of the scan dimension.

Returns:

• label (str) – The label / motor name for this scan dimension.

• unit (str) – The unit for the range.

• range (np.ndarray) – The numerical positions of the scan.

get_param(param_key: str) → Parameter

Get a parameter.

Note: This method returns the Parameter itself, not a copy.

Parameters:

param_key (str) – The key name of the Parameter.

Returns:

The Parameter object.

Return type:

Parameter

get_param_keys() → list[str]

Get the keys of all registered Parameters.

Returns:

The keys of all registered Parameters.

Return type:

list

get_param_value(param_key: str, *default: object, dtype: type | None = None, for_export: bool = False) → object

Get a Parameter value.

Parameters:

• param_key (str) – The key name of the Parameter.

• default (object) – The default value if the param_key does not exist.

• dtype (type, optional) – A datatype to convert the value into. If None, the native datatype is returned. The default is None.

• for_export (bool, optional) – An optional flag to force converting the Parameter value to an export-compatible format. This flag is not compatible with a specific dtype. The default is False.

Returns:

The value of the Parameter.

Return type:

object

get_param_values_as_dict(filter_types_for_export: bool = False) → dict

Get a dictionary with Parameter names and values only.

Parameters:

filter_types_for_export (bool) – Flag to return objects in types suitable for exporting (i.e. pickleable).

Returns:

name_val_pairs – The dictionary with Parameter <name>: <value> pairs.

Return type:

dict

get_params(*param_keys: tuple[str, ...]) → list[Parameter]

Get multiple parameters based on their reference keys.

Parameters:

*param_keys (Tuple[str, ...]) – Any number of reference keys.

Returns:

A list with the Parameter instances referenced by the supplied keys.

Return type:

list

get_range_for_dim(index: int) → ndarray

Get the Scan range for the specified dimension.

Note: The scan dimensions are 0 .. 3 and follow the python convention of starting with zero.

Parameters:

index (Union[0, 1, 2, 3]) – The scan dimension

Returns:

The scan range as numpy array.

Return type:

np.ndarray

import_from_file(filename: str | Path)

Import ScanContext from a file.

Parameters:

filename (Union[str, pathlib.Path]) – The full filename.

property n_points: int

Get the total number of points in the Scan.

Returns:

The total number of images.

Return type:

int

property ndim: int

Get the number of dimensions in the ScanContext.

This method is a simplified wrapper for the ParameterValue “scan_dim”.

Returns:

The number of dimensions.

Return type:

int

property param_keys: list[str]

Get the keys of all stored Parameters.

Returns:

The keys of all stored Parameters.

Return type:

list[str]

property param_values: dict

Get the values of all stored Parameters along with their refkeys.

Returns:

The refkey, value pairs for all stored Parameters.

Return type:

Dict

print_param_values()

Print the name and value of all Parameters.

q_settings_get(key: str, dtype: type | None = None, default: object | None = None) → object

Get the value from a QSetting key.

Parameters:

• key (str) – The QSetting reference key.

• dtype (Union[type, None], optional) – A return datatype. If not None, the output will be returned as dtype(value), otherwise, the generic string/int will be returned. The default is None.

• default (type, optional) – The default value which is returned if the key defaults to None. The default is None.

Returns:

value – The value, converted to the type associated with the Parameter referenced by param_key or dtype, if given.

Return type:

object

q_settings_set(key: str, value: object)

Set the value of a QSettings key.

Parameters:

• key (str) – The name of the key.

• value (object) – The value to be stored.

restore_all_defaults(confirm: bool = False)

Restore the default values to all entries.

Parameters:

confirm (bool) – Confirmation flag as safety feature.

set_default_params()

Set default entries.

This method will go through the supplied defaults iterable. If there are no entries for the Parameter keys, it will add a Parameter with default value.

set_param_value(param_key: str, value: object)

Set a parameter value.

Parameters:

• param_key (str) – The key name of the Parameter.

• value (object) – The value to be set. This has to be the datatype associated with the Parameter.

set_param_values(**kwargs: dict)

Set multiple parameter values at once.

Parameters:

**kwargs (dict) – The reference key and value pairs for all Parameters to be set.

set_param_values_from_dict(value_dict: dict)

Set the Parameter values from a dict with name, value paris.

Parameters:

value_dict (dict) – The dictionary with the stored information.

property shape: tuple

Get the shape of the Scan.

Returns:

The tuple with an entry of the length for each dimension.

Return type:

tuple

update_from_dictionary(scan_dict: dict)

Update the Scan from an imported dictionary.

Parameters:

scan_dict (dict) – The dictionary with the data to import.

update_from_scan(scan: Self)

Update this Scan onject’s Parameters from another Scan.

The purpose of this method is to “copy” the other Scan’s Parameter values while keeping the reference to this object.

Parameters:

scan (Scan) – The other Scan from which the Parameters should be taken.

update_param_values_from_kwargs(**kwargs: dict)

Update the Parameter values corresponding to the given keys.

Parameters:

**kwargs (dict) – The dictionary with Parameter refkeys and values.

update_params_from_init(*args: tuple, **kwargs: dict)

Update the Parameters from the given init args and kwargs.

Parameters:

• *args (Tuple) – The input arguments.

• **kwargs (Dict) – The input keyword arguments.

Subpackage with pydidas contexts.

class pydidas.contexts.DiffractionExperimentIo(clsname, bases, attrs)

Metaclass for DiffractionExperiment exporters and importers which holds the registry with all associated file extensions for importing / exporting DiffractionExperiment or DiffractionExperimentContexts.

classmethod clear_registry()

Clear the registry and remove all items.

classmethod export_to_file(filename, **kwargs)

Call the concrete export_to_file method in the subclass registered to the extension of the filename.

Parameters:

• filename (str) – The full filename and path.

• tree (pydidas.workflow.WorkflowTree) – The instance of the WorkflowTree

• kwargs (dict) – Any kwargs which should be passed to the udnerlying exporter.

classmethod get_registered_formats()

Get the names of all registered formats and the corresponding file extensions.

Returns:

A dictionary with <format name> : <extensions> entries.

Return type:

dict

classmethod get_string_of_formats()

Get a list of strings with the different formats and extensions.

This class method is designed to have an easy way of creating the required lists for QFileDialog windows.

Returns:

The string entries for each format and one entry for all formats, each separated by a “;;”.

Return type:

str

classmethod import_from_file(filename: str, diffraction_exp: object | None = None)

Call the concrete import_from_file method in the subclass registered to the extension of the filename.

Parameters:

• filename (str) – The full filename and path.

• diffraction_exp (Union[DiffractionExperiment, None], optional) – The DiffractionExperiment instance to be updated.

classmethod is_extension_registered(extension)

Check if the extension of filename corresponds to a registered class.

Parameters:

extension (str) – The extension to be checked.

Returns:

Flag whether the extension is registered or not.

Return type:

bool

mro()

Return a type’s method resolution order.

classmethod register_class(new_class, update_registry=False)

Register a class as object for its native extensions.

Parameters:

• new_class (type) – The class to be registered.

• update_registry (bool, optional) – Keyword to allow updating / overwriting of registered extensions. The default is False.

Raises:

KeyError – If an extension associated with new_class has already been registered and update_registry is False.

classmethod verify_extension_is_registered(ext)

Verify the extension is registered with the MetaClass.

Parameters:

ext (str) – The file extension

Raises:

TypeError – If the extension is not registered.

class pydidas.contexts.ScanIo(clsname, bases, attrs)

Metaclass for ScanContext exporters and importers.

The ScanIo holds the registry with all associated file extensions for importing / exporting Scan (and ScanContexts).

classmethod clear_registry()

Clear the registry and remove all items.

classmethod export_to_file(filename, **kwargs)

Call the concrete export_to_file method in the subclass registered to the extension of the filename.

Parameters:

• filename (str) – The full filename and path.

• tree (pydidas.workflow.WorkflowTree) – The instance of the WorkflowTree

• kwargs (dict) – Any kwargs which should be passed to the udnerlying exporter.

classmethod get_registered_formats()

Get the names of all registered formats and the corresponding file extensions.

Returns:

A dictionary with <format name> : <extensions> entries.

Return type:

dict

classmethod get_string_of_formats()

Get a list of strings with the different formats and extensions.

This class method is designed to have an easy way of creating the required lists for QFileDialog windows.

Returns:

The string entries for each format and one entry for all formats, each separated by a “;;”.

Return type:

str

classmethod import_from_file(filename: str, scan: Scan | None = None)

Import a Scan from file and update the given Scan object.

Call the concrete import_from_file method in the subclass registered to the extension of the filename.

Parameters:

• filename (str) – The full filename and path.

• scan (Optional[Scan]) – The Scan object to be updated. If None, the generic ScanContext is used. The default is None.

classmethod is_extension_registered(extension)

Check if the extension of filename corresponds to a registered class.

Parameters:

extension (str) – The extension to be checked.

Returns:

Flag whether the extension is registered or not.

Return type:

bool

mro()

Return a type’s method resolution order.

classmethod register_class(new_class, update_registry=False)

Register a class as object for its native extensions.

Parameters:

• new_class (type) – The class to be registered.

• update_registry (bool, optional) – Keyword to allow updating / overwriting of registered extensions. The default is False.

Raises:

KeyError – If an extension associated with new_class has already been registered and update_registry is False.

classmethod verify_extension_is_registered(ext)

Verify the extension is registered with the MetaClass.

Parameters:

ext (str) – The file extension

Raises:

TypeError – If the extension is not registered.