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.

API Reference for the Measurement class is found here: https://easyscience.github.io/imaging-lib/0.0.2/api-reference/measurement/measurement/

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)

Implementation details

The Measurement class implements a "rebin" method, which is technically not rebinning, since the data has already been histogrammed and we no longer have access to the neutron count data. Instead it is using the resize method from essimaging to merge existing bins.
Hence it only accepts whole integers for rebinning, reflecting how many bins to merge in each direction.

It is named "rebin" in easyimaging because that is how it is understood in the imaging community.

Any subsequent rebinning will rebin the already rebined image again, because this seemed the most natural behaviour, to recover the original image, the "revert_rebin" method exists.

Internally, when rebinning/resizing is done, a new array is created under _rebinned_data_array and the original array is kept under _full_data_array. The internal property _data_array returns the rebinned data array if it exists, otherwise it returns the full data array. Using the internal property thus ensures methods acts on whatever is the "current" image for the user.

Link to the ADR suggestion:
#1