ENH: add spline interpolation motion correction for fNIRS (motion_correct_spline)

[leonardozaggia]

Reference issue (if any)

Nonne (new feature)

What does this implement/fix?

Adds motion_correct_spline (alias spline) to mne.preprocessing.nirs for spline interpolation-based motion correction of fNIRS data.

For each detected motion-artifact segment the signal is detrended with a smoothing spline, then consecutive segments are baseline-shifted so they connect smoothly. Accepts a per-channel artifact mask tIncCh; when None, only spline detrending is applied with no baseline shifting.

Based on Homer3 v1.80.2 hmrR_tInc_baselineshift_Ch_Nirs (Huppert et al. 2009).

Additional information

• Operates on optical density or hemoglobin data.
• p controls spline smoothness (smaller = tighter fit to data).
• tIncCh is shape (n_picks, n_times); True = clean, False = artifact.
• This is one of three related PRs adding Homer3-based motion correction to mne.preprocessing.nirs
  - PCA: ENH: add PCA-based motion correction for fNIRS (motion_correct_pca) #13691
  - Spline: this PR
  - Wavelet: ENH: add wavelet-based motion correction for fNIRS (motion_correct_wavelet) #13692

[larsoner]

@leonardozaggia I wonder if these should live in https://github.com/mne-tools/mne-nirs/tree/main/mne_nirs/preprocessing instead... we can iterate and release faster over in mne-nirs than we can here, and at some point I think decided we should try to put newer functionality there when possible. WDYT?

[leonardozaggia]

@arsoner thanks for your feedback.
I considered this point when first working on this PR. At the end I opted for mne-python because the only other motion regression technique available - TDDR - lives here and thought it best for users to have the motion correction techniques in the same place.

[leonardozaggia]

But of course, I am open to cancel my PR and submit a new one to the dedicated mne-nirs repo if you think it's best :)

[larsoner]

@scott-huberty @drammock any thoughts on where this should live? I'm inclined to add any new fNIRS algorithms to mne-nirs...

[drammock]

@scott-huberty @drammock any thoughts on where this should live? I'm inclined to add any new fNIRS algorithms to mne-nirs...

yeah, I think so too, unless the method is also valuable for other modalities

[scott-huberty]

I'm inclined to add any new fNIRS algorithms to mne-nirs...

I agree that it makes most sense for newly added fNIRS specific utilities to live in mne-nirs!

[leonardozaggia]

Great then, I will move the work to mne-nirs. I suppose these methods could also be implemented for different modalities with sufficient parameter tuning. But I think the most beneficial contribution would be to add them for the mne-based fnirs community to use out of the box.

Just a quick question, do you think it would make sense to port the already existing nirs specific modules here in mne-nirs?

[scott-huberty]

Just a quick question, do you think it would make sense to port the already existing nirs specific modules here in mne-nirs?

Yeah I think that it would be a super nice idea to have all the functionality in one place!

I'll let @larsoner provide a more definitive answer, but I guess we could follow the mne.connectivity -> mne-connectivity example (xref #9493 ) and do a 2 minor version deprecation cycle for the mne.preprocessing.nirs sub package?

Or we can keep mne.preprocessing.nirs and just create wrappers in mne-nirs for the functions we want to port? That way users who want to do everything in one place can, but we don't break people's old scripts that use the mne.preprocessing.nirs namespace.

[drammock]

do you think it would make sense to port the already existing nirs specific modules here in mne-nirs?

yes but not yet. We have plans in the works for creating a proper plug-in architecture for MNE. When MNE-NIRS becomes a plugin would be the right time to migrate the functionality.