ENH dwidenoise: Write out variance explained map

[tsalo]

Is your feature request related to a problem? Please describe.
It would be awesome if dwidenoise could write out a variance explained map. This stems from nipreps/fmriprep#3395 (comment).

Describe the solution you'd like
Maybe this could be a new parameter, like -varex <filename>.

Describe alternatives you've considered
Users can probably calculate variance explained pretty easily (at least for fMRI), but this would make it easier for them.

[Lestropie]

Added to #3023.

What might a use case look like? Would it be most convenient for an output image to contain the fraction of variance that was removed, or the fraction that was retained?

I'm hoping that in the case of optimal shrinkage, an inner product between weights and eigenvalues is all that is required.

[tsalo]

I think the fraction of variance removed would be more useful than the fraction retained. In QSIPrep and fMRIPrep, I would probably mainly use it for a figure in the HTML report, where seeing the removed variance could be clearer than the retained variance.

[Lestropie]

Need to determine how to calculate this information in the presence of other complexities:

1. Preconditioning:

   1. Phase demodulation
   2. Demeaning
   3. Non-stationarity correction

   These all happen upstream to the data provided to the PCA. So even if the eigenvalue spectrum of a given PCA is separated into MP distribution and "signal" components, there may be a substantial amount of information content in the input image for which the corresponding power is omitted from the "signal" components classified by the PCA & noise level estimation.

2. Optimal shrinkage:

   If utilised (as is the default), should "variance explained" (at least within what is visible to the PCA) be based on the sum of eigenvector weights, instead of the eigenvalues that are below vs. above the local noise level threshold?

[Lestropie]

Closed by 8bb54c7.