transform

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.

get_lddmm_dict(self)[source]

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=None, target_resolution=None, preset=None, num_iterations=None, num_affine_only_iterations=None, num_rigid_affine_iterations=None, affine_stepsize=None, deformative_stepsize=None, fixed_affine_scale=None, sigma_regularization=None, smooth_length=None, num_timesteps=None, contrast_order=None, spatially_varying_contrast_map=None, contrast_maxiter=None, contrast_tolerance=None, sigma_contrast=None, check_artifacts=None, sigma_artifact=None, sigma_matching=None, initial_affine=None, initial_velocity_fields=None, initial_contrast_coefficients=None, calibrate=None, track_progress_every_n=None)[source]

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

Parameters:
  • 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. Overrides 0 input. Defaults to 1.
  • target_resolution (float, optional) -- A scalar or list of scalars indicating the resolution of the target. Overrides 0 input. Defaults to 1.
  • preset (str, optional) -- A string specifying a recognized preset, or subset of the following arguments to provide automatically, overridden by values specified in this call. Defaults to None.
  • num_iterations (int, optional) -- The total number of iterations. Defaults to 300.
  • num_affine_only_iterations (int, optional) -- The number of iterations at the start of the process without deformative adjustments. Defaults to 100.
  • num_rigid_affine_iterations (int, optional) -- The number of iterations at the start of the process in which the affine is kept rigid. Defaults to 50.
  • affine_stepsize (float, optional) -- The unitless stepsize for affine adjustments. Should be between 0 and 1. Defaults to 0.3.
  • deformative_stepsize (float, optional) -- The stepsize for deformative adjustments. Optimal values are problem-specific. If equal to 0 then the result is affine-only registration. Defaults to 0.
  • fixed_affine_scale (float, seq, optional) -- The per-dimension scale to impose on the affine at every iteration. If None, no scale is imposed. Defaults to None.
  • sigma_regularization (float, optional) -- A scalar indicating the freedom to deform. Overrides 0 input. Defaults to 10 * np.max(self.template_resolution).
  • smooth_length (float, optional) -- The length scale of smoothing. Overrides 0 input. Defaults to 2 * np.max(self.template_resolution).
  • num_timesteps (int, optional) -- The number of composed sub-transformations in the diffeomorphism. Overrides 0 input. Defaults to 5.
  • contrast_order (int, optional) -- The order of the polynomial fit between the contrasts of the template and target. Overrides 0 input. Defaults to 1.
  • 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.
  • contrast_maxiter (int, optional) -- The maximum number of iterations to converge toward the optimal contrast_coefficients if spatially_varying_contrast_map == True. Overrides 0 input. Defaults to 100.
  • contrast_tolerance (float, optional) -- The tolerance for convergence to the optimal contrast_coefficients if spatially_varying_contrast_map == True. Defaults to 1e-5.
  • sigma_contrast (float, optional) -- The scale of variation in the contrast_coefficients if spatially_varying_contrast_map == True. Overrides 0 input. Defaults to 1e-2.
  • check_artifacts (bool, optional) -- If True, artifacts are jointly classified with registration using sigma_artifact. Defaults to False.
  • sigma_artifact (float, optional) -- The level of expected variation between artifact and non-artifact intensities. Overrides 0 input. Defaults to 5 * sigma_matching.
  • sigma_matching (float, optional) -- An estimate of the spread of the noise in the target, representing the tradeoff between the regularity and accuracy of the registration, where a smaller value should result in a less smooth, more accurate result. Typically it should be set to an estimate of the standard deviation of the noise in the image, particularly with artifacts. Overrides 0 input. Defaults to the standard deviation of the target.
  • 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 all zeros.
  • 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(self.target) - np.mean(self.template) * np.std(self.target) / np.std(self.template), if self.contrast_order > 1, the 1st order coefficient(s) are set to np.std(self.target) / np.std(self.template), and all others are set to zero. Defaults to None.
  • 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.

Kwargs:
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.

Parameters:
  • 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.
Returns:

The result of deforming subject to match deform_to.

Return type:

np.ndarray

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.