class ardent.transform.Transform[source]

Transform stores the deformation that is output by a registration and provides methods for applying that transformation to various images.

Initialize Transform object. Sets attributes to None.


Constructs lddmm_dict, a dictionary of this object's attributes as populated by the return from lddmm_register.

Returns:The attributes of this Transform object, matching the dictionary returned from lddmm_register.
Return type:dict
register(self, template, target, template_resolution=1, target_resolution=1, preset=None, translational_stepsize=0, linear_stepsize=0, deformative_stepsize=0, sigma_regularization=0, num_iterations=200, num_affine_only_iterations=50, initial_affine=None, initial_velocity_fields=None, initial_contrast_coefficients=None, num_timesteps=5, smooth_length=None, contrast_order=1, contrast_tolerance=1e-05, contrast_maxiter=100, sigma_contrast=0.01, sigma_matching=None, spatially_varying_contrast_map=False, calibrate=False, track_progress_every_n=0)[source]

Compute a registration between template and target, to be applied with apply_lddmm.

  • template (np.ndarray) -- The ideally clean template image being registered to the target.
  • target (np.ndarray) -- The potentially messier target image being registered to.
  • template_resolution (float, list, optional) -- A scalar or list of scalars indicating the resolution of the template. Defaults to 1.
  • target_resolution (float, optional) -- A scalar or list of scalars indicating the resolution of the target. Defaults to 1.
  • preset (string, Nontranslational_stepsizeype, optional) --

    Preset of registration parameters. Overrides some subset of the registration parameters with preset values if provided. Supported options:

    'identity' 'clarity, mouse' 'nissl, mouse' 'mri, human'

    Defaults to: None.

  • translational_stepsize (float, optional) -- The stepsize for translational adjustments. Defaults to 0.
  • linear_stepsize (float, optional) -- The stepsize for linear adjustments. Defaults to 0.
  • deformative_stepsize (float, optional) -- The stepsize for deformative adjustments. Defaults to 0.
  • sigma_regularization (float, optional) -- A scalar indicating the freedom to deform. Defaults to 0.
  • num_iterations (int, optional) -- The total number of iterations. Defaults to 200.
  • num_affine_only_iterations (int, optional) -- The number of iterations at the start of the process without deformative adjustments. Defaults to 50.
  • initial_affine (np.ndarray, optional) -- The affine array that the registration will begin with. Defaults to np.eye(template.ndim + 1).
  • initial_velocity_fields (np.ndarray, optional) -- The velocity fields that the registration will begin with. Defaults to None.
  • initial_contrast_coefficients (np.ndarray, optional) -- The contrast coefficients that the registration will begin with. If None, the 0th order coefficient(s) are set to np.mean( - np.mean(self.template) * np.std( / np.std(self.template), if self.contrast_order > 1, the 1st order coefficient(s) are set to np.std( / np.std(self.template), and all others are set to zero. Defaults to None.
  • num_timesteps (int, optional) -- The number of composed sub-transformations in the diffeomorphism. Defaults to 5.
  • smooth_length (float, optional) -- The length scale of smoothing. Defaults to None.
  • contrast_order (int, optional) -- The order of the polynomial fit between the contrasts of the template and target. Defaults to 3.
  • contrast_tolerance (float, optional) -- The tolerance for convergence to the optimal contrast_coefficients if spatially_varying_contrast_map == True. Defaults to 1e-5.
  • contrast_maxiter (int, optional) -- The maximum number of iterations to converge toward the optimal contrast_coefficients if spatially_varying_contrast_map == True. Defaults to 100.
  • sigma_contrast (float, optional) -- The scale of variation in the contrast_coefficients if spatially_varying_contrast_map == True. Defaults to 1e-2.
  • sigma_matching (float, optional) -- A measure of spread. Defaults to None.
  • spatially_varying_contrast_map (bool, optional) -- If True, uses a polynomial per voxel to compute the contrast map rather than a single polynomial. Defaults to False.
  • calibrate (bool, optional) -- A boolean flag indicating whether to accumulate additional intermediate values and display informative plots for calibration purposes. Defaults to False.
  • track_progress_every_n (int, optional) -- If positive, a progress update will be printed every track_progress_every_n iterations of registration. Defaults to 0.
continue_registration(self, **registration_parameter_updates)[source]

Continue registering with all the same registration parameters from the previous call to the register method, but with initial_affine, initial_velocity_fields, and initial_contrast_coefficients set to the affine, velocity_fields, and contrast_coefficients most recently calculated in the register method, updated by registration_parameter_updates.

registration_parameter_updates (key-value pairs, optional): registration parameters provided as kwargs
to overwrite the most recent registration_parameters used in the register method. Defaults to {}.
Raises:RuntimeError -- Raised if self._registration_parameters are not set (as they should be after a call to the register method).
apply_transform(self, subject, subject_resolution=1, output_resolution=None, deform_to='template', extrapolation_fill_value=None, save_path=None)[source]

Apply the transformation--computed by the last call to self.register--to subject, deforming it into the space of deform_to.

  • subject (np.ndarray) -- The image to deform.
  • subject_resolution (float, seq, optional) -- The resolution of subject in each dimension, or just one scalar to indicate isotropy. Defaults to 1.
  • deform_to (str, optional) -- Either 'template' or 'target' indicating which to deform subject to match. Defaults to: "template".
  • output_resolution (NoneType, float, seq, optional) -- The resolution of the output deformed_subject in each dimension, or just one scalar to indicate isotropy, or None to indicate the resolution of template or target based on deform_to. Defaults to None.
  • extrapolation_fill_value (float, NoneType, optional) -- The fill_value kwarg passed to scipy.interpolate.interpn; it should be background intensity.
  • None, this is set to a low quantile of the subject's 10**-subject.ndim quantile to estimate background. Defaults to None. (If) --
  • save_path (str, Path, optional) -- The full path to save the output to. Defaults to: None.

The result of deforming subject to match deform_to.

Return type:


save(self, file_path)[source]

Save the entire instance of this Transform object (self) to file.

Parameters:file_path (str, Path) -- The full path to save self to.
load(self, file_path)[source]

Load an entire instance of a Transform object from memory, as from a file created with the save method, and transplants all of its writeable attributes into self.

Parameters:file_path (str, Path) -- The full path that a Transform object was saved to.