ENH: Add --rescale-intensities and name_source to N4BiasFieldCorrection

[oesteban]

Summary

Fixes # .

List of changes proposed in this PR (pull-request)

Acknowledgment

• (Mandatory) I acknowledge that this contribution will be available under the Apache 2 license.

[effigies]

I wonder if it makes sense to deprecate save_bias, and just always output the bias image, using name_template (unless someone specifically undefines it). Presumably it's already calculated, and so the cost is minimal, and it would save the contortions of _out_bias_file.

Failing that, I would probably make _out_bias_file a property that reconstructs the file as called for or a hidden attribute that's None by default. Either of which will avoid the explicit getattr, setattr, delattr calls, which would make it more readable, IMO.

[codecov]

Codecov Report

Merging #3011 into master will decrease coverage by 3.33%.
The diff coverage is 65%.

@@            Coverage Diff             @@
##           master    #3011      +/-   ##
==========================================
- Coverage    67.5%   64.16%   -3.34%     
==========================================
  Files         344      342       -2     
  Lines       44039    43976      -63     
  Branches     5554     5548       -6     
==========================================
- Hits        29727    28218    -1509     
- Misses      13560    14641    +1081     
- Partials      752     1117     +365

Flag	Coverage Δ
#smoketests	?
#unittests	64.16% <65%> (-0.79%)	⬇️

Impacted Files	Coverage Δ
nipype/interfaces/ants/segmentation.py	74.21% <65%> (+0.48%)	⬆️
nipype/interfaces/nilearn.py	40% <0%> (-56.67%)	⬇️
nipype/utils/spm_docs.py	25.92% <0%> (-44.45%)	⬇️
nipype/interfaces/freesurfer/base.py	50% <0%> (-30.51%)	⬇️
nipype/utils/logger.py	59.7% <0%> (-29.86%)	⬇️
nipype/algorithms/rapidart.py	35% <0%> (-29.42%)	⬇️
nipype/interfaces/spm/base.py	57.94% <0%> (-29.14%)	⬇️
nipype/utils/provenance.py	55.73% <0%> (-28.35%)	⬇️
nipype/interfaces/fsl/model.py	55.26% <0%> (-25.35%)	⬇️
nipype/testing/fixtures.py	77.33% <0%> (-21.34%)	⬇️
... and 43 more

---

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 23300e9...355965d. Read the comment docs.

[codecov]

Codecov Report

Merging #3011 into master will decrease coverage by 3.32%.
The diff coverage is 56.52%.

@@            Coverage Diff             @@
##           master    #3011      +/-   ##
==========================================
- Coverage    67.5%   64.17%   -3.33%     
==========================================
  Files         344      342       -2     
  Lines       44039    43973      -66     
  Branches     5554     5548       -6     
==========================================
- Hits        29727    28219    -1508     
- Misses      13560    14628    +1068     
- Partials      752     1126     +374

Flag	Coverage Δ
#smoketests	?
#unittests	64.17% <56.52%> (-0.78%)	⬇️

Impacted Files	Coverage Δ
nipype/interfaces/ants/segmentation.py	74.44% <56.52%> (+0.71%)	⬆️
nipype/interfaces/nilearn.py	40% <0%> (-56.67%)	⬇️
nipype/utils/spm_docs.py	25.92% <0%> (-44.45%)	⬇️
nipype/interfaces/freesurfer/base.py	50% <0%> (-30.51%)	⬇️
nipype/utils/logger.py	59.7% <0%> (-29.86%)	⬇️
nipype/algorithms/rapidart.py	35% <0%> (-29.42%)	⬇️
nipype/interfaces/spm/base.py	57.94% <0%> (-29.14%)	⬇️
nipype/utils/provenance.py	55.73% <0%> (-28.35%)	⬇️
nipype/interfaces/fsl/model.py	55.26% <0%> (-25.35%)	⬇️
nipype/testing/fixtures.py	77.33% <0%> (-21.34%)	⬇️
... and 40 more

---

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 23300e9...f37b65e. Read the comment docs.

[oesteban]

I wonder if it makes sense to deprecate save_bias, and just always output the bias image, using name_template (unless someone specifically undefines it). Presumably it's already calculated, and so the cost is minimal, and it would save the contortions of _out_bias_file.

As much as I like this idea, I think the name_source mechanism does not fully cover this behavior. In cases like this, it would be fine just generating the file anyways. For the general case, it would be best to allow some kind of metadata (name_enable) pointing to some other traits.Bool (in this case save_bias) that is used to check whether the name substitution should be executed.

Failing that, I would probably make _out_bias_file a property that reconstructs the file as called for or a hidden attribute that's None by default. Either of which will avoid the explicit getattr, setattr, delattr calls, which would make it more readable, IMO.

Agreed, done.

[effigies]

Have you tested? I'm not positive that you'll get an absolute path as the output.

[oesteban]

Have you tested? I'm not positive that you'll get an absolute path as the output.

0b695ae ensures the absolute path of the bias output and I have tested locally.

[oesteban]

I just realized that this overlaps with #2996 on the --rescale-intensities parameter.

[rciric]

I closed mine for now -- I'll open a new one with just the other N4 parameters so that it doesn't conflict.