ENH: Add Rescale interface

[effigies]

Upstreaming another interface from fMRIPrep. This one is based off of fmriprep.interfaces.images.InvertT1w. It rescales a skull-stripped image to match the rough statistics of another, which is not restricted to the case in which we applied it, so I renamed it.

Differences from InvertT1w:

• Contrast inversion is optional (invert input)
• Identifying maxima/minima is replaced with quantile-based statistics, allowing for rescaling that is less sensitive to outliers
• Pure nibabel instead of nilearn, as the only nilearn feature used was new_img_like

The original behavior is recoverable simply with Rescale(invert=True, percentile=0.).

[codecov-io]

Codecov Report

Merging #2599 into master will decrease coverage by 0.02%.
The diff coverage is 40.74%.

@@            Coverage Diff             @@
##           master    #2599      +/-   ##
==========================================
- Coverage   67.62%   67.59%   -0.03%     
==========================================
  Files         339      339              
  Lines       42787    42814      +27     
  Branches     5288     5288              
==========================================
+ Hits        28934    28941       +7     
- Misses      13171    13191      +20     
  Partials      682      682

Flag	Coverage Δ
#smoketests	50.76% <ø> (ø)	⬆️
#unittests	65.08% <40.74%> (ø)	⬆️

Impacted Files	Coverage Δ
nipype/interfaces/image.py	73.07% <40.74%> (-17.12%)	⬇️
nipype/pipeline/plugins/multiproc.py	79.76% <0%> (-2.39%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 205ea17...27ebb6d. Read the comment docs.

[oesteban]

single comma at the end of the line

[oesteban]

it is very unlikely the same percentile works well for both ends of the range. I would split this option or make it a tuple.

[effigies]

Hmm. I expected that people would probably only ever want 0 or 1 (but left room for tweaking), but I can add more flexibility than this. This leads me to wonder if we want to permit different percentiles for the input and reference images. In which case we need 4 values, not 2.

WDYT? If possible, it'd be nice to allow a single knob, to keep it simple until somebody needs more refined control.

[oesteban]

WDYT?:

    percentile = traits.Either(
        traits.Range(low=0., high=50, value=0),  # One-knob behavior
        traits.Tuple(
            traits.Either(None, traits.Range(low=0., high=50, value=0)),
            traits.Either(None, traits.Range(low=50., high=100, value=100)),
        ), desc='...')

Then, if it is not a tuple, it has your one-knob mirror behavior. Otherwise you have a tuple, and you can always set one of the boundaries.

[oesteban]

My fixation for this is that T1 images typically show background pixels under the 15% and, except when there are WM hyperintensities, you probably want 98% or higher for the upper limit.

[effigies]

So, if I'm reading this correct, we don't need to be concerned with supporting different percentiles for the input and the reference?

My fixation for this is that T1 images typically show background pixels under the 15% and, except when there are WM hyperintensities, you probably want 98% or higher for the upper limit.

This is true for skull-stripped images?

[oesteban]

Nope, but I think we should aim for this interface to work well in any situation.

[oesteban]

So, if I'm reading this correct, we don't need to be concerned with supporting different percentiles for the input and the reference?

Okay, gotcha. I'm always thinking of the input. I guess we should specify that this interface expects the reference file to be "consistent" (as in already thresholded).

[effigies]

I think we should aim for this interface to work well in any situation.

I don't think this interface will work at all well in non-skull-stripped cases. Calculating the magic numbers needed won't be significantly easier or more robust than even mediocre skull stripping, if I were to make a guess.

I guess we should specify that this interface expects the reference file to be "consistent" (as in already thresholded).

I do say:

in_file = File(exists=True, mandatory=True,
               desc='Skull-stripped image to rescale')
ref_file = File(exists=True, mandatory=True,
                desc='Skull-stripped reference image')

And:

Rescales the non-zero portion of ``in_file`` to match the bounds of the
non-zero portion of ``ref_file``.

But I can very explicitly say in the docstring that they should be skull-stripped. And would you suggest not applying the supplied percentiles to the reference image, as well?

I guess what's your vision for what this interface should do when percentiles != (0, 100)?

[effigies]

@oesteban No rush, but just letting you know that I'm waiting for our discussion to resolve before making further changes.

[oesteban]

Sorry. We should go ahead with this, I am probably talking of a nonexistent problem. If my suggestion is an actual issue, it'll be straightforward to identify and fix.