MRG: Change Beer Lambert law default ppf value to 6

[rob-luke]

Reference issue

The fNIRS processing uses the modified Beer Lambert law (BLL) to convert optical density data to changes in haemoglobin concentration. This process uses a scaling factor called the partial path length factor.

The largest fNIRS group that wrote the Homer software uses a ppf=6 value. Whereas we use a default value of 0.1. @larsoner already ran in to this issue before, and for his code needed to change the MNE function to use ppf=6 (#8711 (comment))

When I wrote the BLL code I had been using the default ppf value from the Huppert AnalyzIR toolbox (Santosa... Huppert 2018) of 0.1. Their approach was to use a partial volume correction (PVC=60) when determining the ppf. So their ppf = [dpf=6]/[pvc=60] = 0.1

I had assumed when writing our code that the 2018 paper was a better benchmark than the Homer 2009 paper (also by Huppert). However, I just had a phone call with Yucel (author of the fNIRS best practices paper), and they still recommend ppf=6. For many reasons, but one that stood out for me is that the pvc value is not well known and varies across the head and task.

What does this implement/fix?

To be in line with best practices and with the most prominent fNIRS software and match community expectations from existing literature I change our default ppf=0.1 to ppf=6

Additional information

Neither approach is right or wrong. But using ppf=6 is more inline with the community expectations and makes our results easier compared to the majority of the existing literature.

I've been going back and forth in my head about this for a while, but I think we should make the jump before the 0.24 release.

The tests already had a hard coded ppf value (didnt use the default), so they didnt require changing.

[rob-luke]

FYI: @HanBnrd (also looking forward to your talk next week!) @rderollepot @kylemath

@larsoner @agramfort ready for review, unless someone above disagrees

[rob-luke]

Cancel that merge request, I will check the tutorials before requesting a merge. The scaling of results might now be different and I may need to change the tutorial text and ylims

[larsoner]

+1 for this change, but unfortunately we need to do it via deprecation :(

This means in the signature you have ppf=None, and in the description of the kwarg you say the default in 0.24 is 0.1 but will change to 6 in 0.25, and in the code you do:

if ppf is None:
    ppf = 0.1
    warn('The default value ppf=0.1 in 0.24 will change to ppf=6 in 0.25, set it ...', DeprecationWarning)

and then to save us some pain, add an ignore line to conf.py to ignore this deprecation warning so that we don't have to explicitly ignore it in our tests to avoid them failing.

[rob-luke]

but unfortunately we need to do it via deprecation

Ah yes, of course. No worries, I will implement as you describe.

Thanks for explaining how to do it in detail, that saved me a good 20 mins!

[rderollepot]

FYI: @HanBnrd (also looking forward to your talk next week!) @rderollepot @kylemath

@larsoner @agramfort ready for review, unless someone above disagrees

Thank you Robert for your investigation on this point and for the clear sum up above !

[rob-luke]

@larsoner do we put in latest.inc items for future changes? Or should I just remove this from latest?

[larsoner]

Deprecations go in the API section

[rob-luke]

@larsoner and @agramfort could you please review. The failing tests in one CI seem unrelated. Thanks

[larsoner]

Thanks @rob-luke !

[larsoner]

Whoops, depreciation should be deprecation -- will fix in main

[rob-luke]

Thanks @agramfort and @larsoner for completing this PR