topostats.tracing.ordered_tracing#

Order single pixel skeletons with or without NodeStats Statistics.

Attributes#

LOGGER

Classes#

OrderedTraceNodestats

Order single pixel thick skeleton coordinates via NodeStats results.

OrderedTraceTopostats

Order single pixel thick skeleton coordinates via TopoStats.

Functions#

linear_or_circular(→ bool)

Determine whether the molecule is circular or linear via >1 points in the local start area.

ordered_trace_mask(→ numpy.typing.NDArray)

Obtain a mask of the trace coordinates with each trace pixel.

ordered_tracing_image(→ tuple[dict, pandas.DataFrame, ...)

Run ordered tracing for an entire image of >=1 grains.

Module Contents#

topostats.tracing.ordered_tracing.LOGGER#
class topostats.tracing.ordered_tracing.OrderedTraceNodestats(image: numpy.typing.NDArray, nodestats_dict: dict, skeleton: numpy.typing.NDArray, filename: str)[source]#

Order single pixel thick skeleton coordinates via NodeStats results.

Parameters:

  • image (npt.NDArray) – A cropped image array.

  • nodestats_dict (dict) – The nodestats results for a specific grain.

  • skeleton (npt.NDArray) – The pruned skeleton mask array.

  • filename (str) – The image filename (for logging purposes).

image#
nodestats_dict#
filename#
skeleton#
grain_tracing_stats#
mol_tracing_stats#
images#
profiles#
img_idx_to_node#
ordered_coordinates = []#
compile_trace(reverse_min_conf_crossing: bool = False) → tuple[list, numpy.typing.NDArray][source]#

Obtain the trace and diagnostic crossing trace and molecule trace images.

This function uses the branches and full-width half-maximums (FWHMs) identified in the node_stats dictionary to create a continuous trace of the molecule.

Parameters:

reverse_min_conf_crossing (bool) – Whether to reverse the stacking order of the lowest confidence crossing in the trace.

Returns:

A list of each complete path’s ordered coordinates, and labeled crossing image array.

Return type:

tuple[list, npt.NDArray]

compile_images(coord_trace: list, cross_add: numpy.typing.NDArray, crossing_coords: list, fwhms: list) → None[source]#

Obtain all the diagnostic images based on the produced traces, and values.

Crossing coords and fwhms are used as arguments as reversing the minimum confidence can modify these.

Parameters:

  • coord_trace (list) – List of N molecule objects containing 2xM arrays of X, Y coordinates.

  • cross_add (npt.NDArray) – A labelled array with segments of the ordered trace.

  • crossing_coords (list) – A list of I nodes objects containing 2xJ arrays of X, Y coordinates for each crossing branch.

  • fwhms (list) – A list of I nodes objects containing FWHM values for each crossing branch.

static remove_common_values(ordered_array: numpy.typing.NDArray, common_value_check_array: numpy.typing.NDArray, retain: list = ()) → numpy.array[source]#

Remove common values in common_value_check_array from ordered_array while retaining specified coordinates.

Parameters:

  • ordered_array (npt.NDArray) – Coordinate array to remove / retain values from. Will retain its order.

  • common_value_check_array (npt.NDArray) – Coordinate array containing any common values to be removed from ordered_array.

  • retain (list, optional) – List of possible coordinates to keep, by default ().

Returns:

Unique ordered_array values and retained coordinates. Retains the order of ordered_array.

Return type:

np.array

get_topology(nxyz: numpy.typing.NDArray) → list[source]#

Obtain a topological classification from ordered XYZ coordinates.

Parameters:

nxyz (npt.NDArray) – A 4xN array of the order index (n), x, y and pseudo z coordinates.

Returns:

Topology(s) of the provided traced coordinates.

Return type:

list

trace(ordered_segment_coords: list, both_img: numpy.typing.NDArray, zs: numpy.typing.NDArray, n: int = 100) → list[source]#

Obtain an ordered trace of each complete path.

Here a ‘complete path’ means following and removing connected segments until there are no more segments to follow.

Parameters:

  • ordered_segment_coords (list) – Ordered coordinates of each labeled segment in ‘both_img’.

  • both_img (npt.NDArray) – A skeletonised labeled image of each path segment.

  • zs (npt.NDArray) – Array of pseudo heights of the traces. -1 is lowest, 0 is skeleton, then ascending integers for levels of overs.

  • n (int) – The number of points to use for the simplified traces.

Returns:

Ordered trace coordinates of each complete path.

Return type:

list

static reduce_rows(array: numpy.typing.NDArray, n: int = 300) → numpy.typing.NDArray[source]#

Reduce the number of rows in the array to n, keeping the first and last indexes.

Parameters:

  • array (npt.NDArray) – An array to reduce the number of rows in.

  • n (int, optional) – The number of indexes in the array to keep, by default 300.

Returns:

The array reduced to only n + 2 elements, or if shorter, the same array.

Return type:

npt.NDArray

static get_trace_segment(remaining_img: numpy.typing.NDArray, ordered_segment_coords: list, coord_idx: int) → numpy.typing.NDArray[source]#

Return an ordered segment at the end of the current one.

Check the branch of given index to see if it contains an endpoint. If it does, the segment coordinates will be returned starting from the endpoint.

Parameters:

  • remaining_img (npt.NDArray) – A 2D array representing an image composed of connected segments of different integers.

  • ordered_segment_coords (list) – A list of 2xN coordinates representing each segment.

  • coord_idx (int) – The index of the current segment to look at. There is an index mismatch between the remaining_img and ordered_segment_coords by -1.

Returns:

2xN array of coordinates representing a skeletonised ordered trace segment.

Return type:

npt.NDArray

static order_from_end(last_segment_coord: numpy.typing.NDArray, current_segment: numpy.typing.NDArray) → numpy.typing.NDArray[source]#

Order the current segment to follow from the end of the previous one.

Parameters:

  • last_segment_coord (npt.NDArray) – X and Y coordinates of the end of the last segment.

  • current_segment (npt.NDArray) – A 2xN array of coordinates of the current segment to order.

Returns:

  • npt.NDArray – The current segment orientated to follow on from the last.

  • bool – Whether the order has been flipped.

get_over_under_img(coord_trace: list, fwhms: list, crossing_coords: list) → numpy.typing.NDArray[source]#

Obtain a labelled image according to the main trace (=1), under (=2), over (=3).

Parameters:

  • coord_trace (list) – Ordered coordinate trace of each molecule.

  • fwhms (list) – List of full-width half-maximums (FWHMs) for each crossing in the trace.

  • crossing_coords (list) – The crossing coordinates of each branch crossing.

Returns:

2D crossing order labelled image.

Return type:

npt.NDArray

get_mols_img(coord_trace: list, fwhms: list, crossing_coords: list) → numpy.typing.NDArray[source]#

Obtain a labelled image according to each molecule traced N=3 -> n=1,2,3.

Parameters:

  • coord_trace (list) – Ordered coordinate trace of each molecule.

  • fwhms (list) – List of full-width half-maximums (FWHMs) for each crossing in the trace.

  • crossing_coords (list) – The crossing coordinates of each branch crossing.

Returns:

2D individual ‘molecule’ labelled image.

Return type:

npt.NDArray

static get_trace_idxs(fwhms: list) → tuple[list, list][source]#

Split under-passing and over-passing indices.

Parameters:

fwhms (list) – List of arrays of full-width half-maximum (FWHM) values for each crossing point.

Returns:

All the under, and over indices of the for each node FWHMs in the provided FWHM list.

Return type:

tuple[list, list]

check_node_errorless() → bool[source]#

Check if an error has occurred while processing the node dictionary.

Returns:

Whether the error is present.

Return type:

bool

identify_writhes() → str | dict[source]#

Identify the writhe topology at each crossing in the image.

Returns:

A string of the whole grain writhe sign, and a dictionary linking each node to it’s sign.

Return type:

str | dict

static writhe_direction(first_vector: numpy.typing.NDArray, second_vector: numpy.typing.NDArray) → str[source]#

Use the cross product of crossing vectors to determine the writhe sign.

Parameters:

  • first_vector (npt.NDArray) – An x,y component vector of the overlying strand.

  • second_vector (npt.NDArray) – An x,y component vector of the underlying strand.

Returns:

‘+’, ‘-’ or ‘0’ for positive, negative, or no writhe.

Return type:

str

run_nodestats_tracing() → tuple[list, dict, dict][source]#

Run the nodestats tracing pipeline.

Returns:

A list of each molecules ordered trace coordinates, the ordered_tracing stats, and the images.

Return type:

tuple[list, dict, dict]

class topostats.tracing.ordered_tracing.OrderedTraceTopostats(image, skeleton)[source]#

Order single pixel thick skeleton coordinates via TopoStats.

Parameters:

  • image (npt.NDArray) – A cropped image array.

  • skeleton (npt.NDArray) – The pruned skeleton mask array.

image#
skeleton#
grain_tracing_stats#
mol_tracing_stats#
images#
static get_ordered_traces(disordered_trace_coords: numpy.typing.NDArray, mol_is_circular: bool) → list[source]#

Obtain ordered traces from disordered traces.

Parameters:

  • disordered_trace_coords (npt.NDArray) – A Nx2 array of coordinates to order.

  • mol_is_circular (bool) – A flag of whether the molecule has at least one coordinate with only one neighbour.

Returns:

A list of each molecules ordered trace coordinates.

Return type:

list

run_topostats_tracing() → tuple[list, dict, dict][source]#

Run the topostats tracing pipeline.

Returns:

A list of each molecules ordered trace coordinates, the ordered_traicing stats, and the images.

Return type:

tuple[list, dict, dict]

topostats.tracing.ordered_tracing.linear_or_circular(traces) → bool[source]#

Determine whether the molecule is circular or linear via >1 points in the local start area.

This function is sensitive to branches from the skeleton because it is based on whether any given point has zero neighbours or not so the traces should be pruned.

Parameters:

traces (npt.NDArray) – The array of coordinates to be assessed.

Returns:

Whether a molecule is linear or not (True if linear, False otherwise).

Return type:

bool

topostats.tracing.ordered_tracing.ordered_trace_mask(ordered_coordinates: numpy.typing.NDArray, shape: tuple) → numpy.typing.NDArray[source]#

Obtain a mask of the trace coordinates with each trace pixel.

Parameters:

  • ordered_coordinates (npt.NDArray) – Ordered array of coordinates.

  • shape (tuple) – The shape of the array bounding the coordinates.

Returns:

NxM image with each pixel in the ordered trace labeled in ascending order.

Return type:

npt.NDArray

topostats.tracing.ordered_tracing.ordered_tracing_image(image: numpy.typing.NDArray, disordered_tracing_direction_data: dict, nodestats_direction_data: dict, filename: str, ordering_method: str, pad_width: int) → tuple[dict, pandas.DataFrame, pandas.DataFrame, dict][source]#

Run ordered tracing for an entire image of >=1 grains.

Parameters:

  • image (npt.NDArray) – Whole FOV image.

  • disordered_tracing_direction_data (dict) – Dictionary result from the disordered traces. Fields used are “original_image” and “pruned_skeleton”.

  • nodestats_direction_data (dict) – Dictionary result from the nodestats analysis.

  • filename (str) – Image filename (for logging purposes).

  • ordering_method (str) – The method to order the trace coordinates - “topostats” or “nodestats”.

  • pad_width (int) – Width to pad the images by.

Returns:

Results containing the ordered_trace_data (coordinates), any grain-level metrics to be added to the grains dataframe, a dataframe of molecule statistics and a dictionary of diagnostic images.

Return type:

tuple[dict, pd.DataFrame, pd.DataFrame, dict]