magmap.atlas.atlas_refiner module

Refine atlases in 3D.

magmap.atlas.atlas_refiner.aggr_smoothing_metrics(df_pxs)

Aggregate smoothing metrics from a data frame of raw stats by label.

Stats generally compare original and smoothed versions, but when stats of a single version, typically the smoothed version is given. Stats are weighted by the original volume.

Parameters:

df_pxs (pandas.DataFrame) – Data frame with raw stats by label.

Returns:

Data frame of aggregated stats.

Return type:

pandas.DataFrame

magmap.atlas.atlas_refiner.check_mirrorred(img_np, mirror_mult=1, axis=0)

Check whether a given image, typically a labels image, is symmetric.

Parameters:

• img_np (numpy.ndarray) – Numpy array of image, typically a labels image, where symmetry will be detected based on equality of two halves split by the image’s last dimension.

• mirror_mult (int) – Number by which to divide the 2nd half before checking for symmetry; defaults to 1. Typically a number used to generate the 2nd half when mirroring.

• axis (int) – Axis along which to check for symmetry; defaults to 0.

Returns:

Values equality, True if the sides are equal, and unique labels equality, True if the sides have equal sets of unique values.

Return type:

bool, bool

magmap.atlas.atlas_refiner.crop_to_orig(labels_img_np_orig, labels_img_np, crop)

Crop new labels to extent of original labels.

Parameters:

• labels_img_np_orig (np.ndarray) – Original labels image array.

• labels_img_np (np.ndarray) – Labels image array, which will be cropped in-place to labels_img_np_orig.

• crop (bool) – True to apply morphological opening to labels_img_np_orig before cropping.

magmap.atlas.atlas_refiner.extend_edge(region, region_ref, threshold, plane_region, planei, surr_size=0, smoothing_size=0, in_paint=False, edges=None, marker_erosion=0, marker_erosion_min=None, marker_erosion_use_min=False, wt_lat=0, save_steps=False, edge_bounds=None)

Recursively extend the nearest plane with labels based on the underlying atlas histology.

Labels in a given atlas may be incomplete, absent along the lateral edges. To fill in these missing labels, the last labeled plane will be used to extend labeling for all distinct structures in the histology (“reference” image). The given reference region will be thresholded to find distinct sub-regions, and each sub-region will be recursively extended to fill each successive lateral plane with labels from the prior plane resized to that of the reference region in the given plane.

This approach assumes that each nearer plane is the same size or smaller than the next farther plane is, such as the tapering edge of a specimen, since each subsequent plane will be within the bounds of the prior plane. The number of sub-regions to extend is set by the first plane, after which only the largest object within each sub-region will be followed. Labels will be cropped in this first plane to match the size of each corresponding reference region and resized to the size of the largest object in all subsequent planes.

To improve correspondence with the underlying histology, edge-aware reannotation can be applied. This reannotation is a 2D/3D implementation, where the edge map is generated in 3D, but the reannotation occurs in serial 2D, with each generated plane becoming the template for the next plane to give smooth transitions from plane to plane. During the erosion step, the labels are allowed to disappear to emulate their tapering off.

Parameters:

• region (np.ndarray) – Labels volume region, which will be extended along decreasing z-planes and updated in-place.

• region_ref (np.ndarray) – Corresponding reference (eg histology) region.

• threshold (int, float) – Threshold intensity for region_ref.

• plane_region (np.ndarray) – Labels 2D template that will be resized for current plane; if None, a template will be cropped from region at planei.

• planei (int) – Plane index.

• surr_size (int) – Structuring element size for dilating the labeled area that will be considered foreground in region_ref for finding regions to extend; defaults to 0 to not dilate.

• surr_size – Structuring element size for dilating the labeled area that will be considered foreground in region_ref for finding regions to extend; defaults to 0 to not dilate.

• smoothing_size (int) – Structuring element size for smooth_labels(); defaults to 0 to not smooth.

• in_paint (bool) – True to in-paint region_ref foreground not present in plane_region; defaults to False.

• edges (np.ndarray) – Array of edges for watershed-based reannotation. Typically of same size as region. Defaults to None to generate new edges from region_ref if marker_erosion is > 0.

• marker_erosion (int) – Structuring element size for label erosion to markers for watershed-based reannotation. Defaults to 0 to skip this reannotation.

• marker_erosion_min (int) – Minimum size of erosion filter passed to segmenter.labels_to_markers_erosion(); defaults to None.

• marker_erosion_use_min (bool) – Flag for using the minimum filter size if reached, passed to segmenter.labels_to_markers_erosion(); defaults to False.

• save_steps (bool) – True to output intermediate steps as images, saving to the extension set in config.savefig; defaults to False.

• wt_lat (float) – Weight lateral planes more heavily by reducing the weight of medial planes’ erosion filter sizes by this fraction. Defaults to 0 to weight all planes equally. 1 causes the most medial plane to undergo no erosion, with erosion weight increasing linearly to 1 at the most lateral planes.

• edge_bounds (list[int]) – Sequence of indices of lateral first, last planes; defaults to None to determine based on edge map.

magmap.atlas.atlas_refiner.find_labels_lost(label_ids_orig, label_ids, label_img_np_orig=None)

Find labels lost and optionally the size of each label.

Parameters:

• label_ids_orig (List[int]) – Sequence of original label IDs.

• label_ids (List[int]) – Sequence of new label IDs.

• label_img_np_orig (np.ndarray) – Original labels image array to show the size of lost regions; defaults to None.

Returns:

Sequence of missing labels.

Return type:

List[int]

magmap.atlas.atlas_refiner.find_symmetric_axis(img_np, mirror_mult=1)

Find the axis along which the image is symmetric.

Parameters:

• img_np (np.ndarray) – Array to check for symmetry.

• mirror_mult (int) – Number by which to divide the 2nd half before checking for symmetry; defaults to 1. Typically a number used to generate the 2nd half when mirroring.

Returns:

The axis that is symmetric, or -1 if no symmetry is found.

Return type:

int

magmap.atlas.atlas_refiner.import_atlas(atlas_dir, show=True, prefix=None)

Import atlas from the given directory.

Process the atlas according to the register settings specified at :attr:config.register_settings.

The imported atlas will be saved to a directory of the same path as atlas_dir except with _import appended to the end. DSC will be calculated and saved as a CSV file in this directory as well.

Parameters:

• atlas_dir (str) – Path to atlas directory.

• show (bool, default: True) – True to show the imported atlas. Only supported for SimpleITK.

• prefix (Optional[str], default: None) – Output path; defaults to None to ignore. If ends with a file separator,``atlas_dir`` will still be used for the output filename; otherwise, the basename will be used for this filename.

magmap.atlas.atlas_refiner.label_smoothing_metric(orig_img_np, smoothed_img_np, filter_size=None, spacing=None)

Measure degree of appropriate smoothing, defined as smoothing that retains the general shape and placement of the region.

Compare the difference in compactness before and after the smoothing algorithm, termed “compaction,” while penalizing inappropriate smoothing, the smoothed volume lying outside of the original broad volume, termed “displacement.”

Parameters:

• orig_img_np – Unsmoothed labels image as Numpy array.

• smoothed_img_np – Smoothed labels image as Numpy array, which should be of the same shape as original_img_np.

• filter_size (float) – Structuring element size for smoothing, used here only to include in output data frame; defaults to None.

• spacing (list[float]) – Sequence of voxel spacing in same order as for img_np; defaults to None.

Returns:

Tuple of a data frame of the smoothing metrics and another data frame of the raw metric components.

magmap.atlas.atlas_refiner.make_labels_fg(labels_sitk)

Make a labels foreground image.

Parameters:

labels_sitk (Union[Image, itkTemplate]) – Labels image where 0 = background, and all other values are considered foreground.

Return type:

Union[Image, itkTemplate]

Returns:

Labels foreground image.

magmap.atlas.atlas_refiner.match_atlas_labels(img_atlas, img_labels, metrics=None)

Apply register profile settings to labels and match atlas image accordingly.

Parameters:

• img_atlas (Union[Image, itkTemplate]) – Reference image, such as histology.

• img_labels (Union[Image, itkTemplate]) – Labels image.

• metrics (Optional[Dict[AtlasMetrics, Union[float, Sequence[float]]]], default: None) – Dictionary of metrics. If None, metrics will not be measured.

Returns:

• img_atlas: the updated atlas

• img_labels: the updated labels

• df_sm: a data frame of smoothing stats, or None if smoothing was not performed

• df_sm_raw: a data frame of raw smoothing stats, or None if smoothing was not performed

Return type:

Tuple of

magmap.atlas.atlas_refiner.measure_atlas_refinement(metrics, img_atlas, img_labels, atlas_profile, path=None)

Parameters:

• metrics (Dict[Enum, List]) – Dictionary of metric names to values, which will be modified in-place.

• img_atlas (Image) – Atlas intensity image.

• img_labels (Image) – Atlas annotation image.

• atlas_profile (AtlasProfile) – Atlas profile.

• path (Optional[str], default: None) – Output path; defaults to None to not save.

Return type:

DataFrame

Returns:

Pandas data frame of metrics.

magmap.atlas.atlas_refiner.measure_overlap(img1, img2, thresh_img1=None, thresh_img2=None, add_to_img1_mask=None, return_masks=False)

Measure the Dice Similarity Coefficient between two intensity images.

Calculdate the DSC between the foreground of two images.

Parameters:

• img1 (Union[Image, itkTemplate, ndarray]) – Intensity image. The image type (itk.Image or sitk.Image) will determine which library is used.

• img2 (Union[Image, itkTemplate, ndarray]) – Intensity mage to compare.

• thresh_img1 (Optional[float], default: None) – Threshold to determine the foreground of img1; defaults to None to determine by a mean threshold.

• thresh_img2 (Optional[float], default: None) – Threshold to determine the foreground of img2; defaults to None to determine by a mean threshold.

• add_to_img1_mask (Optional[ndarray], default: None) – Boolean mask to add foreground mask of img1; defaults to None. Useful to treat as foreground regions that would be thresholded as background but included in labels.

• return_masks (bool, default: False) – True to return the thresholded, mask images used for the overlap calculate; defaults to False.

Return type:

Union[float, Tuple[float, Union[Image, itkTemplate, ndarray], ndarray]]

Returns:

The DSC of the foreground of the two given images, or np.nan if the DSC cannot be computed. If`return_masks`` is True, also returns the masked images as NumPy arrays.

magmap.atlas.atlas_refiner.measure_overlap_combined_labels(base_img, labels_img, add_lbls=None, return_masks=False)

Measures the overlap of a combined labels images to another image

Should be 1.0 by definition when using labels_img to curate another image.

Parameters:

• base_img (Union[Image, itkTemplate]) – Base image.

• labels_img (Union[Image, itkTemplate]) – Labels image, where all non-zero values will be treated as foreground.

• add_lbls (Optional[Sequence[Tuple[int, int]]], default: None) – Sequence of labels in labels_img to add to the mask for base_img.

• return_masks (bool, default: False) – True to return the thresholded, mask images used for the overlap calculate.

Return type:

float

Returns:

Dice Similarity Coefficient from measure_overlap().

magmap.atlas.atlas_refiner.measure_overlap_labels(img1, img2)

Measure the mean Dice Similarity Coefficient between two labeled images.

Parameters:

• img1 (Union[Image, itkTemplate]) – Labels image 1.

• img2 (Union[Image, itkTemplate]) – Labels image 2.

Return type:

float

Returns:

The mean label-by-label DSC of the two given images.

magmap.atlas.atlas_refiner.mirror_planes(img_np, start, mirror_mult=1, resize=True, start_dup=None, rand_dup=None, check_equality=False)

Mirror image across its sagittal midline.

Parameters:

• img – Labels image in Numpy format, which will be edited directly unless resize is True.

• start – Starting index at which to begin mirroring, inclusive.

• mirror_mult (default: 1) – Multiplier for mirrored portion of image, such as -1 when creating a labels map with one side distinct from the other; defaults to 1.

• resize (default: True) – True if the image should be resized to be symmetric in size across start; defaults to True.

• start_dup (default: None) – Fraction at which to start duplicating planes before mirroring, which may be useful for atlases where entired labeled regions are past midline, where duplication of a few atlas planes may simply expand rather than duplicating structures; defaults to None.

• rand_dup (default: None) – Multiplier for randomizer to choose duplicate planes from a random selection within this given range prior to start_dup. Defaults to None, in which case the plane just prior to the duplication starting plane will simply be duplicated throughout the region.

• check_equality (default: False) – True to check equality from one half to the other along axis 0; defaults to False.

Returns:

The mirrored image in Numpy format.

magmap.atlas.atlas_refiner.smooth_labels(labels_img_np, filter_size=3, mode=None, metrics=False, spacing=None)

Smooth each label within labels annotation image.

Labels images created in one orthogonal direction may have ragged, high-frequency edges when viewing in the other orthogonal directions. Smooth these edges by applying a filter to each label.

Parameters:

• labels_img_np (ndarray) – Labels image as a Numpy array.

• filter_size (int, default: 3) – Structuring element or kernel size; defaults to 3.

• mode (Optional[bool], default: None) – One of :attr:config.SmoothingModes, where opening applies a morphological opening filter unless the size is severely reduced, in which case a closing filter is applied instead; gaussian applies a Gaussian blur; and closing applies a closing filter only.

• metrics (bool, default: False) – True to measure smoothing metrics by label; defaults to False.

• spacing (Optional[Sequence[float]], default: None) – Sequence of labels_img_np spacing in z, y, x for metrics, only used when metrics is True; defaults to False.

Return type:

Tuple[Optional[DataFrame], Optional[DataFrame]]

Returns:

Data frams of the aggregated smoothing metrics weighted by volume and individual label metrics, or None for each if metrics is False.

magmap.atlas.atlas_refiner.transpose_img(img_sitk, plane=None, rotate=None, rotate_deg=None, target_size=None, target_size_res=None, flip=None, order=None)

Transpose an image to a different plane or rotation.

Supports the ROTATE and FLIP settings in magmap.settings.config.transform for additional transformations.

Parameters:

• img_sitk (Image) – Image in SimpleITK format.

• plane (Optional[str], default: None) – One of magmap.settings.config.PLANES, specifying the planar orientation in which to transpose the image. The current orientation is taken to be “xy”. Defaults to None, in which case the value from magmap.settings.config.plane will be taken.

• rotate (Optional[int], default: None) – Number of times to rotate by 90 degrees; defaults to None, in which case the value will be automatically determined based on config.transform and plane.

• rotate_deg (Optional[Sequence[Dict[str, Any]]], default: None) – Rotations by arbitrary number of degrees. Given as a sequence of dicts with args for magmap.cv_nd.rotate_nd(). Defaults to None.

• target_size (Union[float, Sequence[int], None], default: None) – Size of target in z, y, x order, or a single rescaling factor. Defaults to None.

• target_size_res (Union[float, Sequence[int], None], default: None) – Same as target_size, but applied to the image resolutions instead of changing the image itself. Defaults to None.

• flip (Union[int, Sequence[int], None], default: None) – Axis or sequence of axes to flip after transposition. Defaults to None, where it will be based on plane.

• order (Optional[int], default: None) – Spline interpolation order; defaults to None.

Return type:

Image

Returns:

The transposed image. If the original image will undergo no transformations, img_sitk is simply returned.

magmap.atlas.atlas_refiner.truncate_labels(img_np, x_frac=None, y_frac=None, z_frac=None)

Truncate image by zero-ing out pixels outside of given bounds.

Parameters:

• img_np – 3D image array in Numpy format.

• x_frac (default: None) – 2D tuple of (x_start, x_end), given as fractions of the image. Defaults to None, in which case the full image in that direction will be preserved.

• y_frac (default: None) – Same as x_frac but for y-axis.

• z_frac (default: None) – Same as x_frac but for z-axis.

Returns:

The truncated image.