Dataset Plug-ins

To use your own raw data with iris, a plug-in functionality is made available.

Plug-ins are Python modules that implement a subclass of AbstractRawDataset, and should be placed in ~/iris_plugins (C:\Users\UserName\iris_plugins on Windows). Subclasses of AbstractRawDataset are automatically detected by iris and can be used via the GUI.

Installed plug-ins can be imported from iris.plugins:

from iris.plugins import DatasetSubclass

which would work if the DatasetSubclass is defined in the file ~/iris_plugins/<anything>.py. Example plug-ins is available here. Plug-ins used by members of the Siwick research group are visible here.

Installing a plug-in

To install a plug-in that you have written in a file named ~/myplugin.py:

import iris
iris.install_plugin('~/myplugin.py')

Installing a plug-in in the above makes it immediately available.

install_plugin(path) Install and load an iris plug-in.

Subclassing AbstractRawDataset

To take advantage of iris’s DiffractionDataset and PowderDiffractionDataset, an appropriate subclass of AbstractRawDataset must be implemented. This subclass can then be fed to DiffractionDataset.from_raw() to produce a DiffractionDataset.

How to assemble a AbstractRawDataset subclass

Ultrafast electron diffraction experiments typically have multiple scans. Each scan consists of a time-delay sweep. You can think of it as one scan being an experiment, and so each dataset is composed of multiple, equivalent experiments.

To subclass AbstractRawDataset, the method AbstractRawDataset.raw_data() must minimally implemented. It must follow the following specification:

AbstractRawDataset.raw_data(timedelay, scan=1, **kwargs)

Returns an array of the image at a timedelay and scan.

Parameters:
  • timdelay (float) – Acquisition time-delay.
  • scan (int, optional) – Scan number. Default is 1.
  • kwargs – Keyword-arguments are ignored.
Returns:

arr

Return type:

~numpy.ndarray, ndim 2

Raises:
  • ValueError : if timedelay or scan are invalid / out of bounds.
  • IOError : Filename is not associated with an image/does not exist.

For better performance, or to tailor data reduction to your data acquisition scheme, the following method can also be overloaded:

AbstractRawDataset.reduced(exclude_scans=None, align=True, normalize=True, mask=None, processes=1, dtype=<class 'float'>)

Generator of reduced dataset. The reduced diffraction patterns are generated in order of time-delay.

This particular implementation normalizes diffracted intensity of pictures acquired at the same time-delay while rejecting masked pixels.

Parameters:
  • exclude_scans (iterable or None, optional) – These scans will be skipped when reducing the dataset.
  • align (bool, optional) – If True (default), raw diffraction patterns will be aligned using the masked normalized cross-correlation approach. See skued.align for more information.
  • normalize (bool, optional) – If True (default), equivalent diffraction pictures (e.g. same time-delay, different scans) are normalized to the same diffracted intensity.
  • mask (array-like of bool or None, optional) – If not None, pixels where mask = True are ignored for certain operations (e.g. alignment).
  • processes (int or None, optional) – Number of Processes to spawn for processing.
  • dtype (numpy.dtype or None, optional) – Reduced patterns will be cast to dtype.
Yields:

pattern (~numpy.ndarray, ndim 2)

AbstractRawDataset metadata

AbstractRawDataset subclasses automatically include the following metadata:

  • date (str): Acquisition date. Date format is up to you.
  • energy (float): Electron energy in keV.
  • pump_wavelength (int): photoexcitation wavelength in nanometers.
  • fluence (float): photoexcitation fluence \(\text{mJ}/\text{cm}**2\).
  • time_zero_shift (float): Time-zero shift in picoseconds.
  • temperature (float): sample temperature in Kelvins.
  • exposure (float): picture exposure in seconds.
  • resolution (2-tuple): pixel resolution of pictures.
  • time_points (tuple): time-points in picoseconds.
  • scans (tuple): experimental scans.
  • camera_length (float): sample-to-camera distance in meters.
  • pixel_width (float): pixel width in meters.
  • notes (str): notes.

Subclasses can add more metadata or override the current metadata with new defaults.

All proper subclasses of AbstractRawDataset are automatically added to the possible raw dataset formats that can be loaded from the GUI.