HemoCompute

Calculates HbO and HbR from reflectance signals.

Description

This function uses reflectance (intrinsic) signals to estimate changes in oxygenated (HbO) and deoxygenated (HbR) hemoglobin. The illumination spectra and camera responses come only from the folder rig ledger (UMITRigLedger.json in the SaveFolder), never from the rig library or the Active rig. The filter transmission comes from the filter set named by FilterSet.

Rig requirements

The SaveFolder must be bound to a rig. HemoCompute stops with an error, before anything is written, when the folder:

has no rig ledger (Umitoolbox:RigLedger:noLedger), for example a folder imported by an earlier release;
is recorded as "no rig" (Umitoolbox:RigLedger:noRigBound), for example a single-camera import that was never bound;
is in a rig conflict (Umitoolbox:RigLedger:conflicted);
has an invalid rig ledger (Umitoolbox:RigLedger:invalidLedger); see Invalid rig ledger for the ways out, including Repair Rig Ledger.

The error message says why the folder was refused and how to fix it: bind a rig with DataViewer's Management > Rig > Folder Rig menu, resolve the conflict there, or start again from a fresh save folder. A pipeline runs the same checks before it starts (preflight): a folder that fails them is skipped and logged, and the other folders are processed.

After a successful computation, HemoCompute commits the optics and the filter set it used to the folder's rig ledger (the first time only). From then on the folder keeps using those optics: rebinding it to a rig whose optics differ creates a rig conflict, and a filter set whose content differs from the committed one under the same name makes HemoCompute refuse the folder (Umitoolbox:RigLedger:filterSetModified; use a filter set with a new name instead). The Rig Manager does not let you change the profiles of a filter set in place (it offers to save a new filter set), so this happens with a library file edited by hand or a different library on another computer. Editing or archiving the library rig afterwards has no effect on the folder.

When the rig library of this computer no longer has the filter set (for example on another computer), HemoCompute uses the copy committed in the folder's rig ledger and shows the warning Umitoolbox:HemoCompute:FilterSetFromLedger. To use the library again, import the filter set with the same name and content into the rig library.

Input

Call the function as HemoCompute(SaveFolder, data, ...).

SaveFolder contains AcqInfos.mat and the imported reflectance channels.
data is the name of one of the illumination channel .dat files in the SaveFolder (for example red.dat), as wired into the pipeline step. It must be one of the channel files resolved from AcqInfos.mat and the folder's rig optics (see below), otherwise the function returns an error. Numeric arrays, other file types and other dimension layouts are not supported.
Why this input exists: it is a pipeline dependency, not the data that is processed. The function reads all the selected channel files from the SaveFolder, whichever one is passed, so the values of data are validated but never used. The input is kept because the pipeline schedules a step from its data inputs: a step without one would be treated as a source and run in the first phase, before setup steps such as the registration of the folder, and without waiting for the step that produces the channels. Wiring one channel file into data makes the step run after its producer, in the main schedule.

HemoCompute reads all the channels selected by Illuminations from the SaveFolder, not only the file passed in data. Supported canonical names are red, green, and yellow; the historical name amber is normalized to yellow. Imported channel filenames and timebases are resolved from AcqInfos.mat. Every resolved channel file must be an image time series with dimensions Y,X,T. Four-dimensional event-split input is not supported.

Output

The function writes the Y,X,T files HbO.dat and HbR.dat in the SaveFolder. With one requested output, the function returns the manifest {'HbO.dat','HbR.dat'}. With two requested outputs, it returns those two filenames individually; it does not return numeric arrays.

Samples whose intensity (after normalization) is not positive and finite, for example masked pixels stored as 0, have no optical density: HbO and HbR are NaN at those samples, and the function shows the warning Umitoolbox:HemoCompute:NonPositiveIntensity with the number of such samples. NaN samples stay NaN. (Earlier releases gave finite or infinite values there.)

files = HemoCompute(saveFolder, data);
[hbOFile, hbRFile] = HemoCompute(saveFolder, data);
hbO = loadData(fullfile(saveFolder, hbOFile));

Parameters

Set of excitation and emission filters used in recordings. The filter set is read from the rig library of this computer (or, if the library no longer has it, from the copy committed in the folder's rig ledger, see Description):

GCaMP: Filter set from recordings using GCaMP as a fluorophore
jRGECO: Filter set from recordings using jRGECO as a fluorophore
none: No filter set

Set this parameter to true to normalize the data prior to the calculation of the HbR and HbO: each channel is smoothed with a 1 Hz low-pass filter and divided by its 1/120 Hz baseline. Set to false to skip the normalization if the input data is already normalized.

At frame rates of 2 Hz or less, 1 Hz is not below the Nyquist frequency, so the 1 Hz smoothing is skipped with the warning Umitoolbox:HemoCompute:NormalizationSmoothingSkipped, and each channel is only divided by its 1/120 Hz baseline. (Earlier releases failed on such recordings.)

If the data from the input files are already normalized (i.e. with an average around 0 or 1) and this parameter is set to true, the normalization will be skipped. However, if it is set to false and the input data is not normalized, the computation will be aborted. The normalized data is necessary for the execution of this algorithm.

Select two or three different channels from red, green, and yellow. The selected channels must exist in the SaveFolder and be represented by the acquisition and by the optics of the folder's rig.

Sets the assumed total hemoglobin concentration in micromolar.

Sets the assumed tissue oxygen saturation as a percentage.