Skip to content

Commit 10f28fe

Browse files
satrasatra
authored
Merge pull request #1591 from oesteban/enh/InterfaceLoadSettings
[ENH] Convenient load/save of interface inputs
2 parents 20c40ae + 4b155b1 commit 10f28fe

File tree

6 files changed

+339
-34
lines changed

6 files changed

+339
-34
lines changed

‎CHANGES

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
Upcoming release 0.13
22
=====================
33

4+
* ENH: Convenient load/save of interface inputs (https://github.com/nipy/nipype/pull/1591)
45
* ENH: Add a Framewise Displacement calculation interface (https://github.com/nipy/nipype/pull/1604)
56
* FIX: Use builtins open and unicode literals for py3 compatibility (https://github.com/nipy/nipype/pull/1572)
67
* TST: reduce the size of docker images & use tags for images (https://github.com/nipy/nipype/pull/1564)

‎doc/users/interface_tutorial.rst

Lines changed: 45 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,27 +4,27 @@
44
Tutorial : Interfaces
55
=======================
66

7-
Specifying options
8-
------------------
7+
Specifying input settings
8+
-------------------------
99

1010
The nipype interface modules provide a Python interface to external
1111
packages like FSL_ and SPM_. Within the module are a series of Python
1212
classes which wrap specific package functionality. For example, in
1313
the fsl module, the class :class:`nipype.interfaces.fsl.Bet` wraps the
1414
``bet`` command-line tool. Using the command-line tool, one would
15-
specify options using flags like ``-o``, ``-m``, ``-f <f>``, etc...
15+
specify input settings using flags like ``-o``, ``-m``, ``-f <f>``, etc...
1616
However, in nipype, options are assigned to Python attributes and can
1717
be specified in the following ways:
1818

19-
Options can be assigned when you first create an interface object:
19+
Settings can be assigned when you first create an interface object:
2020

2121
.. testcode::
2222

2323
import nipype.interfaces.fsl as fsl
2424
mybet = fsl.BET(in_file='foo.nii', out_file='bar.nii')
2525
result = mybet.run()
2626

27-
Options can be assigned through the ``inputs`` attribute:
27+
Settings can be assigned through the ``inputs`` attribute:
2828

2929
.. testcode::
3030

@@ -34,14 +34,53 @@ Options can be assigned through the ``inputs`` attribute:
3434
mybet.inputs.out_file = 'bar.nii'
3535
result = mybet.run()
3636

37-
Options can be assigned when calling the ``run`` method:
37+
Settings can be assigned when calling the ``run`` method:
3838

3939
.. testcode::
4040

4141
import nipype.interfaces.fsl as fsl
4242
mybet = fsl.BET()
4343
result = mybet.run(in_file='foo.nii', out_file='bar.nii', frac=0.5)
4444

45+
Settings can be saved to a json file:
46+
47+
.. testcode::
48+
49+
import nipype.interfaces.fsl as fsl
50+
mybet = fsl.BET(in_file='foo.nii', out_file='bar.nii', frac=0.5)
51+
mybet.save_inputs_to_json('bet-settings.json')
52+
53+
Once saved, the three inputs set for ``mybet`` will be stored in a JSON
54+
file. These settings can also be loaded from a json file:
55+
56+
.. testcode::
57+
58+
import nipype.interfaces.fsl as fsl
59+
mybet = fsl.BET()
60+
mybet.load_inputs_from_json('bet-settings.json', overwrite=False)
61+
62+
63+
Loading settings will overwrite previously set inputs by default, unless
64+
the ``overwrite`` argument is ``False``. Conveniently, the settings can be
65+
also read during the interface instantiation:
66+
67+
.. testcode::
68+
69+
import nipype.interfaces.fsl as fsl
70+
mybet = fsl.BET(from_file='bet-settings.json')
71+
72+
If the user provides settings during interface creation, they will take
73+
precedence over those loaded using ``from_file``:
74+
75+
.. testcode::
76+
77+
import nipype.interfaces.fsl as fsl
78+
mybet = fsl.BET(from_file='bet-settings.json', frac=0.7)
79+
80+
In this case, ``mybet.inputs.frac`` will contain the value ``0.7`` regardless
81+
the value that could be stored in the ``bet-settings.json`` file.
82+
83+
4584
Getting Help
4685
------------
4786

‎examples/smri_ants_registration.py

Lines changed: 37 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,9 @@
1010
coregister two T1 volumes.
1111
1212
1. Tell python where to find the appropriate functions.
13+
1314
"""
15+
1416
from __future__ import print_function, unicode_literals
1517
from builtins import open
1618

@@ -25,6 +27,7 @@
2527

2628
"""
2729
2. Download T1 volumes into home directory
30+
2831
"""
2932

3033
homeDir = os.getenv("HOME")
@@ -57,36 +60,44 @@
5760
]
5861

5962
"""
60-
3. Define the parameters of the registration
63+
3. Define the parameters of the registration. Settings are
64+
saved in ``smri_ants_registration_settings.json``.
65+
6166
"""
6267

63-
reg = Registration()
68+
reg = Registration(from_file='./smri_ants_registration_settings.json')
6469
reg.inputs.fixed_image = input_images[0]
6570
reg.inputs.moving_image = input_images[1]
66-
reg.inputs.output_transform_prefix = 'thisTransform'
67-
reg.inputs.output_warped_image = 'INTERNAL_WARPED.nii.gz'
68-
69-
reg.inputs.output_transform_prefix = "output_"
70-
reg.inputs.transforms = ['Translation', 'Rigid', 'Affine', 'SyN']
71-
reg.inputs.transform_parameters = [(0.1,), (0.1,), (0.1,), (0.2, 3.0, 0.0)]
72-
reg.inputs.number_of_iterations = ([[10000, 111110, 11110]] * 3 +
73-
[[100, 50, 30]])
74-
reg.inputs.dimension = 3
75-
reg.inputs.write_composite_transform = True
76-
reg.inputs.collapse_output_transforms = False
77-
reg.inputs.metric = ['Mattes'] * 3 + [['Mattes', 'CC']]
78-
reg.inputs.metric_weight = [1] * 3 + [[0.5, 0.5]]
79-
reg.inputs.radius_or_number_of_bins = [32] * 3 + [[32, 4]]
80-
reg.inputs.sampling_strategy = ['Regular'] * 3 + [[None, None]]
81-
reg.inputs.sampling_percentage = [0.3] * 3 + [[None, None]]
82-
reg.inputs.convergence_threshold = [1.e-8] * 3 + [-0.01]
83-
reg.inputs.convergence_window_size = [20] * 3 + [5]
84-
reg.inputs.smoothing_sigmas = [[4, 2, 1]] * 3 + [[1, 0.5, 0]]
85-
reg.inputs.sigma_units = ['vox'] * 4
86-
reg.inputs.shrink_factors = [[6, 4, 2]] + [[3, 2, 1]] * 2 + [[4, 2, 1]]
87-
reg.inputs.use_estimate_learning_rate_once = [True] * 4
88-
reg.inputs.use_histogram_matching = [False] * 3 + [True]
89-
reg.inputs.initial_moving_transform_com = True
71+
72+
"""
73+
Alternatively to the use of the ``from_file`` feature to load ANTs settings,
74+
the user can manually set all those inputs instead::
75+
76+
reg.inputs.output_transform_prefix = 'thisTransform'
77+
reg.inputs.output_warped_image = 'INTERNAL_WARPED.nii.gz'
78+
reg.inputs.output_transform_prefix = "output_"
79+
reg.inputs.transforms = ['Translation', 'Rigid', 'Affine', 'SyN']
80+
reg.inputs.transform_parameters = [(0.1,), (0.1,), (0.1,), (0.2, 3.0, 0.0)]
81+
reg.inputs.number_of_iterations = ([[10000, 111110, 11110]] * 3 +
82+
[[100, 50, 30]])
83+
reg.inputs.dimension = 3
84+
reg.inputs.write_composite_transform = True
85+
reg.inputs.collapse_output_transforms = False
86+
reg.inputs.metric = ['Mattes'] * 3 + [['Mattes', 'CC']]
87+
reg.inputs.metric_weight = [1] * 3 + [[0.5, 0.5]]
88+
reg.inputs.radius_or_number_of_bins = [32] * 3 + [[32, 4]]
89+
reg.inputs.sampling_strategy = ['Regular'] * 3 + [[None, None]]
90+
reg.inputs.sampling_percentage = [0.3] * 3 + [[None, None]]
91+
reg.inputs.convergence_threshold = [1.e-8] * 3 + [-0.01]
92+
reg.inputs.convergence_window_size = [20] * 3 + [5]
93+
reg.inputs.smoothing_sigmas = [[4, 2, 1]] * 3 + [[1, 0.5, 0]]
94+
reg.inputs.sigma_units = ['vox'] * 4
95+
reg.inputs.shrink_factors = [[6, 4, 2]] + [[3, 2, 1]] * 2 + [[4, 2, 1]]
96+
reg.inputs.use_estimate_learning_rate_once = [True] * 4
97+
reg.inputs.use_histogram_matching = [False] * 3 + [True]
98+
reg.inputs.initial_moving_transform_com = True
99+
100+
"""
90101

91102
print(reg.cmdline)
92103

‎examples/smri_ants_registration_settings.json

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
{
2+
"convergence_window_size": [
3+
20,
4+
20,
5+
20,
6+
5
7+
],
8+
"winsorize_lower_quantile": 0.0,
9+
"output_transform_prefix": "output_",
10+
"transforms": [
11+
"Translation",
12+
"Rigid",
13+
"Affine",
14+
"SyN"
15+
],
16+
"initial_moving_transform_com": true,
17+
"metric_weight": [
18+
1.0,
19+
1.0,
20+
1.0,
21+
[
22+
0.5,
23+
0.5
24+
]
25+
],
26+
"sigma_units": [
27+
"vox",
28+
"vox",
29+
"vox",
30+
"vox"
31+
],
32+
"convergence_threshold": [
33+
1e-08,
34+
1e-08,
35+
1e-08,
36+
-0.01
37+
],
38+
"sampling_strategy": [
39+
"Regular",
40+
"Regular",
41+
"Regular",
42+
[
43+
null,
44+
null
45+
]
46+
],
47+
"shrink_factors": [
48+
[
49+
6,
50+
4,
51+
2
52+
],
53+
[
54+
3,
55+
2,
56+
1
57+
],
58+
[
59+
3,
60+
2,
61+
1
62+
],
63+
[
64+
4,
65+
2,
66+
1
67+
]
68+
],
69+
"winsorize_upper_quantile": 1.0,
70+
"metric": [
71+
"Mattes",
72+
"Mattes",
73+
"Mattes",
74+
[
75+
"Mattes",
76+
"CC"
77+
]
78+
],
79+
"interpolation": "Linear",
80+
"ignore_exception": false,
81+
"use_estimate_learning_rate_once": [
82+
true,
83+
true,
84+
true,
85+
true
86+
],
87+
"terminal_output": "stream",
88+
"write_composite_transform": true,
89+
"initialize_transforms_per_stage": false,
90+
"num_threads": 1,
91+
"output_warped_image": "INTERNAL_WARPED.nii.gz",
92+
"sampling_percentage": [
93+
0.3,
94+
0.3,
95+
0.3,
96+
[
97+
null,
98+
null
99+
]
100+
],
101+
"number_of_iterations": [
102+
[
103+
10000,
104+
111110,
105+
11110
106+
],
107+
[
108+
10000,
109+
111110,
110+
11110
111+
],
112+
[
113+
10000,
114+
111110,
115+
11110
116+
],
117+
[
118+
100,
119+
50,
120+
30
121+
]
122+
],
123+
"radius_or_number_of_bins": [
124+
32,
125+
32,
126+
32,
127+
[
128+
32,
129+
4
130+
]
131+
],
132+
"environ": {
133+
"NSLOTS": "1"
134+
},
135+
"smoothing_sigmas": [
136+
[
137+
4.0,
138+
2.0,
139+
1.0
140+
],
141+
[
142+
4.0,
143+
2.0,
144+
1.0
145+
],
146+
[
147+
4.0,
148+
2.0,
149+
1.0
150+
],
151+
[
152+
1.0,
153+
0.5,
154+
0.0
155+
]
156+
],
157+
"use_histogram_matching": [
158+
false,
159+
false,
160+
false,
161+
true
162+
],
163+
"transform_parameters": [
164+
[
165+
0.1
166+
],
167+
[
168+
0.1
169+
],
170+
[
171+
0.1
172+
],
173+
[
174+
0.2,
175+
3.0,
176+
0.0
177+
]
178+
],
179+
"dimension": 3,
180+
"collapse_output_transforms": false
181+
}

0 commit comments

Comments
 (0)