fix(roisignals): correct neuropil masks and the options output of extractF

[ehennestad]

Two defects in roi signal extraction. I found them by comparing nansen.twophoton.roisignals.extractF with mean pixel values computed by hand on a synthetic stack. The roi signals were exact. The neuropil signals and the returned options were not.

nansen.processing.roi.estimateNeuropilMasks grows a neuropil mask around each roi and ignores the pixels in pixelsToIgnore while it does so. With an image mask it computed pixelsToIgnore = footprintAllRois & ~params.imageMask, which is only true for roi pixels that lie outside the image mask. extractF and nansen.processing.SignalExtractor replace an empty imageMask with true(imageSize), so pixelsToIgnore was false everywhere. The default excludeRoiFromNeuropil = true therefore had no effect: a neuropil mask left out the pixels of its own roi, but held the pixels of every other roi within its reach. On a synthetic stack with a bright roi 3 pixels away from another roi, the mean neuropil signal of that other roi was 3466 instead of 2047. A user-defined imageMask had almost no effect for the same reason. The two conditions are now combined with |.

This changes extracted values. RoiSignals_NeuropilF from the Extract Signals session methods, and neuropil signals saved from the roimanager, include pixels of neighboring rois if they were extracted before this change. dffClassic does not use the neuropil signal and is not affected. dffChenEtAl2013 and dffRoiMinusDffNpil are affected: the activity of a neighboring roi was subtracted from the roi signal as if it were neuropil.

extractF returned P as its second output. P is the struct of default values that the options are parsed against. The parsed options, with roiInd, imageMask, extractFcn and roiMaskFormat resolved, are in params. The Extract Signals session method saves the second output as OptionsSignalExtraction, which therefore always recorded the default values. The second output is now params.

Both functions now declare their options in an arguments block instead of parsing varargin with utility.parsenvpairs. estimateNeuropilMasks takes its five options as name-value arguments, resolves roiInd = "all" itself and throws NANSEN:RoiSignals:ImageMaskSizeMismatch for an image mask of the wrong size. createMasks passes the options by name. extractF takes an optional options struct followed by name-value arguments, because most callers pass a struct, often the one from getDefaultParameters, which also holds the fields that configure the options editor. Options in the struct are passed on as name-value arguments, so they are validated in the same way. Fields that are not options are ignored, and an option given by name still replaces the field of the same name. No option has a default value in the block, because a default could not be told apart from a value given by name and would replace the value in the struct. Default values are added afterwards from getDefaultParameters, which stays the only place where they are defined.

Two things behave differently for callers of extractF. A misspelled option name throws an error instead of being ignored. The struct has to come before the name-value arguments: the extractSignals session method passed it last and is updated, and all other callers in the repository already pass it first. Name=Value syntax now works. utility.parsenvpairs only recognizes option names that are character vectors, so names given as strings were ignored before.

The help text of both functions is rewritten. It documents the size and layout of signalArray, every option with its default value, the second output, the behavior for stacks with more than one current channel, and how a neuropil mask is grown.

nansen.unittest.roisignals.EstimateNeuropilMasksTest and nansen.unittest.roisignals.ExtractFTest are new. They compare the signals with the mean pixel values of hand-made masks and cover the mask options, the calling conventions of extractF and its second output. In testNeuropilSignalLeavesOutNeighboringRois the rois are brighter than the background, so the neuropil signal only equals the background if no neuropil mask holds a pixel of any roi.

The two fixes are the first two commits and change one line each, so they can be picked without the arguments blocks.

Not part of this PR:

• NansenModules/NANSEN-TwoPhoton holds its own copies of estimateNeuropilMasks and extractF with the same two defects. The draft stack WP0: two-photon migration hygiene (no moves) #129 to WP8: remove the two-photon module from NANSEN and require it from its own repository #137 removes the copies in this repository, so the fixes have to be ported to the module, and the new tests have to move to the twophotontest package when WP2: move the ROI-signals cluster into the two-photon module #132 is rebased.
• With a scalar roiInd, createMasks only builds masks for the rois that RoI.getNeighboringRoiIndices returns, which are the rois whose center lies within two radii. A roi slightly further away can still lie where the neuropil mask grows, so the neuropil signal of a single-roi extraction can differ from the full extraction. This was hidden while no roi pixels were left out at all.
• utility.parsenvpairs ignores option names given as strings, so computeDff(F, dffFcn="dffChenEtAl2013") returns the dffClassic result without a warning. computeDff also returns ΔF/F of the first roi only when it is given a samples-by-rois matrix.

🤖 Generated with Claude Code

[github-actions]

Test Results

393 tests  +24   393 ✅ +24   40s ⏱️ +13s
 27 suites + 2     0 💤 ± 0 
  1 files   ± 0     0 ❌ ± 0 

Results for commit e93f050. ± Comparison against base commit d8ee8c3.