The ScanContext class#

Introduction#

The ScanContext is the pydidas Singleton instance of the Scan class. It is used for storing and accessing global information about the scan layout and generic infomation like title, directory and file naming patterns.

Stored information include

Dimensionality (for arranging results)

Name (for metadata and titles only)

Directory (for data loading)

Filename pattern (for data loading)

Scan multiplicity (the number of each frames at each scan point).

Starting index of files/frames

Index stepping

Information for each scan dimension

Name for the scan dimension (for reference, e.g. motor name, time)

Number of scan points

Step width between two scan points

Offset of the first scan points

Unit of the scan direction

These information allow to arrange the processed datasets in the correct order and to add metadata about the scan to plots and stored datasets.

All objects are stored as Parameters and can be accesses as described in the basic tutorial. A full list of Parameters is given in List of all ScanContext Parameters.

Its instance can be obtained by calling the following code:

>>> import pydidas
>>> SCAN = pydidas.contexts.ScanContext()

Configuring the ScanContext#

Global Parameters#

The ScanContext has global Parameters for generic information, listed in detail below:

ScanContext Parameter name	data type	description
scan_dim	int	The number of dimensions in the scan.
scan_title	str	The scan title. This Parameter is only used for plot titles and metadata.
scan_base_directory	pathlib.Path	The base directory for finding the files of the scan.
scan_name_pattern	str	The naming pattern of the scan files. Use hashes ‘#’ for wildcards which will be replaced by indices.
scan_start_index	int	The starting index to subsititute the wildcards in the name pattern.
scan_multiplicity	int	The number of frames acquired at each scan point. Note: If you want to handle multiple images individually, add them as an additional scan dimension.
scan_multi_image_handling	str	Flag how to handle multiple images. Choices are averaging or summation.

>>> import pydidas
>>> SCAN = pydidas.contexts.ScanContext()
>>> SCAN.set_param_value('scan_name', 'Test_42')
>>> SCAN.set_param_value('scan_dim', 2)
>>> SCAN.set_param_value('scan_base_directory', '/home/user/dir_to_data')

Note

The number of dimensions in the scan is limited to 4 which should be sufficient for all applications. If you have a specific application which required a larger number of dimensions, please get in contact with the pydidas development team to discuss your needs.

Parameters for each dimension#

The Parameters for each dimension are distinguished by a dimension index in the Parameter names, respectively. In the description, the numbers are substituted by an i for generality. It is important to preserve the scan order from the experiment to have the results in the correct structure.

Each dimension is described by a total of five Parameters:

name	type	default	description
scan_dim{i}_label	str	[empty str]	The axis name for scan direction i. This information will only be used for labelling.
scan_dim{i}_n_points	int	0	The number of scan points in scan direction i.
scan_dim{i}_delta	float	2	The step width between two scan points in scan direction i.
scan_dim{i}_offset	float	0	The coordinate offset of the movement in scan direction i (i.e. the counter / motor position for scan step #0)
scan_dim{i}_unit	str	[empty str]	The unit of the movement / steps / offset in scan direction i. This value will only be used for labelling these numbers.

Note

The only Parameter that must be set for each dimension is the number of points scan_dim{i}_n_points to allow pydidas to organize results in the correct grid.

As example, let us configure a scan with 2 dimensions. The slow motor is the x-axis with 25 scan points in the range [-12.0 mm, -11.5 mm, …, 12.0 mm] and the fast motor is the z-axis with 100 points in the range [150 nm, 225, nm, …, 7575 nm]:

>>> import pydidas
>>> SCAN = pydidas.contexts.ScanContext()
>>> SCAN.set_param_value('scan_dim', 2)
>>> SCAN.set_param_value('scan_dim0_label', 'x')
>>> SCAN.set_param_value('scan_dim0_n_points', 25)
>>> SCAN.set_param_value('scan_dim0_delta', 0.5)
>>> SCAN.set_param_value('scan_dim0_offset', -12.0)
>>> SCAN.set_param_value('scan_dim0_unit', 'mm')
>>> SCAN.set_param_value('scan_dim1_label', 'x')
>>> SCAN.set_param_value('scan_dim1_n_points', 100)
>>> SCAN.set_param_value('scan_dim1_delta', 75)
>>> SCAN.set_param_value('scan_dim1_offset', 150)
>>> SCAN.set_param_value('scan_dim1_unit', 'nm')

Import of scan metadata#

pydidas includes the option to import metadata from beamlines directly. Please contact your beamline local contact for details.

Import functions will be implemented as required and depending on the scan metadata available at the beamlines.

List of all ScanContext Parameters#

scan_dim (type: int, default: 2, unit: “”)
The scan dimensionality. This defines the number of processed dimensions.
scan_title (type: str, default: “”, unit: “”)
The scan name or title. This is used exclusively for reference in axis labels and result exporters.
scan_base_directory (type: Path, default: “.”, unit: “”)
The base directory in which the raw scan data is stored.
scan_name_pattern (type: str, default: “”, unit: “”)
The name pattern for scan files, subdirectories etc. User hashes (“#”) to mark wildcard characters to be filled in with the current index.
scan_start_index (type: int, default: 0, unit: “”)
The starting index for files etc. of the first point in the scan.
scan_index_stepping (type: int, default: 1, unit: “”)
The stepping of the index, i.e. the difference in the index between two adjacent scan points.
scan_multiplicity (type: int, default: 1, unit: “”)
The image multiplicity: The number of frames acquired at each unique scan point. Use this value only if the multiple images should be combined. Otherwise, use an additional scan dimension for the multiplicity.
scan_multi_image_handling (type: str, default: “Average”, unit: “”)
The handling instructions for multiple frames at each scan point. Can be either “Average” or “Sum”.

The following Parameters exist for each scan dimension, i.e. scan_dim{i}_label stands for scan_dim0_label, scan_dim1_label, scan_dim2_label, scan_dim3_label. For clarity, only the generic form is described here.

scan_dim{i}_label (type: str, default: “”)
The axis name for scan direction {i}. This information will only be used for labelling.
scan_dim{i}_n_points (type: int, default: 0)
The number of scan points in scan direction {i}.
scan_dim{i}_delta (type: float, default: 1)
The step width between two scan points in scan direction {i}.
scan_dim{i}_offset (type: float, default: 0)
The coordinate offset of the movement in scan direction {i} (i.e. the counter / motor position for scan step #0).
scan_dim{i}_unit (type: str, default: “”)
The unit of the movement / steps / offset in scan direction {i}.