[ENH] Convenient load/save of interface inputs

CHANGES

@@ -1,6 +1,7 @@
 Upcoming release 0.13
 =====================
 
+* ENH: Convenient load/save of interface inputs (https://github.com/nipy/nipype/pull/1591)
 * ENH: Add a Framewise Displacement calculation interface (https://github.com/nipy/nipype/pull/1604)
 * FIX: Use builtins open and unicode literals for py3 compatibility (https://github.com/nipy/nipype/pull/1572)
 * TST: reduce the size of docker images & use tags for images (https://github.com/nipy/nipype/pull/1564)

doc/users/interface_tutorial.rst

@@ -4,27 +4,27 @@
  Tutorial : Interfaces
 =======================
 
-Specifying options
-------------------
+Specifying input settings
+-------------------------
 
 The nipype interface modules provide a Python interface to external
 packages like FSL_ and SPM_.  Within the module are a series of Python
 classes which wrap specific package functionality.  For example, in
 the fsl module, the class :class:`nipype.interfaces.fsl.Bet` wraps the
 ``bet`` command-line tool.  Using the command-line tool, one would
-specify options using flags like ``-o``, ``-m``, ``-f <f>``, etc...
+specify input settings using flags like ``-o``, ``-m``, ``-f <f>``, etc...
 However, in nipype, options are assigned to Python attributes and can
 be specified in the following ways:
 
-Options can be assigned when you first create an interface object:
+Settings can be assigned when you first create an interface object:
 
 .. testcode::
 
    import nipype.interfaces.fsl as fsl
    mybet = fsl.BET(in_file='foo.nii', out_file='bar.nii')
    result = mybet.run()
 
-Options can be assigned through the ``inputs`` attribute:
+Settings can be assigned through the ``inputs`` attribute:
 
 .. testcode::
 
@@ -34,14 +34,53 @@ Options can be assigned through the ``inputs`` attribute:
    mybet.inputs.out_file = 'bar.nii'
    result = mybet.run()
 
-Options can be assigned when calling the ``run`` method:
+Settings can be assigned when calling the ``run`` method:
 
 .. testcode::
 
    import nipype.interfaces.fsl as fsl
    mybet = fsl.BET()
    result = mybet.run(in_file='foo.nii', out_file='bar.nii', frac=0.5)
 
+Settings can be saved to a json file:
+
+.. testcode::
+
+   import nipype.interfaces.fsl as fsl
+   mybet = fsl.BET(in_file='foo.nii', out_file='bar.nii', frac=0.5)
+   mybet.save_inputs_to_json('bet-settings.json')
+
+Once saved, the three inputs set for ``mybet`` will be stored in a JSON
+file. These settings can also be loaded from a json file:
+
+.. testcode::
+
+   import nipype.interfaces.fsl as fsl
+   mybet = fsl.BET()
+   mybet.load_inputs_from_json('bet-settings.json', overwrite=False)
+
+
+Loading settings will overwrite previously set inputs by default, unless
+the ``overwrite`` argument is ``False``. Conveniently, the settings can be
+also read during the interface instantiation:
+
+.. testcode::
+
+   import nipype.interfaces.fsl as fsl
+   mybet = fsl.BET(from_file='bet-settings.json')
+
+If the user provides settings during interface creation, they will take
+precedence over those loaded using ``from_file``:
+
+.. testcode::
+
+   import nipype.interfaces.fsl as fsl
+   mybet = fsl.BET(from_file='bet-settings.json', frac=0.7)
+
+In this case, ``mybet.inputs.frac`` will contain the value ``0.7`` regardless
+the value that could be stored in the ``bet-settings.json`` file.
+
+
 Getting Help
 ------------
 

examples/smri_ants_registration.py

@@ -10,7 +10,9 @@
 coregister two T1 volumes.
 
 1. Tell python where to find the appropriate functions.
+
 """
+
 from __future__ import print_function, unicode_literals
 from builtins import open
 
@@ -25,6 +27,7 @@
 
 """
 2. Download T1 volumes into home directory
+
 """
 
 homeDir = os.getenv("HOME")
@@ -57,36 +60,44 @@
 ]
 
 """
-3. Define the parameters of the registration
+3. Define the parameters of the registration. Settings are
+saved in ``smri_ants_registration_settings.json``.
+
 """
 
-reg = Registration()
+reg = Registration(from_file='./smri_ants_registration_settings.json')
 reg.inputs.fixed_image = input_images[0]
 reg.inputs.moving_image = input_images[1]
-reg.inputs.output_transform_prefix = 'thisTransform'
-reg.inputs.output_warped_image = 'INTERNAL_WARPED.nii.gz'
-
-reg.inputs.output_transform_prefix = "output_"
-reg.inputs.transforms = ['Translation', 'Rigid', 'Affine', 'SyN']
-reg.inputs.transform_parameters = [(0.1,), (0.1,), (0.1,), (0.2, 3.0, 0.0)]
-reg.inputs.number_of_iterations = ([[10000, 111110, 11110]] * 3 +
-                                   [[100, 50, 30]])
-reg.inputs.dimension = 3
-reg.inputs.write_composite_transform = True
-reg.inputs.collapse_output_transforms = False
-reg.inputs.metric = ['Mattes'] * 3 + [['Mattes', 'CC']]
-reg.inputs.metric_weight = [1] * 3 + [[0.5, 0.5]]
-reg.inputs.radius_or_number_of_bins = [32] * 3 + [[32, 4]]
-reg.inputs.sampling_strategy = ['Regular'] * 3 + [[None, None]]
-reg.inputs.sampling_percentage = [0.3] * 3 + [[None, None]]
-reg.inputs.convergence_threshold = [1.e-8] * 3 + [-0.01]
-reg.inputs.convergence_window_size = [20] * 3 + [5]
-reg.inputs.smoothing_sigmas = [[4, 2, 1]] * 3 + [[1, 0.5, 0]]
-reg.inputs.sigma_units = ['vox'] * 4
-reg.inputs.shrink_factors = [[6, 4, 2]] + [[3, 2, 1]] * 2 + [[4, 2, 1]]
-reg.inputs.use_estimate_learning_rate_once = [True] * 4
-reg.inputs.use_histogram_matching = [False] * 3 + [True]
-reg.inputs.initial_moving_transform_com = True
+
+"""
+Alternatively to the use of the ``from_file`` feature to load ANTs settings,
+the user can manually set all those inputs instead::
+
+    reg.inputs.output_transform_prefix = 'thisTransform'
+    reg.inputs.output_warped_image = 'INTERNAL_WARPED.nii.gz'
+    reg.inputs.output_transform_prefix = "output_"
+    reg.inputs.transforms = ['Translation', 'Rigid', 'Affine', 'SyN']
+    reg.inputs.transform_parameters = [(0.1,), (0.1,), (0.1,), (0.2, 3.0, 0.0)]
+    reg.inputs.number_of_iterations = ([[10000, 111110, 11110]] * 3 +
+                                       [[100, 50, 30]])
+    reg.inputs.dimension = 3
+    reg.inputs.write_composite_transform = True
+    reg.inputs.collapse_output_transforms = False
+    reg.inputs.metric = ['Mattes'] * 3 + [['Mattes', 'CC']]
+    reg.inputs.metric_weight = [1] * 3 + [[0.5, 0.5]]
+    reg.inputs.radius_or_number_of_bins = [32] * 3 + [[32, 4]]
+    reg.inputs.sampling_strategy = ['Regular'] * 3 + [[None, None]]
+    reg.inputs.sampling_percentage = [0.3] * 3 + [[None, None]]
+    reg.inputs.convergence_threshold = [1.e-8] * 3 + [-0.01]
+    reg.inputs.convergence_window_size = [20] * 3 + [5]
+    reg.inputs.smoothing_sigmas = [[4, 2, 1]] * 3 + [[1, 0.5, 0]]
+    reg.inputs.sigma_units = ['vox'] * 4
+    reg.inputs.shrink_factors = [[6, 4, 2]] + [[3, 2, 1]] * 2 + [[4, 2, 1]]
+    reg.inputs.use_estimate_learning_rate_once = [True] * 4
+    reg.inputs.use_histogram_matching = [False] * 3 + [True]
+    reg.inputs.initial_moving_transform_com = True
+
+"""
 
 print(reg.cmdline)
 

examples/smri_ants_registration_settings.json

@@ -0,0 +1,181 @@
+{
+    "convergence_window_size": [
+        20,
+        20,
+        20,
+        5
+    ],
+    "winsorize_lower_quantile": 0.0,
+    "output_transform_prefix": "output_",
+    "transforms": [
+        "Translation",
+        "Rigid",
+        "Affine",
+        "SyN"
+    ],
+    "initial_moving_transform_com": true,
+    "metric_weight": [
+        1.0,
+        1.0,
+        1.0,
+        [
+            0.5,
+            0.5
+        ]
+    ],
+    "sigma_units": [
+        "vox",
+        "vox",
+        "vox",
+        "vox"
+    ],
+    "convergence_threshold": [
+        1e-08,
+        1e-08,
+        1e-08,
+        -0.01
+    ],
+    "sampling_strategy": [
+        "Regular",
+        "Regular",
+        "Regular",
+        [
+            null,
+            null
+        ]
+    ],
+    "shrink_factors": [
+        [
+            6,
+            4,
+            2
+        ],
+        [
+            3,
+            2,
+            1
+        ],
+        [
+            3,
+            2,
+            1
+        ],
+        [
+            4,
+            2,
+            1
+        ]
+    ],
+    "winsorize_upper_quantile": 1.0,
+    "metric": [
+        "Mattes",
+        "Mattes",
+        "Mattes",
+        [
+            "Mattes",
+            "CC"
+        ]
+    ],
+    "interpolation": "Linear",
+    "ignore_exception": false,
+    "use_estimate_learning_rate_once": [
+        true,
+        true,
+        true,
+        true
+    ],
+    "terminal_output": "stream",
+    "write_composite_transform": true,
+    "initialize_transforms_per_stage": false,
+    "num_threads": 1,
+    "output_warped_image": "INTERNAL_WARPED.nii.gz",
+    "sampling_percentage": [
+        0.3,
+        0.3,
+        0.3,
+        [
+            null,
+            null
+        ]
+    ],
+    "number_of_iterations": [
+        [
+            10000,
+            111110,
+            11110
+        ],
+        [
+            10000,
+            111110,
+            11110
+        ],
+        [
+            10000,
+            111110,
+            11110
+        ],
+        [
+            100,
+            50,
+            30
+        ]
+    ],
+    "radius_or_number_of_bins": [
+        32,
+        32,
+        32,
+        [
+            32,
+            4
+        ]
+    ],
+    "environ": {
+        "NSLOTS": "1"
+    },
+    "smoothing_sigmas": [
+        [
+            4.0,
+            2.0,
+            1.0
+        ],
+        [
+            4.0,
+            2.0,
+            1.0
+        ],
+        [
+            4.0,
+            2.0,
+            1.0
+        ],
+        [
+            1.0,
+            0.5,
+            0.0
+        ]
+    ],
+    "use_histogram_matching": [
+        false,
+        false,
+        false,
+        true
+    ],
+    "transform_parameters": [
+        [
+            0.1
+        ],
+        [
+            0.1
+        ],
+        [
+            0.1
+        ],
+        [
+            0.2,
+            3.0,
+            0.0
+        ]
+    ],
+    "dimension": 3,
+    "collapse_output_transforms": false
+}