Splitting to handle multiple frames per plane

[nataliaorlova]

While piloting high resolution stacks and also axonal imaging, we discovered the need to acquire multiple frames per plane in all data modalities for experiments on MesoScopes (surface_average, depth_average, timeseries, local and cortical stacks).

We acquired first session (SID 1178748400) with frames per plane number != 1, and it caused splitting module to fail - see this lims job data log

The code failed on splitting surface_average, but we anticipate it to fail on other modes where we change frames per plane as well. For surface, the splitting code expects N pairs of FastZ actuator values for N ROIs in a session, i.e. if the session has 2 ROIs and their surfaces are at -160 and -155, it expects the fast Z actuators to be [[-160, 0], [-155,0]], while when averaging is set to M, the value array with have M repeats of each pair, i.e. for M=4, the fastz values array will be [[-160, 0], [-160, 0], [-160, 0], [-160, 0], [-155, 0], [-155, 0], [-155, 0], [-155, 0]]

To optimize data quality in both phase 4 projects and OpenScope, we have to change this parameter (number of frames per plane) and we would like to request the splitting code to be able to handle this situation.

We acquired the sample test data, it's located here : /allen/programs/braintv/workgroups/multiphoton/Natalia/05242022_sample_data_splitting_for_Scott

Test data consists of the following:

For each data modality (surface, depth, local stack and cortical stack - we skipped timeseries because of it's size, and since depth_average represents a sub-sample of timeseries data):

• 1 frame (no change comparing to pipeline data)
• 4 frames
• 4 frames with averaged on the rig

Additionally, for cortical z stack, we acquired a stack in a slightly different mode (so called slow stack in ScanImage):

• 10 frames
• 10 frames averaging on the rig
  This is because cortical stacks are larger (more planes) and ScanImage has a limitation on number of repeats for large stacks and doesn't allow us to stick the same "fast Stack" mode.

Related to issue 495, whenever the stack comes off the rig unaveraged, we'd like the splitting code to average all planes at the same depth for both local and cortical stacks.

[danielsf]

Our hypothesis is that ScanImage records some fields in the metadata which will help us disambiguate how may frames per plane are being taken. One promising option is

metadata[0]['SI.hStackManager.framesPerSlice']

which is 4 for 'local_stack_4_frames_00001.tif' and 1 for 'local_stack_1_frame_00001.tif'.

Note to self: we should also be looking at

metadata[0]['SI.hChannels.channelSave']

which appears to be 1 for the surface images (only saving the first channel) and [1, 2] for stack-like images (saving both channels...?). I suspect that the "channels" in question are the two entries in each row of SI.hStackManager.zsAllActuators.

[nataliaorlova]

First part of last paragraph makes perfect sense (metadata[0]['SI.hStackManager.framesPerSlice'] defines how many planes where acquired per plane).

However, whatever the structure of SI.hStackManager.zsAllActuators, when metadata[0]['SI.hChannels.channelSave'] has 1, only data scanned at FastZ1 (channel 1) is saved to disk, while when it has [1, 2], data form both FastZ positions (both channels) is saved.

I'll try to start a document with definitions which ScanImage parameters are set and to what for each data modalities, and I think we should add a column there for metadata field where this is recorded.

[danielsf]

@nataliaorlova Your explanation of SI.hChannels.channelSave comports with my understanding. Thanks.

[nataliaorlova]

Types of outputs:

1. 1 frame (no change comparing to pipeline data) : data should be split into different depth/channels; additionally, for everything but time series data should be averaged based on <SI.hStackManger.numVolumes>

2. N frames : output data should be split into depth.channels and averaged based on number of frames per plane <SI.hStackManager.framesPerSlice> AND for everything but time series, also averaged base don number of repeats <SI.hStackManager.numVolumes>

3. N frames averaged on the rig : similar to case 1 above with 1 frame per slice/plane