topostats.tracing.pruning#

Prune branches from skeletons.

Attributes#

LOGGER

Classes#

topostatsPrune

Prune spurious skeletal branches based on their length and/or height.

heightPruning

Pruning of branches based on height.

Functions#

prune_skeleton(→ numpy.typing.NDArray)

Pruning skeletons using different pruning methods.

_prune_method(→ collections.abc.Callable)

Determine which skeletonize method to use.

_prune_topostats(→ numpy.typing.NDArray)

Prune using the original TopoStats method.

order_branch_from_end(→ numpy.typing.NDArray)

Take a linear branch and orders its coordinates starting from a specific endpoint.

rm_nibs(skeleton)

Remove single pixel branches (nibs) not identified by nearest neighbour algorithms as there may be >2 neighbours.

local_area_sum(→ tuple)

Evaluate the local area around a point in a binary map.

Module Contents#

topostats.tracing.pruning.LOGGER#
topostats.tracing.pruning.prune_skeleton(image: numpy.typing.NDArray, skeleton: numpy.typing.NDArray, pixel_to_nm_scaling: float, **kwargs) → numpy.typing.NDArray[source]#

Pruning skeletons using different pruning methods.

This is a thin wrapper to the methods provided within the pruning classes below.

Parameters:

  • image (npt.NDArray) – Original image as 2D numpy array.

  • skeleton (npt.NDArray) – Skeleton to be pruned.

  • pixel_to_nm_scaling (float) – The pixel to nm scaling for pruning by length.

  • **kwargs – Pruning options passed to the respective method.

Returns:

An array of the skeleton with spurious branching artefacts removed.

Return type:

npt.NDArray

topostats.tracing.pruning._prune_method(image: numpy.typing.NDArray, skeleton: numpy.typing.NDArray, pixel_to_nm_scaling: float, **kwargs) → collections.abc.Callable[source]#

Determine which skeletonize method to use.

Parameters:

  • image (npt.NDArray) – Original image as 2D numpy array.

  • skeleton (npt.NDArray) – Skeleton to be pruned.

  • pixel_to_nm_scaling (float) – The pixel to nm scaling for pruning by length.

  • **kwargs – Pruning options passed to the respective method.

Returns:

Returns the function appropriate for the required skeletonizing method.

Return type:

Callable

Raises:

ValueError – Invalid method passed.

topostats.tracing.pruning._prune_topostats(img: numpy.typing.NDArray, skeleton: numpy.typing.NDArray, pixel_to_nm_scaling: float, **kwargs) → numpy.typing.NDArray[source]#

Prune using the original TopoStats method.

This is a modified version of the pubhlished Zhang method.

Parameters:

  • img (npt.NDArray) – Image used to find skeleton, may be original heights or binary mask.

  • skeleton (npt.NDArray) – Binary mask of the skeleton.

  • pixel_to_nm_scaling (float) – The pixel to nm scaling for pruning by length.

  • **kwargs – Pruning options passed to the topostatsPrune class.

Returns:

The skeleton with spurious branches removed.

Return type:

npt.NDArray

class topostats.tracing.pruning.topostatsPrune(img: numpy.typing.NDArray, skeleton: numpy.typing.NDArray, pixel_to_nm_scaling: float, max_length: float = None, height_threshold: float = None, method_values: str = None, method_outlier: str = None)[source]#

Prune spurious skeletal branches based on their length and/or height.

Contains all the functions used in the original TopoStats pruning code written by Joe Betton.

Parameters:

  • img (npt.NDArray) – Original image.

  • skeleton (npt.NDArray) – Skeleton to be pruned.

  • pixel_to_nm_scaling (float) – The pixel to nm scaling for pruning by length.

  • max_length (float) – Maximum length of the branch to prune in nanometres (nm).

  • height_threshold (float) – Absolute height value to remove branches below in nanometres (nm).

  • method_values (str) – Method for obtaining the height thresholding values. Options are ‘min’ (minimum value of the branch), ‘median’ (median value of the branch) or ‘mid’ (ordered branch middle coordinate value).

  • method_outlier (str) – Method for pruning brancvhes based on height. Options are ‘abs’ (below absolute value), ‘mean_abs’ (below the skeleton mean - absolute threshold) or ‘iqr’ (below 1.5 * inter-quartile range).

img#
skeleton#
pixel_to_nm_scaling#
max_length = None#
height_threshold = None#
method_values = None#
method_outlier = None#
prune_skeleton() → numpy.typing.NDArray[source]#

Prune skeleton by length and/or height.

If the class was initialised with both max_length is not None an d height_threshold is not None then length based pruning is performed prior to height based pruning.

Returns:

A pruned skeleton.

Return type:

npt.NDArray

_prune_by_length(single_skeleton: numpy.typing.NDArray, max_length: float) → numpy.typing.NDArray[source]#

Remove hanging branches from a skeleton by their length.

This is an iterative process as these are a persistent problem in the overall tracing process.

Parameters:

  • single_skeleton (npt.NDArray) – Binary array of the skeleton.

  • max_length (float) – Maximum length of the branch to prune in nanometers (nm).

Returns:

Pruned skeleton as binary array.

Return type:

npt.NDArray

static _find_branch_ends(coordinates: list) → list[source]#

Identify branch ends.

This is achieved by iterating through the coordinates and assessing the local pixel area. Ends have only one adjacent pixel.

Parameters:

coordinates (list) – List of x, y coordinates of a branch.

Returns:

List of x, y coordinates of the branch ends.

Return type:

list

class topostats.tracing.pruning.heightPruning(image: numpy.typing.NDArray, skeleton: numpy.typing.NDArray, max_length: float = None, height_threshold: float = None, method_values: str = None, method_outlier: str = None)[source]#

Pruning of branches based on height.

Parameters:

  • image (npt.NDArray) – Original image, typically the height data.

  • skeleton (npt.NDArray) – Skeleton to prune branches from.

  • max_length (float) – Maximum length of the branch to prune in nanometres (nm).

  • height_threshold (float) – Absolute height value to remove branches below in nanometers (nm).

  • method_values (str) – Method of obtaining the height thresholding values. Options are ‘min’ (minimum value of the branch), ‘median’ (median value of the branch) or ‘mid’ (ordered branch middle coordinate value).

  • method_outlier (str) – Method to prune branches based on height. Options are ‘abs’ (below absolute value), ‘mean_abs’ (below the skeleton mean - absolute threshold) or ‘iqr’ (below 1.5 * inter-quartile range).

image#
skeleton#
skeleton_convolved = None#
skeleton_branches = None#
skeleton_branches_labelled = None#
max_length = None#
height_threshold = None#
method_values = None#
method_outlier = None#
skeleton_pruned#
convolve_skeleton() → None[source]#

Convolve skeleton.

segment_skeleton() → None[source]#

Convolve skeleton and break into segments at nodes/junctions.

label_branches() → None[source]#

Label segmented branches.

_get_branch_mins(segments: numpy.typing.NDArray) → numpy.typing.NDArray[source]#

Collect the minimum height value of each individually labeled branch.

Parameters:

segments (npt.NDArray) – Integer labeled array matching the dimensions of the image.

Returns:

Array of minimum values of each branch index -1.

Return type:

npt.NDArray

_get_branch_medians(segments: numpy.typing.NDArray) → numpy.typing.NDArray[source]#

Collect the median height value of each labeled branch.

Parameters:

segments (npt.NDArray) – Integer labeled array matching the dimensions of the image.

Returns:

Array of median values of each branch index -1.

Return type:

npt.NDArray

_get_branch_middles(segments: numpy.typing.NDArray) → numpy.typing.NDArray[source]#

Collect the positionally ordered middle height value of each labeled branch.

Where the branch has an even amount of points, average the two middle heights.

Parameters:

segments (npt.NDArray) – Integer labeled array matching the dimensions of the image.

Returns:

Array of middle values of each branch.

Return type:

npt.NDArray

static _get_abs_thresh_idx(height_values: numpy.typing.NDArray, threshold: float | int) → numpy.typing.NDArray[source]#

Identify indices of labelled branches whose height values are less than a given threshold.

Parameters:

  • height_values (npt.NDArray) – Array of each branches heights.

  • threshold (float | int) – Threshold for heights.

Returns:

Branch indices which are less than threshold.

Return type:

npt.NDArray

static _get_mean_abs_thresh_idx(height_values: numpy.typing.NDArray, threshold: float | int, image: numpy.typing.NDArray, skeleton: numpy.typing.NDArray) → numpy.typing.NDArray[source]#

Identify indices of labelled branch whose height values are less than mean skeleton height - absolute threshold.

For DNA a threshold of 0.85nm (the depth of the major groove) would ideally remove all segments whose lowest point is < mean(height) - 0.85nm, i.e. 1.15nm.

Parameters:

  • height_values (npt.NDArray) – Array of branches heights.

  • threshold (float | int) – Threshold to be subtracted from mean heights.

  • image (npt.NDArray) – Original image of heights.

  • skeleton (npt.NDArray) – Binary array of skeleton used to identify heights from original image to use.

Returns:

Branch indices which are less than mean(height) - threshold.

Return type:

npt.NDArray

static _get_iqr_thresh_idx(image: numpy.typing.NDArray, segments: numpy.typing.NDArray) → numpy.typing.NDArray[source]#

Identify labelled branch indices whose heights are less than 1.5 x interquartile range of all heights.

Parameters:

  • image (npt.NDArray) – Original image with heights.

  • segments (npt.NDArray) – Array of skeleton branches.

Returns:

Branch indices where heights are < 1.5 * inter-quartile range.

Return type:

npt.NDArray

static check_skeleton_one_object(skeleton: numpy.typing.NDArray) → bool[source]#

Ensure that the skeleton hasn’t been broken up upon removing a segment.

Parameters:

skeleton (npt.NDArray) – 2D single pixel thick array.

Returns:

True or False depending on whether there is 1 or !1 objects.

Return type:

bool

filter_segments(segments: numpy.typing.NDArray) → numpy.typing.NDArray[source]#

Identify and remove segments of a skeleton based on the underlying image height.

Parameters:

segments (npt.NDArray) – A labelled 2D array of skeleton segments.

Returns:

The original skeleton without the segments identified by the height criteria.

Return type:

npt.NDArray

height_prune() → numpy.typing.NDArray[source]#

Identify and remove spurious branches (containing endpoints) using the underlying image height.

Returns:

A skeleton with outer branches removed by height.

Return type:

npt.NDArray

static _split_skeleton(skeleton: numpy.typing.NDArray) → numpy.typing.NDArray[source]#

Split the skeleton into branches by removing junctions/nodes and label branches.

Parameters:

skeleton (npt.NDArray) – Convolved skeleton to be split. This should have nodes labelled as 3, ends as 2 and all other points as 1.

Returns:

Removes the junctions (3) and returns all remaining sections as labelled segments.

Return type:

npt.NDArray

topostats.tracing.pruning.order_branch_from_end(nodeless: numpy.typing.NDArray, start: list, max_length: float = np.inf) → numpy.typing.NDArray[source]#

Take a linear branch and orders its coordinates starting from a specific endpoint.

NB - It may be possible to use np.lexsort() to order points, see topostats.measure.feret.sort_coords() for an example of how to sort by row or column coordinates, which end of the branch this is from probably doesn’t matter as one only wants to find the mid-point I think.

Parameters:

  • nodeless (npt.NDArray) – A 2D binary array where there are no crossing pixels.

  • start (list) – A coordinate to start closest to / at.

  • max_length (float, optional) – The maximum length to order along the branch, in pixels, by default np.inf.

Returns:

The input linear branch ordered from the start coordinate.

Return type:

npt.NDArray

topostats.tracing.pruning.rm_nibs(skeleton)[source]#

Remove single pixel branches (nibs) not identified by nearest neighbour algorithms as there may be >2 neighbours.

Parameters:

skeleton (npt.NDArray) – A single pixel thick trace.

Returns:

A skeleton with single pixel nibs removed.

Return type:

npt.NDArray

topostats.tracing.pruning.local_area_sum(img: numpy.typing.NDArray, point: list | tuple | numpy.typing.NDArray) → tuple[source]#

Evaluate the local area around a point in a binary map.

Parameters:

  • img (npt.NDArray) – Binary array of image.

  • point (list | tuple | npt.NDArray) – Coordinates of a point within the binary_map.

Returns:

Tuple consisting of an array values of the local coordinates around the point and the number of neighbours around the point.

Return type:

tuple