ADR Suggestion The Measurement Object

[damskii9992]

General

Following the discussion of the Top-level API in https://github.com/orgs/easyscience/discussions/29, the Experiment object is one of the 5 main objects in the API which the user will interact with.
The Experiment object is responsible for handling both the measured data and the instrument model of an experiment. I.e. everything directly related to the experiment.

Current Implementation

The Experiment object has not currently been implemented

Proposed Implementation

The Experiment object will contain two objects itself, the InstrumentModel object, and the Measurement object, as well as a number of utility functions.

The InstrumentModel Object

The InstrumentModel object will contain any physics which is related to the specific experimental setup used. It is added on top of the idealized SampleModel when fitting, to account for experimental features in order to produce a more realistic model that can be fit to the experimental data.
A list of pre-defined InstrumentModels will be provided for common instruments and setups, such as the main experimental setup for the imaging beamline ODIN at ESS, but custom InstrumentModels can also be defined and saved for future use.
The InstrumentModel will include the following experimental physics:

• Background
• Resolution function
• Full flight-path for ToF->Wavelength conversion
• Averaging kernel
• (Possibly) Forward scattering model with sample-to-detector distance

The Measurement Object

The Measurement object will contain the measured data in the form of a Scipp Data Group, together with a list of Region Of Interests (ROIs).
The Measurement Object is responsible for converting calls to Scipp syntax in order to interface with the Scipp Data Group and to interface with various data loaders.

The RoiSpectrum Object

The Experiment object will include the very critical method:

Experiment.roi_spectrum(roi=roi)

Which will return a RoiSpectrum Object by applying the given ROI.
The RoiSpectrum object will also inherit from BaseExperiment and contain similar fields to the Experiment object defined here.
The InstrumentModel will be inherited from the Experiment object, but the Measurement object will contain the 1D spectrum of the used ROI region rather than the full data stack.
The RoiSpectrum will additionally contain the ROI used to define it and a reference to its parent Experiment object.

Utility methods

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

• .load_scitiff will load a scitiff file and create a new InstrumentModel if the scitiff contains any InstrumentModel fields.
• .load_tiff will load a basic tiff file. Will require a timestep or a list of times to define ToF for each frame.
• .load_instrument_model will load a previously saved InstrumentModel
• .set_instrument_model will set an InstrumentModel, either user-defined or from the pre-defined list.
• .plot will plot the spectrum of the (default first) ROI in the ROI list, if any, otherwise will assume the whole image as ROI.
• .plot_model(sample_model=SampleModel) will call the class method of the Analysis object to plot the theoretical spectrum with the provided SampleModel and the InstrumentModel applied, according to https://github.com/orgs/easyscience/discussions/29
• .calculate_model(sample_model=SampleModel) will call the class method of the Analysis object to calculate the theoretical spectrum with the provided SampleModel and the InstrumentModel applied, according to https://github.com/orgs/easyscience/discussions/29
• .view will show the time-averaged image if no time is defined, otherwise will show image at that time frame.
• .ROI_list will print the list of ROI's
• .add_ROI will add a new ROI to the list of ROIs
• .ROI_selector will open up the image and allow the user to define a ROI using the mouse.
• probably more

[rozyczko]

As mentioned earlier, my issue with this is that RoiSpectrum name is misleading. Whereas we assume Experiment is an object which contains instrumental parameters and reduced data, the same can't be said about RoiSpectrum. This name makes me think (and maybe other users?) that this is just data. A spectrum is just one piece of information - we still need the instrumental params.

Maybe the idea is to have the dataset (profile, spectrum) a separate object, which can be prepared before sending off to Analysis, and have instrumental parameters a different object?
We would have Model, Profile (Spectrum), and Parameters as separate objects, but tied to each other (in Diffraction - a model to dataset, and a dataset to parameters)?

[damskii9992]

As mentioned earlier, my issue with this is that RoiSpectrum name is misleading

Maybe ExperimentSubset then? Or ExperimentRegion? Or if we're okay with abbreviations: ExperimentROI?

We would have Model, Profile (Spectrum), and Parameters as separate objects, but tied to each other (in Diffraction - a model to dataset, and a dataset to parameters)?

Then we would be back to having to add another page in the GUI or give up on the 1-to-1 correspondence between pages in the GUI and objects in the lib. But if we do that I would propose the names: Model (or SampleModel), Measurement and Instrument (or InstrumentModel). I would be okay with adding another page/object to split up Experiment into Measurement and Instrument.
It seems we are struggling quite a bit to fit stuff into the Experiment object (which also has quite a few responsibilities!).

[rozyczko]

SampleModel and ExperimentModel with immutable ExperimentData would probably look best. Yes, this means we would have to redesign the GUI tabs if we want to keep 1:1 correspondence (?)

OR: be explicit in naming GUI regions and name the profile region and instrument region (right panel) visibly

[henrikjacobsenfys]

Slight nitpick here, but surely the forward scattering is also sample dependent? In this case, I'm not sure where it belongs, but it's not purely InstrumentModel.

[damskii9992]

This is technically correct, but I believe it can be modeled with a generic black-body model with the main parameter being the sample to detector distance.

[damskii9992]

Based on the discussion here and my own experience developing the Minimal Working Product of the "Measurement" page in the EasyImaging GUI, I am leaning towards having an extra primary object as proposed above. So in Imaging, the primary objects would be: Project, Measurement, SampleModel, ExperimentModel, Analysis and Summary.

New Proposed Implementation

The Measurement object will contain the measured data in the form of a Scipp Data Group, together with a list of RegionOfInterests (ROI) objects.
The Measurement Object is responsible for converting calls to Scipp syntax in order to interface with the Scipp Data Group and to interface with various data loaders and view and inspect the data.

Creating the Measurement object

The Measurement object should be possible to create in 3 different ways, directly in a notebook requiring no file-loading, from a SciTiff (the reduced data-format of choice) and from a folder of tiff files.

Directly from a Scipp Data Group
To make smoother notebooks combining essimaging for the reduction and EasyImaging for the analysis. The syntax would simply be:

measurement = Measurement(data = Scipp.DataGroup, name = 'best_measurement')

With adequate checks of the given Data Group.

From a SciTiff
For loading a reduced file directly into a Measurement, a classmethod will be used to load SciTiffs using the SciTiff packages loader:

mesurement = Measurement.from_scitiff(file_path = './best_folder/best_data.tiff')

Which will call `scitiff.load_scitiff(file_path') to set the Scipp Data Group of the normal constructor.

From a folder of tiffs
For loading data which was not saved as a scitiff, such as data from other facilities, 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

[henrikjacobsenfys]

This looks nice and well-thought-out.
I do wonder if it would be useful to be able to index the regions of interest by something else than their names - if you have a 2000x2000 grid, names can get quite clunky. This may also be needed when you're fitting regions of interest sequentially, since you may want to use the parameters of the previous fit as the start guess of the next one (although this method is dangerous - if one fit diverges, all subsequent fits diverge too).

[damskii9992]

Oh, they will be indexable too, it is saved as a list rather than a dictionary, after all :)
I need them to be indexable for the GUI logic to make sense, although I would've preferred them being a dictionary. The thing is, the list will never have more than a few members, like 1-3 most commonly, and they usually represent different elements in the image, like different materials, or corner versus core, i.e. they're categorical and thus make more sense to differentiate by name.
I would've liked a combined list and dictionary :(

[AndrewSazonov]

Have you considered how the calculated data should be stored and linked to the Measurement object?

[damskii9992]

The calculated data? You mean the one from the model?
I would not store the calculated data, but simply calculate it on the fly from the model when needed.
But that has nothing to do with the Measurement object, as the Measurement object is only for storing measured data.

[AndrewSazonov]

Right, I meant the data calculated from the model. I think you refer to it as the theoretical spectrum. In the diffraction project, we handle this with a Datastore object that keeps both measured and calculated data.

In the simplest case, this means storing the x-values (e.g. 2Theta positions), the measured intensities at each x, and the corresponding calculated intensities. That's what I had in mind by "linking": for every x position, you can retrieve both the measured and the associated calculated intensity.

Whenever a model parameter (sample or instrument/experiment) changes, the calculated pattern is recalculated and stored again. This way, when you want to plot measured vs. calculated patterns, either after a manual change or at the end of a fit, you don’t need to recalculate on the fly.

In your approach, the theoretical spectrum would be recalculated every time it's requested. So even if the model hasn't changed, and you just want to display multiple plots focusing on different ranges, you'd end up triggering multiple recalculations, right?

[damskii9992]

Yes, that is indeed true, I do not yet know how expensive these recalculations are, but I'm afraid that storing them might be heavier than recalculating them in the case of imaging. Especially when the user wants to fit the model to every single pixel of an image . . .
But for arguments sake, lets say I find it to be too expensive and I need to store the calculated data like you do.

I think I'd then store the calculated data on the SampleModel, and update it there when changing parameters. Or maybe actually on the Analysis object, since the Analysis object knows the x-values from its associated Measurement objects.

I prefer having these things properly separated depending on responsibility, rather than having a Datastore object to handle it.

[AndrewSazonov]

Storing the calculated data on the SampleModel wouldn't work for diffraction, at least - in cases where multiple SampleModels contribute to the measured data (which is not uncommon), the calculated diffraction pattern is the superposition of all their contributions. The total pattern therefore can't really "belong" to just one SampleModel.

Storing it on the Analysis makes more sense in that case. In Imaging, do you see the Analysis object as being responsible for linking the SampleModel(s), ExperimentModel(s), and Measurement, right? We've touched this before, but just to refresh: in diffraction, each Experiment object has a list of SampleModels contributing to the total calculated profile associated with this experiment, so the Datastore is part of the Experiment object and holds both the measured and calculated data.

[AndrewSazonov]

This is a library-related discussion, but since you mentioned the GUI, my question is about the GUI pages. By suggesting the primary objects - Project, Measurement, SampleModel, ExperimentModel, Analysis, and Summary - for the library, are you also envisioning the same set of pages for the GUI? And if so, would they appear in the same order as the objects you listed?

[damskii9992]

Yes indeed. And I would probably rename Summary as well, or add another page/object there for post-processing/visualization. But I have not yet decided fully on that. I know that @henrikjacobsenfys needs something similar in EasySpectroscopy.

[AndrewSazonov]

Do you suggest preserving that overall order? So, after creating a project, the workflow would be: load the measured data, then define the sample model, then the experiment model, and finally proceed to the fitting?

[henrikjacobsenfys]

Yes, I need a second Analysis page to analyse fit parameters. I'm unsure what to call it, but I'll cross that bridge when I get to it. I'm unsure if it will replace the Summary page, or if I'll have one of those too.