ADR Suggestion The Experiment 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.