magmap.stats.vols module

Measure volumes and densities by regions.

Intended to be higher-level, relatively atlas-agnostic measurements.

class magmap.stats.vols.LabelMetrics(value)

Bases: Enum

An enumeration.

CoefVarIntens = 32
CoefVarNuc = 33
Compactness = 35
Density = 8
DensityIntens = 9
Dist = 31
EdgeDistMean = 30
EdgeDistSum = 29
EdgeSize = 28
EntropyIntensity = 23
HighIntensity = 22
Intensity = 6
LowIntensity = 21
MeanIntensity = 19
MeanNuclei = 26
MedIntensity = 20
NucClusLarg = 42
NucClusNoise = 41
NucCluster = 40
NucDSC = 37
NucOut = 39
Nuclei = 7
RegDensityMean = 12
RegNucMean = 11
RegVolMean = 10
Region = 1
SurfaceArea = 34
VarIntensDiff = 25
VarIntensIn = 17
VarIntensMatch = 24
VarIntensOut = 18
VarIntensity = 16
VarNucIn = 14
VarNucMatch = 27
VarNucOut = 15
VarNuclei = 13
VolAlt = 3
VolAltPx = 5
VolDSC = 36
VolOut = 38
VolPx = 4
Volume = 2
class magmap.stats.vols.LabelToEdge[source]

Bases: SharedArrsContainer

Convert a labels image to its edge

Provides class methods for encapsulation and shared arrays to use in multiprocessing without requirement for global variables.

classmethod find_label_edge(label_id)[source]

Convert a label into just its border.

Parameters:

label_id (int) – Integer of the label to extract from labels_img_np.

Returns:

  • label ID: the label ID

  • slices: list of slices defining the location of the ROI where the edges can be found

  • borders: ROI as a volume mask defining where the edges exist

Return type:

Tuple of

footprint: Sequence[int] = None

Structuring element footprint for generating the edge, where larger footprints given thicker edges.

labels_img: ndarray = None

Labels image.

classmethod make_labels_edge(labels_img_np)[source]

Convert labels image into label borders image.

The atlas is assumed to be a sample (eg microscopy) image on which an edge-detection filter will be applied.

Parameters:

labels_img_np (ndarray) – Image as a Numpy array, assumed to be an annotated image whose edges will be found by obtaining the borders of all annotations.

Return type:

ndarray

Returns:

Binary image array the same shape as labels_img_np with labels reduced to their corresponding borders.

class magmap.stats.vols.MeasureLabel[source]

Bases: SharedArrsContainer

Measure metrics within image labels in a way that allows multiprocessing without global variables.

All images should be of the same shape. If :attr:df is available, it will be used in place of underlying images. Typically this data frame contains metrics for labels only at the lowest level, such as drawn or non-overlapping labels. These labels can then be used to aggregate values through summation or weighted means to generate metrics for superseding labels that contains these individual labels.

Variables:

  • atlas_img_np – Sample image as a Numpy array.

  • labels_img_np – Integer labels image as a Numpy array.

  • labels_edge – Numpy array of labels reduced to their edges.

  • dist_to_orig – Distance map of labels to edges, with intensity values in the same placement as in labels_edge.

  • heat_map – Numpy array as a density map.

  • blobs (np.ndarray) – 2D array of blobs such as nuclei in the format, [[z, y, x, label_id, ...], ...]. Defaults to None.

  • subseg – Integer sub-segmentations labels image as Numpy array.

  • df – Pandas data frame with a row for each sub-region.

atlas_img_np = None
blobs = None
df = None
dist_to_orig = None
heat_map = None
classmethod label_metrics(label_id, extra_metrics=None, df=None, spacing=None)[source]

Calculate metrics for a given label or set of labels.

Wrapper to call :func:measure_variation, :func:measure_variation, and :func:measure_edge_dist.

Parameters:

  • label_id (Union[int, Sequence[int]]) – Integer of the label or sequence of multiple labels in :attr:labels_img_np for which to measure variation.

  • extra_metrics (Optional[List[MetricGroups]], default: None) – Sequence of additional metric groups to measure; defaults to None.

  • df (Optional[DataFrame], default: None) – Pandas data frame with a row for each sub-region; defaults to None.

  • spacing (Optional[Sequence[float]], default: None) – Sequence of image spacing for each pixel in the images; defaults to None.

Return type:

Tuple[int, Dict]

Returns:

Tuple of the given label ID, intensity variation, number of pixels in the label, density variation, number of blobs, sum edge distances, mean of edge distances, and number of pixels in the label edge.

labels_edge = None
labels_img_np = None
labels_interior = None
classmethod measure_counts(label_ids)[source]

Measure the distance between edge images.

If :attr:df is available, it will be used to sum values from labels in label_ids found in the data frame rather than re-measuring values from images.

Parameters:

label_ids – Integer of the label or sequence of multiple labels in :attr:labels_img_np for which to measure variation.

Returns:

Tuple of the given label ID and a dictionary of metrics. The metrics are NaN if the label size is 0.

classmethod measure_edge_dist(label_ids)[source]

Measure the distance between edge images.

If :attr:df is available, it will be used to calculated a sum from edge distance sum or weighted averages from edge distance mean values from labels in label_ids found in the data frame rather than re-measuring values from images.

Parameters:

label_ids – Integer of the label or sequence of multiple labels in :attr:labels_img_np for which to measure variation.

Returns:

Tuple of the given label ID and dictionary of metrics. The metrics are NaN if the label size is 0.

classmethod measure_point_cloud(label_ids)[source]

Measure point cloud statistics such as those from nuclei.

Assumes that the class attribute blobs is available.

Parameters:

label_ids – Integer of the label or sequence of multiple labels in :attr:labels_img_np for which to measure variation.

Returns:

Tuple of the given label ID and dictionary of metrics. The metrics are NaN if the label size is 0.

classmethod measure_shapes(label_ids)[source]

Measure label shapes.

Labels will be measured even if :attr:df is available to account for the global shape rather than using weighted-averages.

Parameters:

label_ids – Integer of the label or sequence of multiple labels in :attr:labels_img_np for which to measure shapes.

Returns:

Tuple of the given label ID and a dictionary of metrics.

classmethod measure_variation(label_ids)[source]

Measure the variation in underlying atlas intensity.

Variation is measured by standard deviation of atlas intensity and, if :attr:heat_map is available, that of the blob density.

If :attr:df is available, it will be used to calculated weighted averages from labels in label_ids found in the data frame rather than re-measuring values from images.

Parameters:

label_ids – Integer of the label or sequence of multiple labels in :attr:labels_img_np for which to measure variation.

Returns:

Tuple of the given label ID and a dictionary a metrics. The metrics are NaN if the label size is 0.

classmethod region_props(region, metrics, keys)[source]

Measure properties for a region and add to a dictionary.

Parameters:

  • region – Region to measure, which can be a flattened array.

  • metrics – Dictionary to store metrics.

  • keys – Sequence of keys corresponding to standard deviation, median, and Shannon Entropy measurements.

classmethod set_data(atlas_img_np, labels_img_np, labels_edge=None, dist_to_orig=None, labels_interior=None, heat_map=None, blobs=None, subseg=None, df=None, spacing=None)[source]

Set the images and data frame.

spacing = None
subseg = None
class magmap.stats.vols.MeasureLabelOverlap[source]

Bases: object

Measure metrics comparing two versions of image labels in a way that allows multiprocessing without global variables.

All images should be of the same shape. If :attr:df is available, it will be used in place of underlying images. Typically this data frame contains metrics for labels only at the lowest level, such as drawn or non-overlapping labels. These labels can then be used to aggregate values through summation or weighted means to generate metrics for superseding labels that contains these individual labels.

Variables:

  • labels_imgs – Sequence of integer labels image as Numpy arrays.

  • heat_map – Numpy array as a density map; defaults to None to ignore density measurements.

  • df – Pandas data frame with a row for each sub-region.

df = None
heat_map = None
labels_imgs = None
classmethod measure_overlap(label_ids)[source]

Measure the overlap between image labels.

If :attr:df is available, it will be used to sum values from labels in label_ids found in the data frame rather than re-measuring values from images.

Parameters:

label_ids – Integer of the label or sequence of multiple labels in :attr:labels_img_np for which to measure variation.

Returns:

Tuple of the given label ID and a dictionary of metrics. The metrics are NaN if the label size is 0.

classmethod set_data(labels_imgs, heat_map=None, df=None)[source]

Set the images and data frame.

class magmap.stats.vols.MetricCombos(value)[source]

Bases: Enum

Combinations of metrics.

Each combination should be a tuple of combination name, a tuple of metric Enums, and a function to use for aggregation applied across colums to give a new metric value for each row.

COEFVAR_INTENS = ('CoefVarIntensity', (LabelMetrics.VarIntensity, LabelMetrics.MeanIntensity), <function _coef_var>)
COEFVAR_NUC = ('CoefVarNuclei', (LabelMetrics.VarNuclei, LabelMetrics.MeanNuclei), <function _coef_var>)
HOMOGENEITY = ('Homogeneity', (LabelMetrics.VarIntensity, LabelMetrics.EdgeDistSum, LabelMetrics.VarNuclei), <function MetricCombos.<lambda>>)
magmap.stats.vols.get_metric_weight_col(stat)[source]

Get the weighting column for a given metric.

Parameters:

stat (str) – The metric for which to find the appropriate weighting metric.

Returns:

The name of the corresponding weighting metric as a string.

magmap.stats.vols.get_single_label(label_id)[source]

Get an ID as a single element.

Parameters:

label_id – Single ID or sequence of IDs.

Returns:

The first elements if label_id is a sequence, or the label_id itself if not.

magmap.stats.vols.labels_distance(labels_img1, labels_img2, spacing=None, out_path=None, name=None)[source]

Measure distances between corresponding labels in two images.

Assumes that a 0 is background and will be skipped.

Parameters:

  • labels_img1 (ndarray) – Labels image 1.

  • labels_img2 (ndarray) – Labels image 2. Does not have to be of the same shape as labels_img, but assumed to have the same origin/offset and spacing as distances are based on centroid coordinates of the corresponding labels.

  • spacing (Optional[Sequence[float]], default: None) – Spacing/scaling in z,y,x; defaults to None.

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

  • name (Optional[str], default: None) – Sample name; defaults to None.

Return type:

DataFrame

Returns:

Data frame of output metrics.

magmap.stats.vols.map_meas_to_labels(labels_img, df, meas, fn_avg, skip_nans=False, reverse=False, col_wt=None)[source]

Generate a map of a given measurement on a labels image.

The intensity values of labels will be replaced by the given metric of the chosen measurement, such as the mean of the densities. If multiple conditions exist, the difference of metrics for the first two conditions will be taken under the assumption that the values for each condition are in matching order.

Parameters:

  • labels_img (ndarray) – Labels image as a Numpy array in x,y,z.

  • df (DataFrame) – Pandas data frame with measurements by regions corresponding to that of labels_img.

  • meas (str) – Name of column in df from which to extract measurements.

  • fn_avg (Callable[[Sequence], float]) – Function to apply to the column for each region. If None, df is assumed to already contain statistics generated from the clrstats R package, which will be extracted directly.

  • skip_nans (bool, default: False) – True to skip any region with NaNs, leaving 0 instead; defaults to False to allow NaNs in resulting image. Some applications may not be able to read NaNs, so this parameter allows giving a neutral value instead.

  • reverse (bool, default: False) – Reverse the order of sorted conditions when generating stats by fn_avg to compare conditions; defaults to False.

  • col_wt (Optional[str], default: None) – Name of column to use for weighting, where the magnitude of meas will be adjusted as fractions of the max value in this weighting column for labels found in labels_img; defaults to None.

Return type:

Optional[ndarray]

Retunrs:

A map of averages for the given measurement as an image of the same shape as labels_img of float data type, or None if no values for meas are found.

magmap.stats.vols.measure_labels_metrics(atlas_img_np, labels_img_np, labels_edge, dist_to_orig, labels_interior=None, heat_map=None, blobs=None, subseg=None, spacing=None, unit_factor=None, combine_sides=True, label_ids=None, grouping={}, df=None, extra_metrics=None)[source]

Compute metrics such as variation and distances within regions based on maps corresponding to labels image.

Parameters:

  • atlas_img_np – Atlas or sample image as a Numpy array.

  • labels_img_np – Integer labels image as a Numpy array.

  • labels_edge – Numpy array of labels reduced to their edges.

  • dist_to_orig – Distance map of labels to edges, with intensity values in the same placement as in labels_edge.

  • labels_interior (default: None) – Numpy array of labels eroded to interior region.

  • heat_map (default: None) – Numpy array as a density map; defaults to None to ignore density measurements.

  • blobs (np.ndarray) – 2D array of blobs; defaults to None.

  • subseg (default: None) – Integer sub-segmentations labels image as Numpy array; defaults to None to ignore label sub-divisions.

  • spacing (default: None) – Sequence of image spacing for each pixel in the images.

  • unit_factor (default: None) – Unit factor conversion; defaults to None. Eg use 1000 to convert from um to mm.

  • combine_sides (default: True) – True to combine corresponding labels from opposite sides of the sample; defaults to True. Corresponding labels are assumed to have the same absolute numerical number and differ only in signage. May be False if combining by passing both pos/neg labels in label_ids.

  • label_ids (default: None) – Sequence of label IDs to include. Defaults to None, in which case the labels will be taken from unique values in labels_img_np.

  • grouping (default: {}) – Dictionary of sample grouping metadata, where each entry will be added as a separate column. Defaults to an empty dictionary.

  • df (default: None) – Data frame with rows for all drawn labels to pool into parent labels instead of re-measuring stats for all children of each parent; defaults to None.

  • extra_metrics (List[config.MetricGroups]) – List of enums specifying additional stats; defaults to None.

Returns:

Pandas data frame of the regions and weighted means for the metrics.

magmap.stats.vols.measure_labels_overlap(labels_imgs, heat_map=None, spacing=None, unit_factor=None, combine_sides=True, label_ids=None, grouping={}, df=None)[source]

Compute metrics comparing two version of atlas labels.

Parameters:

  • labels_imgs – Sequence of integer labels image as Numpy arrays.

  • heat_map (default: None) – Numpy array as a density map; defaults to None to ignore density measurements.

  • spacing (default: None) – Sequence of image spacing for each pixel in the images.

  • unit_factor (default: None) – Unit factor conversion; defaults to None. Eg use 1000 to convert from um to mm.

  • combine_sides (default: True) – True to combine corresponding labels from opposite sides of the sample; defaults to True. Corresponding labels are assumed to have the same absolute numerical number and differ only in signage. May be False if combining by passing both pos/neg labels in label_ids.

  • label_ids (default: None) – Sequence of label IDs to include. Defaults to None, in which case the labels will be taken from unique values in labels_img_np.

  • grouping (default: {}) – Dictionary of sample grouping metadata, where each entry will be added as a separate column. Defaults to an empty dictionary.

  • df (default: None) – Data frame with rows for all drawn labels to pool into parent labels instead of re-measuring stats for all children of each parent; defaults to None.

Returns:

Pandas data frame of the regions and weighted means for the metrics.

Return type:

pd.DataFrame