Scans

extra.components.Scantool

Scantool(run, src=None)

Interface for the European XFEL scantool (Karabacon).

        -----------------------------------------------------------
In [1]: |scantool = Scantool(run)                                 |
        |scantool.info()                                          |
        -----------------------------------------------------------
Out[1]: Scantool (MID_RR_SYS/MDL/KARABACON) configuration:
          Scan type: dscan
          Acquisition time: 1.0s

        Motors:
          DET2_TX (MID_EXP_DES/MOTOR/DET2_TX): -0.05 -> 0.05, 100 steps

See the scantool documentation for more information about the device itself.

Parameters:

Name	Type	Description	Default
run	DataCollection	A run containing the scantool.	required
src	str	The device name of the scantool. If this is not passed the class will try to find the right device automatically.	None

source_name property

source_name: str

The name of the scantool device.

source property

source: SourceData

SourceData object for the device.

active property

active: bool

Boolean to indicate whether the scantool was used during the run.

scan_type property

scan_type: str

The type of scan configured (ascan, dscan, mesh, etc).

acquisition_time property

acquisition_time: float

Acquisition time in seconds.

motors property

motors: list

List of aliases of the motors being moved.

Note that these are scantool-specific aliases, not EXtra-data aliases.

motor_devices property

motor_devices: dict

A dictionary mapping motor aliases to their actual device names.

Warning

This property is obtained by parsing a configuration string, which may not be compatible with previous versions of the scantool. If it was not possible to get the device names then a warning will be printed when initializing the class, and this property will be None.

steps property

steps: dict

A dictionary mapping motor aliases to the number of steps they were scanned over.

start_positions property

start_positions: dict

A dictionary mapping motor aliases to their start positions.

stop_positions property

stop_positions: dict

A dictionary mapping motor aliases to their stop positions.

info

info(compact=False)

Print information about the scantool from Scantool.format().

format

format(compact=False)

Format information about the scantool as a string.

Parameters:

Name	Type	Description	Default
compact	bool	Whether to print the information in a compact 1-line format or a multi-line format.	False

extra.components.Scan

Scan(
    motor,
    name=None,
    resolution=None,
    min_trains=None,
    intra_step_filtering=1,
)

Detect steps in a motor scan.

Example usage in a Jupyter notebook:

        -----------------------------------------------------------
In [1]: |s = Scan(run["MOTOR/MCMOTORYFACE"])                      |
        |s.info()                                                 |
        -----------------------------------------------------------
Out[1]: Scan over MOTOR/MCMOTORYFACE.actualPosition from -0.5800 to -0.5600:
         Steps: 21
         Scan time: 0:17:54
         Average step length: 511.33 trains (51.13s)
         Average step size: 1.00e-03 [arb. u.]

        Detection parameters:
         resolution: 5.00e-04
         min_trains: 235

        ----------------------------------------------------------
In [2]: |s.plot() # Check the detection results                  |
        ----------------------------------------------------------

The class tries to detect the best parameters automatically, but it will still fail in some situations. If that happens either the resolution or min_trains parameters (unlikely to be both) will need to be set manually, typically on a per-motor rather than per-run basis.

Note

You should always check the results of the detection with Scan.plot() to verify that they're correct.

Parameters:

Name	Type	Description	Default
motor	(SourceData, KeyData, DataArray)	An object that contains the motor positions and train IDs. If it's a SourceData object the actualPosition key will be used. Note that if a xarray.DataArray is passed it must have a trainId coordinate with the train IDs (i.e. obtained with KeyData.xarray()). Raw Numpy arrays are not allowed.	required
resolution	float	The usable resolution of the motor. Ideally this should be slightly above the noise level of the motor (and below the step size of the scan). It will be guessed if not passed explicitly. This is the trickiest parameter to guess automatically. For example, if it's set too high then multiple real steps will be detected as single steps. And if it's set too low and there's a lot of drift in the motor steps, there can be multiple detected steps within a single real step.	None
min_trains	int	The minimum number of trains per-step in the scan. It will be guessed if not passed explicitly. The automatic guessing rarely fails badly. Usually you will only need to tweak this if the length of the steps varies a lot and some of the smaller steps are being cut out (this often happens with energy scans).	None
intra_step_filtering	float	A factor that influences how aggressively noisy trains within a step will be filtered out. Higher values mean less aggressive and lower values mean more aggressive. This factor is used to remove trains in a step that are outside a certain range of the mean value in the step, the main purpose being to remove trains on the boundaries of a step. Try tweaking this value if there are too many/too few trains being filtered around a step.	1

name property

name: str

Name of the device being scanned.

steps property

steps: list

List of (position, train_ids) tuples for each step in the scan.

positions property

positions: ndarray

Array of positions for each step.

positions_train_ids property

positions_train_ids: list

List of train IDs for each position.

plot

plot(ax=None)

Visualize the scan steps.

Each step is plotted in a different color on top of the motor positions. On a long scan with lots of steps you'll probably want to zoom in to check the individual steps.

Example plot:

bin_by_steps

bin_by_steps(data, uncertainty_method='std')

Average train-resolved data within each scan step.

This will return a DataArray containing the averaged value of data over each step in the scan, along with position, counts, and uncertainty coordinates containing the position/counts/uncertainty for each step. The .name property will be set to data.name, and the following attributes will be set:

• motor: scan.name
• uncertainty_method: the uncertainty_method that was passed, indicating either the standard deviation or standard error.

Parameters:

Name	Type	Description	Default
data	DataArray	A train-resolved (i.e. with a trainId coordinate) array to bin.	required
uncertainty_method	str	Can be set to std to use the standard deviation (i.e. the 1-sigma region) or stderr to use the standard error.	'std'

plot_bin_by_steps

plot_bin_by_steps(
    data,
    uncertainty_method="std",
    title=None,
    xlabel=None,
    ylabel=None,
    ax=None,
    figsize=(9, 5),
)

Plot step-averaged data.

This calls Scan.bin_by_steps() and plots the result. Note that while it's possible to explicitly specify the title/xlabel/ylabel, it's recommended to set data.name and scan.name and let the plot settings be inferred automatically.

Example plot with data.name == "ROI intensity" and scan.name == "Theta":

Parameters:

Name	Type	Description	Default
data	DataArray	A train-resolved array to pass to Scan.bin_by_steps().	required
uncertainty_method	str	Same as in Scan.bin_by_steps().	'std'
title	str	The title of the plot.	None
xlabel	str	The xlabel of the plot.	None
ylabel	str	The ylabel of the plot.	None
ax	Axes	The axes to plot on. A figure will be created if this is not set.	None
figsize	tuple	The figure size. Only used if ax=None.	(9, 5)

split_by_steps

split_by_steps(data)

Split an EXtra or EXtra-data object, or a DataArray, into scan steps.

This will yield one shorter object of the same type for each step. It should work for any object with a .select_trains() method, and for xarray DataArray objects with a 'trainId' coordinate.

info

info(compact=False)

Print information about the scan from Scan.format()

format

format(compact=False) -> str

Format information about the scan as a string.

Parameters:

Name	Type	Description	Default
compact	bool	Whether to format the information in a one-line or multi-line string.	False