ramac package

ramac.correspondence_csv_input module

ramac.correspondence_csv_input.create_final_dataframe_timepoints(correspondences, unmatched_names_df1, unmatched_names_df2, df1_file, df2_file)

Create a final DataFrame containing lesion correspondences between two timepoints.

Parameters

  • correspondences (pandas.DataFrame) – DataFrame containing lesion or ROI correspondences.

  • unmatched_names_df1 (pandas.DataFrame) – DataFrame containing unmatched indices from the first file.

  • unmatched_names_df2 (pandas.DataFrame) – DataFrame containing unmatched indices from the second file.

  • df1_file (str) – The file path to the first set of lesions or ROIs.

  • df2_file (str) – The file path to the second set of lesions or ROIs.

Returns

A DataFrame containing the final lesion correspondences.

Return type

pandas.DataFrame

ramac.correspondence_csv_input.find_corresponding_lesions_timepoints(df1_file, df2_file, threshold)

Find corresponding lesions between two sets of lesions or ROIs.

Parameters

  • df1_file (str) – The file path to the first set of lesions or ROIs.

  • df2_file (str) – The file path to the second set of lesions or ROIs.

  • threshold (float) – The threshold distance for considering lesions or ROIs as corresponding.

Returns

A tuple containing correspondences DataFrame, unmatched indices DataFrame from the first file, and unmatched indices DataFrame from the second file.

Return type

Tuple[pandas.DataFrame, pandas.DataFrame, pandas.DataFrame]

ramac.correspondence_csv_input.plot_lesion_correspondences_timepoints(df1_file, df2_file)

Plot lesion correspondences between two timepoints.

Parameters

  • df1_file (str) – The file path to the first set of lesions or ROIs.

  • df2_file (str) – The file path to the second set of lesions or ROIs.

Returns

None

ramac.correspondence_csv_input.process_lesion_timepoints(screening_file, transformed_file, threshold)

Process lesion timepoints to find corresponding lesions.

Parameters

  • screening_file – str Filepath of the screening data.

  • transformed_file – str Filepath of the transformed data.

  • threshold – float Threshold value for finding corresponding lesions.

Returns

DataFrame

DataFrame containing correspondences between lesions.

unmatched_names_df1DataFrame

DataFrame containing unmatched lesions from screening data.

unmatched_names_df2DataFrame

DataFrame containing unmatched lesions from transformed data.

Return type

correspondences

ramac.correspondence_csv_input.read_lesion_csv(file_path)

Read a CSV file containing lesion data into a DataFrame.

Parameters

file_path (str) – The file path to the CSV file.

Returns

A DataFrame containing the lesion data.

Return type

pandas.DataFrame

ramac.input_transform module

ramac.merge_dataframe module

ramac.merge_dataframe.merge_indices(df)

Merge ‘Fixed Index’ and ‘Reg Index’ columns into ‘Correspondence Index’ column.

Parameters

df (pandas.DataFrame) – The DataFrame containing ‘Fixed Index’ and ‘Reg Index’ columns.

Returns

The DataFrame with a new ‘Correspondence Index (F, M)’ column

containing tuples of corresponding indices.

Return type

pandas.DataFrame

ramac.plots module

ramac.plots.compare_slices_interactive(original_phantom, transformed_phantom, moving_resampled)

Compare slices interactively for three input images.

Parameters

  • original_phantom (SimpleITK.Image) – The original phantom image.

  • transformed_phantom (SimpleITK.Image) – The transformed phantom image (which is the moving image).

  • moving_resampled (SimpleITK.Image) – The resampled moving image (registered image).

Returns

None

ramac.plots.ordinal(n)

Converts a number into its ordinal representation.

Parameters

n (int) – The number to be converted.

Returns

The ordinal representation of the number.

Return type

str

ramac.plots.plot_lesions(*args)

Plots visualizations of lesions on different slices of the obtained images (fixed, moving and registered). In each row, different orinetations (X, Y and Z slices) of a particular volumetric image are plotted across columns.

Parameters

*args – Variable number of arguments representing tuples of (image, voxel_tuples) pairs, where: image (SimpleITK.Image): The image to visualize. voxel_tuples (list): List of tuples containing voxel coordinates of lesions in the image.

Returns

None

ramac.plots.plot_lesions_1(original_phantom, transformed_phantom, moving_resampled, fixed_voxel_tuples, transformed_lesions_rounded, registered_voxel_tuples)

Plots visualizations of lesions on different slices of the obtained images (fixed, moving and registered). In each row, a particular slice of the fixed, moving and registered images are plotted across the columns

Parameters

  • original_phantom (SimpleITK.Image) – The original phantom image.

  • transformed_phantom (SimpleITK.Image) – The transformed phantom image.

  • moving_resampled (SimpleITK.Image) – The resampled moving image.

  • fixed_voxel_tuples (list) – List of tuples containing voxel coordinates of lesions in the fixed image.

  • transformed_lesions_rounded (list) – List of tuples containing transformed lesion coordinates for visualization.

  • registered_voxel_tuples (list) – List of tuples containing voxel coordinates of lesions in the registered image.

Returns

None

ramac.plots.plot_slice(ax, slice_array, centroid, title, aspect, slice_number, window_level, window_width, flip=False)

Plots a single slice of the image with the centroid of the lesion marked.

Parameters

  • ax (matplotlib.axes.Axes) – The Axes object to plot the slice on.

  • slice_array (numpy.ndarray) – The 2D array representing the image slice.

  • centroid (tuple) – The coordinates (x, y) of the lesion centroid.

  • title (str) – The title of the plot.

  • aspect (float) – The aspect ratio of the plot.

  • slice_number (int) – The number of the slice.

  • window_level (float) – The window level for image visualization.

  • window_width (float) – The window width for image visualization.

  • flip – Whether to flip the slice array vertically. Defaults to False.

ramac.plots.plot_slices_interactive(image, slice_x, slice_y, slice_z)

Plot interactive slices along each axis of the provided image.

Parameters

  • image (SimpleITK.Image) – The input 3D image.

  • slice_x (int) – The slice index along the x-axis.

  • slice_y (int) – The slice index along the y-axis.

  • slice_z (int) – The slice index along the z-axis.

Returns

None

ramac.plots.plot_triplanar(image, voxel_tuples, window_level, window_width, image_name)

Plots triplanar views (axial, sagittal, coronal) of the image slices containing lesions.

Parameters

  • image (SimpleITK.Image) – The input image containing the lesion data.

  • voxel_tuples (list of tuples) – A list of tuples containing the voxel coordinates (x, y, z) of the lesions.

  • window_level (float) – The window level for image visualization.

  • window_width (float) – The window width for image visualization.

  • image_name (str) – The name of the image to be displayed in the plot.

Returns

None

ramac.preprocessing module

ramac.preprocessing.mask_air(image, air_threshold=-950)

Mask out air voxels using air_threhold.

Parameters

  • image (np.array) – Image to be preprocessed.

  • air_threshold (float, optional) – Threshold for air voxels. The default is -950.

Returns

masked_image – Processed image with air voxels removed.

Return type

np.array

ramac.registration module

ramac.registration.display_images(fixed_image_z, moving_image_z, fixed_npa, moving_npa)

Display images from the fixed and moving image stacks.

Parameters

  • fixed_image_z (int) – The index of the slice to be displayed from the fixed image stack.

  • moving_image_z (int) – The index of the slice to be displayed from the moving image stack.

  • fixed_npa (numpy.ndarray) – The numpy array representing the fixed image stack.

  • moving_npa (numpy.ndarray) – The numpy array representing the moving image stack.

Returns

None

ramac.registration.display_images_with_alpha(image_z, alpha, fixed, moving)

Display images with alpha blending between fixed and moving images.

Parameters

  • image_z (int) – The index of the slice to be displayed.

  • alpha (float) – The alpha blending parameter.

  • fixed (SimpleITK.Image) – The fixed image.

  • moving (SimpleITK.Image) – The moving image.

Returns

None

ramac.registration.end_plot()

Callback invoked when the EndEvent happens, do cleanup of data and figure.

Returns

None

ramac.registration.plot_values(registration_method)

Callback invoked when the IterationEvent happens, update our data and display new figure.

Parameters

registration_method – The registration method.

Returns

None

ramac.registration.registration_3d_rigid_gradient_descent(fixed_image, moving_image)

Perform 3D rigid registration using gradient descent optimization.

Parameters

  • fixed_image – SimpleITK.Image The fixed image to be registered.

  • moving_image – SimpleITK.Image The moving image to be registered.

Returns

tuple

A tuple containing the resampled moving image and the list of transforms applied.

Details:

This function performs 3D rigid registration between a fixed and a moving image using gradient descent optimization. It initializes the transformation parameters using the CenteredTransformInitializer with a similarity transformation. The registration process is driven by the correlation metric. Optimization is performed using the RegularStepGradientDescent optimizer with specified parameters. The function prints the optimizer progress at each iteration and outputs the transformed moving image.

ramac.registration.registration_3d_rigid_series(fixed_image, moving_image)

Perform 3D rigid registration using a series of steps.

Parameters

  • fixed_image – SimpleITK.Image The fixed image to be registered.

  • moving_image – SimpleITK.Image The moving image to be registered.

Returns

tuple

A tuple containing the resampled moving image and the list of transforms applied.

Details:

This function performs 3D rigid registration between a fixed and a moving image in a series of steps. It initializes the transformation parameters using the CenteredTransformInitializer with an Euler3DTransform. The registration method is driven by the MattesMutualInformation metric. Optimization is performed using gradient descent with specified parameters. Multi-resolution framework is used for optimization. The function prints the final metric value and optimizer’s stopping condition. It also returns the resampled moving image and the list of initial and final transforms applied.

ramac.registration.start_plot()

Callback invoked when the StartEvent happens, sets up our new data.

Returns

None

ramac.registration.update_multires_iterations()

Callback invoked when the sitkMultiResolutionIterationEvent happens, update the index into the metric_values list.

Returns

None

ramac.transform_coordinates module

ramac.transform_coordinates.create_transformed_dataframe(df_file, transform)

Create a new DataFrame with transformed coordinates.

Parameters

  • df_file (str) – The path to the CSV file containing the original lesion data.

  • transform (SimpleITK.Transform) – The transformation to apply to the coordinates.

Returns

A DataFrame containing the transformed lesion data.

Return type

pandas.DataFrame

ramac.transform_coordinates.read_lesion_csv(file_path)

Read lesion data from a CSV file into a DataFrame.

Parameters

file_path (str) – The path to the CSV file containing lesion data.

Returns

A DataFrame containing the lesion data.

Return type

pandas.DataFrame

ramac.transform_coordinates.transform_centroid(centroid, transform)

Apply a transformation to a given centroid.

Parameters

  • centroid (tuple or str) – The centroid coordinates as a tuple or string representation.

  • transform (SimpleITK.Transform) – The transformation to apply.

Returns

The transformed centroid coordinates.

Return type

tuple

ramac.transform_coordinates.transform_physical_to_index(image, df_file_or_df)

Transform physical coordinates to voxel indices using SimpleITK.

Parameters

  • image (SimpleITK.Image) – The image containing the spatial information.

  • df_file_or_df (str or pandas.DataFrame) – The path to the CSV file containing physical coordinates, or a DataFrame containing the physical coordinates directly.

Returns

DataFrame containing voxel indices.

Return type

pandas.DataFrame

ramac.utils module

ramac.utils.applied_transform(transform)

Applies a transformation and prints its parameters.

Parameters

transform – object The transformation object to be applied.

Returns

None

Prints:

Transformation Parameters: The parameters of the applied transformation.

ramac.utils.apply_rotation_and_translation(lesion_coords, rotation_matrix_x, translation)

Apply rotation and translation to lesion coordinates.

Parameters

  • lesion_coords (list of tuples) – List of lesion coordinates (x, y, z).

  • rotation_matrix_x (numpy.ndarray) – Rotation matrix for the x-axis.

  • #rotation_matrix_y (numpy.ndarray) – Rotation matrix for the y-axis.

  • translation (tuple) – The translation vector (z, y, x).

Returns

Transformed lesion coordinates.

Return type

list of tuples

ramac.utils.create_trim_dataframe(week)

Creates a trimmed DataFrame from the input DataFrame ‘week’.

This function splits the ‘Merge Centroid’ column of the input DataFrame ‘week’ into separate ‘x’, ‘y’, and ‘z’ columns and copies the ‘Updated Index’ column into a new column named ‘Index’.

Parameters

week (pandas.DataFrame) – The input DataFrame containing the data to be trimmed.

Returns

A new DataFrame containing the trimmed data, with columns ‘x’, ‘y’, ‘z’, and ‘Index’.

Return type

pandas.DataFrame

ramac.utils.insert_lesion(x, c, r)

Inserts a lesion into the given 3D array.

Parameters

  • x (np.ndarray) – The 3D array representing the phantom.

  • c (tuple) – The coordinates of the center of the lesion in the format (z, y, x).

  • r (float) – The radius of the lesion.

Returns

The modified phantom array with the lesion inserted.

Return type

np.ndarray

ramac.utils.list_to_dataframe(data_list)

Convert a list of tuples to a DataFrame.

Parameters

data_list (list) – List of tuples containing data.

Returns

DataFrame containing the data.

Return type

pandas.DataFrame

ramac.utils.numpy_array_to_sitk(x, spacing=(1.0, 1.0, 1.0), origin=(0.0, 0.0, 0.0))

Converts a NumPy array to a SimpleITK image format.

Parameters

  • x (np.ndarray) – The input NumPy array.

  • spacing (tuple, optional) – The spacing of the image voxels along each dimension. Defaults to (1., 1., 1.).

  • origin (tuple, optional) – The origin of the image in physical coordinates. Defaults to (0., 0., 0.).

Returns

The SimpleITK image representation of the input NumPy array.

Return type

SimpleITK.Image

ramac.utils.numpy_point_to_sitk(xyz, sitk_image)

Converts a tuple of numpy indices (xyz) to a SimpleITK point.

Parameters

  • xyz (tuple) – The tuple of integers representing the indices along each axis (x, y, z).

  • sitk_image (SimpleITK.Image) – The SimpleITK image from which the point is to be extracted.

Returns

The physical point corresponding to the given numpy indices.

Return type

SimpleITK.Point

ramac.utils.numpy_points_to_sitk(xyzs, sitk_image)

Converts a list of numpy indices (xyzs) to a list of SimpleITK points.

Parameters

  • xyzs (list) – A list of tuples, each representing the indices along each axis (x, y, z).

  • sitk_image (SimpleITK.Image) – The SimpleITK image from which the points are to be extracted.

Returns

A list of SimpleITK points corresponding to the given numpy indices.

Return type

list

ramac.utils.rotation_matrix(axis, theta)

Return the rotation matrix associated with counterclockwise rotation about the given axis by theta degrees.

Parameters

  • axis (list or numpy.ndarray) – The axis of rotation.

  • theta (float) – The angle of rotation in degrees.

Returns

The rotation matrix.

Return type

numpy.ndarray

ramac.utils.round_coordinates_to_integer(coordinates)

Round each coordinate in a list of tuples to the nearest integer.

Parameters

coordinates (list of tuples) – List containing tuples of coordinates.

Returns

List of tuples with each coordinate rounded to the nearest integer.

Return type

list of tuples

ramac.utils.save_lesion_coordinates(lesion_coords, lesion_index, filename)

Save lesion coordinates to a CSV file.

Parameters

  • lesion_coords (list of tuples) – List of lesion coordinates (x, y, z).

  • lesion_index (list of int) – List of lesion indices.

  • filename (str) – The filename for the CSV file.

Returns

None

ramac.utils.save_transformed_dataframe(transformed_df, output_file)

Save a DataFrame to a CSV file.

Parameters

  • transformed_df – DataFrame The DataFrame containing the transformed data.

  • output_file – str The path to the output CSV file.

Returns

None

Saves:

The transformed DataFrame to the specified CSV file without index.

ramac.utils.transform_phantom_np(phantom, rotation_angle, translation, axes=(1, 2))

Apply rotation and translation to the phantom.

Parameters

  • phantom (ndarray) – The input phantom.

  • rotation_angle (float) – The rotation angle in degrees.

  • translation (tuple) – The translation vector.

Returns

The transformed phantom.

Return type

ndarray

ramac.utils.voxel_tuples_from_dataframe(df)

Extract voxel coordinates as tuples from a DataFrame.

Parameters

df (pandas.DataFrame) – DataFrame containing voxel coordinates.

Returns

List of tuples containing voxel coordinates.

Return type

list