The Measurement Object

[damskii9992]

General

The Measurement object is usually the first easyimaging object that a user creates. It is responsible for loading in the measured data, inspecting the data in various ways, perform simple edits on the data, like re-binning of it, and to create and hold Regions Of Interest (ROIs).

The data is held in the Measurement object as a Scipp DataArray with strictly defined coordinates and dimensions. The Measurement object is responsible for converting calls to Scipp syntax in order to interface with the Scipp DataArray.

Creating the Measurement object

The Measurement object can be instantiated in 3 different ways, directly in a notebook from a pre-existing Scipp DataArray, requiring no file-loading, from a SciTiff (the reduced data-format of choice) and from a regular tiff stack.

Directly from a Scipp DataArray

To make smoother notebooks combining essimaging for the reduction and EasyImaging for the analysis, it is possible to instantiate the Measurement class directly from a Scipp DataArray:

measurement = Measurement(data_array = Scipp.DataArray)

Note

This has very strict requirements on the contents of the given Scipp DataArray. Namely the array must have the dimensions x, y, and t and the coordinate tof in the dimension of t with a unit of time. If the DataArray does not fulfill this requirement, the constructor fails and the Measurement isn't created.

The DataArray can optionally have x and y coordinates, representing the physical positions of the pixels in space, if these exists in the DataArray they must be in the dimensions of x and y respectively and have a unit of length.

The DataArray can have masks, which will be respected, but any other coordinates of the DataArray will be ignored.

Tip

Here is an example of a valid Scipp DataArray:

import scipp as sc
from easyimaging import Measurement

tof = sc.arange('t', 0, 10, 1, unit='s')
x = sc.arange('x', 0, 7, 1, unit='m')  # Optional
y = sc.arange('y', 0, 7, 1, unit='m')  # Optional
coords = {'tof': tof, 'x': x, 'y': y}
data = sc.ones(dims=['t', 'y', 'x'], shape=[10, 6, 6])

data_array = sc.DataArray(data=data, coords=coords)

measurement = Measurement(data_array=data_array)

From a SciTiff

A Measurement object can also be instantiated by a class method which loads a SciTiffs using the SciTiff packages loader:

mesurement = Measurement.from_scitiff(filename = './best_folder/best_scitiff_data.tiff')

Which will call scitiff.load_scitiff(file_path=filename') to construct the Scipp DataArrayused to then construct theMeasurement`.

From a Tiff stack

For loading data which was not saved as a scitiff, such as data from other facilities, a loader is also
we need a loader which construct the Scipp Data Group from multiple tiff files. The loader should load all tiff files in a folder matching the user-given pattern, and construct the time-dimension by a user-given array or step-size.

measurement = Measurement.from_tiff_files(folder_path = './best_folder', file_pattern='img_*', time_of_flights=np.array)

The time_of_flights will take either a step-size or a list or numpy array of times for each image loaded which is located in the folder_path and matches the pattern.

The RegionOfInterest list

The Measurement object will have a list of RegionOfInterest objects which is initially empty. A RegionOfInterest object defines a region in 4-dimensional space (x,y,z,t) of the full image. When passing a Measurement object to an Analysis object, an optional "region_of_interests" keyword can be used to only fit the given region of interests. Similarly the spectrum method of the Measurement object takes the "region_of_interests" keyword to return the spectrum for a region rather than the entire sample:

Measurement.spectrum(region_of_interest = ['First Region', 'Second Region'])

The keyword can be the name of a single RegionOfInterest object in the Measurement or a list of names, in which case their spectra will be summed up.

Creating a RegionOfInterest
Initially only square regions will be allowed, but it is planned to extend this in the future. As such each RegionOfInterest object is defined by the 2 points defining the square, the start and end points of the square. These points can be given manually to the create_region_of_interest method:

measurement.create_region_of_interest(name='First Region', x_start = Scipp.scalar, y_start = Scipp.scalar, x_end = Scipp.scalar, y_end = Scipp.scalar). 

Or by using the interactive widget from essimaging:

measurement.draw_region_of_interests()

In which case their names will simply me: 'RegionOfInterest_0' etc.

Utility methods

The Measurement object will additionally provide a number of utility methods for user usage:

• .plot_spectrum will plot the spectrum. Uses '.spectrum' to get the spectrum and thus also accepts the region_of_interests keyword.
• .view will show the time-averaged image if no time is defined, otherwise will show image at that time frame.
• '.interactive_view' will use the Scipp slicer widget to allow the user to drag a slider to view different images.
• probably more