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, *, target=None)

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`
`target`	`(KeyData, DataArray)`	Optional target positions of the scanned motor. If passed, this will be used to determine steps, and trains where the actual motor position (motor parameter) differs by more than resolution are discarded.	`None`

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.

from_motor_targets `classmethod` ¤

from_motor_targets(motor: SourceData, *, tolerance=None, name=None)

Make a Scan object based on the target positions of a motor

The steps are defined by the motor target positions. Points are only included if the actual position is within tolerance of the target.

plot ¤

plot(figsize=(10, 6), 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.

group_data ¤

group_data(data)

Group data labelled with train IDs by scan step.

data can be an xarray object with trainId coordinates, or a pandas object with train IDs in the index. The train IDs can be one level in a MultiIndex, so long as the level is named trainId.

Returns a GroupBy object from the relevant library (e.g. a DataArrayGroupedBy for a DataArray input, or a DataFrameGroupBy/SeriesGroupBy for a DataFrame or Series input).

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`

Scans

extra.components.Scantool ¤

source_name property ¤

source property ¤

active property ¤

scan_type property ¤

acquisition_time property ¤

motors property ¤

motor_devices property ¤

steps property ¤

start_positions property ¤

stop_positions property ¤

info ¤

format ¤

extra.components.Scan ¤

name property ¤

steps property ¤

positions property ¤

positions_train_ids property ¤

from_motor_targets classmethod ¤

plot ¤

bin_by_steps ¤

plot_bin_by_steps ¤

split_by_steps ¤

group_data ¤

info ¤

format ¤

source_name `property` ¤

source `property` ¤

active `property` ¤

scan_type `property` ¤

acquisition_time `property` ¤

motors `property` ¤

motor_devices `property` ¤

steps `property` ¤

start_positions `property` ¤

stop_positions `property` ¤

name `property` ¤

steps `property` ¤

positions `property` ¤

positions_train_ids `property` ¤

from_motor_targets `classmethod` ¤