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: Returns: arr
Return type: ~numpy.ndarray, ndim 2
Raises: - ValueError : if
timedelay
orscan
are invalid / out of bounds. - IOError : Filename is not associated with an image/does not exist.
- ValueError : if
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.