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, affine_stepsize=None, deformative_stepsize=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_transform.

Args: 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 (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.

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. affine_stepsize (float, optional): The stepsize for affine adjustments. Should be between 0 and 1. Defaults to 0.2. deformative_stepsize (float, optional): The stepsize for deformative adjustments. Defaults to 0. 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.