ants.Registration `restrict_deformation` trait only taking 1 or 0

[kcho]

Summary

--restrict-deformation option in antsRegistration takes in float.
However, in nipype ants.Registration, the restrict_deformation trait only takes 1 or 0

For example, below gives error

        reg = Registration()
        reg.inputs.dimension = 3
        
        reg.inputs.fixed_image = self.t1_brain_recip
        reg.inputs.moving_image = self.nodif_loc
        reg.inputs.initial_moving_transform = self.t1_to_dti_flirt_mat_c3d
        reg.inputs.invert_initial_moving_transform = False
        reg.inputs.output_transform_prefix = self.t1_to_dti_ants_mat
        reg.inputs.metric = ['CC']
        reg.inputs.metric_weight = [1]
        reg.inputs.radius_or_number_of_bins = [4]
        reg.inputs.number_of_iterations = [[100, 70, 20]]
        reg.inputs.convergence_threshold = [1.e-7]
        reg.inputs.convergence_window_size = [5]
        reg.inputs.transforms = ['SyN']
        reg.inputs.transform_parameters = [(0.1, 3, 0)]
        reg.inputs.shrink_factors = [[4,2,1]]
        reg.inputs.smoothing_sigmas = [[2,1,0]]
        reg.inputs.sigma_units = ['vox']
        reg.inputs.restrict_deformation = [[0.1, 1.0, 0.1]]
        reg.inputs.collapse_output_transforms = True
        reg.inputs.winsorize_lower_quantile = 0.005
        reg.inputs.winsorize_upper_quantile = 0.995
        reg.inputs.verbose = True

---------------------------------------------------------------------------
TraitError                                Traceback (most recent call last)
<ipython-input-20-ebf795f87438> in <module>()
      4 # prac.t1_to_dti_registration()
      5 # prac.t1_to_dti_registration_c3d()
----> 6 prac.ants_unwarping()

<ipython-input-19-25032190378e> in ants_unwarping(self)
    661         reg.inputs.smoothing_sigmas = [[2,1,0]]
    662         reg.inputs.sigma_units = ['vox']
--> 663         reg.inputs.restrict_deformation = [[0.1, 1.0, 0.1]]
    664         reg.inputs.collapse_output_transforms = True
    665         reg.inputs.winsorize_lower_quantile = 0.005

/ccnc_bin/anaconda3/lib/python3.6/site-packages/traits/trait_types.py in validate(self, object, name, value)
   2334                 return value
   2335 
-> 2336             return TraitListObject( self, object, name, value )
   2337 
   2338         self.error( object, name, value )

/ccnc_bin/anaconda3/lib/python3.6/site-packages/traits/trait_handlers.py in __init__(self, trait, object, name, value)
   2311             except TraitError as excp:
   2312                 excp.set_prefix( 'Each element of the' )
-> 2313                 raise excp
   2314 
   2315         self.len_error( len( value ) )

/ccnc_bin/anaconda3/lib/python3.6/site-packages/traits/trait_handlers.py in __init__(self, trait, object, name, value)
   2303                 validate = trait.item_trait.handler.validate
   2304                 if validate is not None:
-> 2305                     value = [ validate( object, name, val ) for val in value ]
   2306 
   2307                 list.__setitem__(self, slice(0, 0), value )

/ccnc_bin/anaconda3/lib/python3.6/site-packages/traits/trait_handlers.py in <listcomp>(.0)
   2303                 validate = trait.item_trait.handler.validate
   2304                 if validate is not None:
-> 2305                     value = [ validate( object, name, val ) for val in value ]
   2306 
   2307                 list.__setitem__(self, slice(0, 0), value )

/ccnc_bin/anaconda3/lib/python3.6/site-packages/traits/trait_types.py in validate(self, object, name, value)
   2334                 return value
   2335 
-> 2336             return TraitListObject( self, object, name, value )
   2337 
   2338         self.error( object, name, value )

/ccnc_bin/anaconda3/lib/python3.6/site-packages/traits/trait_handlers.py in __init__(self, trait, object, name, value)
   2311             except TraitError as excp:
   2312                 excp.set_prefix( 'Each element of the' )
-> 2313                 raise excp
   2314 
   2315         self.len_error( len( value ) )

/ccnc_bin/anaconda3/lib/python3.6/site-packages/traits/trait_handlers.py in __init__(self, trait, object, name, value)
   2303                 validate = trait.item_trait.handler.validate
   2304                 if validate is not None:
-> 2305                     value = [ validate( object, name, val ) for val in value ]
   2306 
   2307                 list.__setitem__(self, slice(0, 0), value )

/ccnc_bin/anaconda3/lib/python3.6/site-packages/traits/trait_handlers.py in <listcomp>(.0)
   2303                 validate = trait.item_trait.handler.validate
   2304                 if validate is not None:
-> 2305                     value = [ validate( object, name, val ) for val in value ]
   2306 
   2307                 list.__setitem__(self, slice(0, 0), value )

/ccnc_bin/anaconda3/lib/python3.6/site-packages/traits/trait_types.py in validate(self, object, name, value)
   2010             return value
   2011 
-> 2012         self.error( object, name, value )
   2013 
   2014     def full_info ( self, object, name, value ):

/ccnc_bin/anaconda3/lib/python3.6/site-packages/traits/trait_handlers.py in error(self, object, name, value)
    170         """
    171         raise TraitError( object, name, self.full_info( object, name, value ),
--> 172                           value )
    173 
    174     def full_info ( self, object, name, value ):

TraitError: Each element of the 'restrict_deformation' trait of a RegistrationInputSpec instance must be 0 or 1, but a value of 0.1 <class 'float'> was specified.

Best regards,
Kevin

[djarecka]

could you please point me to the place where you found this is a float? reading the help command, it's not clear to me.

[mgxd]

It's not very well documented, but there are some use cases ANTsX/ANTs#216 where this applies. @kcho do you know if possible values only range from 0-1?

[kcho]

@mgxd thank you for your prompt reply. I'm not sure about the range, as I only tried 0.1, 0.2, 1

[AndrewLawrence]

I use this feature of antsRegistration.

As far as I can tell from the C++ the float values work as a multiplicative factor for a calculated field (i.e. there is no norming of the floats over the dimensions). So 1.0 for a given dimension is no change, 0.0 is no warping in that dimension and 0.1 is 1/10th of the estimated warp.

I can't think of any sensible usage outside of [0-1], and numbers outside this range would make "restrict-deformation" a misnomer (you would be exaggerating at >1 or reversing deformations at <0).
This said, ANTS doesn't seem to stop you doing this (I can't actually test this at the moment because of server maintenance)

[effigies]

@kcho @AndrewLawrence Are either of you interested in opening a pull request?