Analysis -> Filament Utils

tardis_em.analysis.filament_utils.resample_filament(points, spacing_size) → ndarray

Resample a collection of 3D coordinates (X, Y, Z) associated with unique IDs to uniform spacing along their paths. The input points are grouped by their IDs, and each group is interpolated based on the specified spacing size.

Parameters:

points – A numpy array of shape [N, 4], where each row contains [ID, X, Y, Z]. The ‘ID’ column is used to differentiate between different groups of points, while the remaining columns represent the 3D coordinates.
spacing_size – A float specifying the uniform spacing distance to be applied when resampling the 3D points within each group.

Returns:

A numpy array of resampled points with shape [M, 4], where each row contains [ID, X, Y, Z]. The output maintains the ID for each group, along with its uniformly-spaced coordinates.

Return type:

numpy.ndarray

tardis_em.analysis.filament_utils.sort_segments(coord: ndarray) → ndarray

Sorts 3D segments by their coordinates. The function first identifies unique segment identifiers in the first column of the array. It then collects and sorts the associated segments for each unique identifier, constructing a final 2D array combining the sorted results.

Parameters:: coord – Input 2D array where each row represents a 3D segment. The first column contains unique segment identifiers, and the remaining columns contain the segment coordinates.
Returns:: A sorted 2D array of the same shape as the input, where the rows are sorted segment-wise based on their coordinates.

tardis_em.analysis.filament_utils.sort_segment(coord: ndarray) → ndarray

Sorts a set of coordinates in a specific sequence by iteratively selecting the farthest point and proceeding to find the nearest neighbors in subsequent steps.

This function is designed to work with a two-dimensional array of coordinates. It uses a combination of distance calculations (using cdist) and nearest-neighbor search (using scipy.spatial.KDTree) to determine the order in which coordinates are rearranged. The process starts by identifying the farthest pair of points in the set and continues from the first point in the sequence, progressively adding the nearest neighbor to the sequence.

Parameters:: coord – A numpy array of two-dimensional coordinates. Shape is expected as (n, 2), where n is the number of coordinates provided.
Returns:: A numpy array of sorted coordinates in the order as per the described procedure.
Return type:: np.ndarray

tardis_em.analysis.filament_utils.reorder_segments_id(coord: ndarray, order_range: list | None = None, order_list: ndarray | list | None = None) → ndarray

Reorders segment IDs within the provided coordinate array based on the given range or a specific order list. This function modifies the segment IDs in the coordinate data to either follow a sequence defined by a range or an explicitly provided order. If no range or list is provided, default ordering is applied based on the unique segment IDs.

Parameters:

coord (np.ndarray) – A 2D numpy array where the first column contains the segment IDs to be reordered.
order_range (Optional[list]) – An optional list defining the range of values to be used when reordering segment IDs. If None, the IDs are reordered into a default range sequence.
order_list (Optional[Union[list, np.ndarray]]) – An optional list or numpy array defining the specific new order of segment IDs. If None, the IDs are reordered using a default range sequence.

Returns:

A numpy array with updated segment IDs, reflecting the reordering as per the provided range or specific order list.

Return type:

np.ndarray

tardis_em.analysis.filament_utils.smooth_spline(points: ndarray, s=0.5)

Smoothens a given set of 3D points using spline interpolation to reduce variations and noise while maintaining the overall shape of the point cloud.

If the points array includes an identifier column (ID), the function normalizes the coordinates, computes the pre- and post-smoothing tortuosity of the points, and ensures that the smoothed spline does not increase tortuosity excessively, serving as a failure check for the smoothing process.

If the points array contains only the 3D coordinates ([X, Y, Z]), it directly computes the spline without any tortuosity checks or normalization.

Parameters:

points – The array of input 3D points to be smoothened. The input array should have a shape of either (N, 3) for 3D points without identifiers, or (N, 4) for 3D points prefixed with an identifier column.
s – The smoothness factor for spline interpolation. A smaller value ensures the spline closely conforms to the input points, while a larger value produces a smoother spline. Default is 0.5.

Returns:

An array of smoothened 3D point coordinates. If an identifier column is present, it is preserved in the returned result. The output shape is consistent with the input, either (N, 4) for points with identifiers or (N, 3) for points without identifiers.

tardis_em.analysis.filament_utils.sort_by_length(coord)

Sorts and reorders segments in the coordinate array by their total length in ascending order.

This function takes an input array of coordinates, identifies unique segment IDs, calculates the total length of each segment, and then sorts the segments by length. The output is the reordered array with updated segment IDs, maintaining their relative order after sorting.

Parameters:: coord (numpy.ndarray) – A numpy array where the first column represents segment IDs and the subsequent columns represent coordinates.
Returns:: A numpy array with segments reordered by their total length, where segment IDs are updated and assigned sequentially in the sorted order.
Return type:: numpy.ndarray

tardis_em.analysis.filament_utils.cut_150_degree(segments_array: ndarray)

Cuts segments based on angles between consecutive line segments and reassigns IDs to the newly split segments. The function calculates angles between vectors within provided segments, and if any angle is less than or equal to 150 degrees, the segment is split at the point with the smallest angle. Single-point segments are excluded from the output.

Parameters:: segments_array (numpy.ndarray) – A numpy ndarray where each row represents a segment point. The first column contains segment IDs, and the remaining columns contain point coordinates.
Returns:: A tuple containing a boolean indicating whether any segments were split, and a numpy array of the updated segments with reassigned segment IDs.
Return type:: tuple

Analysis -> Spatial Graph Utils

class tardis_em.analysis.spatial_graph_utils.FilterConnectedNearSegments(distance_th=1000, cylinder_radius=150)

This class is used to manage and process splines in a point cloud by connecting nearby segments based on specific cylindrical geometry criteria. It handles operations such as determining cylindrical overlap, removing duplicates, and merging splines.

splines_direction(spline1: list, spline2: list) → bool

Determines whether two splines are facing the same direction within specific spatial constraints. This function evaluates the positional relationships of two splines based on predefined conditions involving distance and orientation in a cylindrical coordinate system.

Parameters:

spline1 – The first spline represented as a list of points, where each point is a coordinate in 2D or 3D space.
spline2 – The second spline represented as a list of points, where each point is a coordinate in 2D or 3D space.

Returns:

A boolean value indicating whether the two splines face in the same direction based on the specified criteria.

marge_splines(point_cloud: ndarray, omit_border: int, initial: bool) → ndarray

Merge splines from a given point cloud dataset based on certain distance and alignment criteria. Each spline in the point cloud is analyzed and combined with other splines if they satisfy conditions such as proximity, alignment, and not being within a border exclusion zone. The function returns the merged splines as a numpy array.

Parameters:

point_cloud (numpy.ndarray) – A numpy array representing the point cloud data, where each row corresponds to a point with information such as spline ID, x-coordinate, y-coordinate, and z-coordinate.
omit_border (int) – An integer value specifying the range from the minimum and maximum along the z-axis for excluding points at borders, used to eliminate spurious connections near boundaries.
initial (bool) – A boolean indicating whether to process and create an initial dictionary of splines based on unique spline IDs. Controls the creation and initialization of spline data structures.

Returns:

A numpy array representing the merged splines, where each row corresponds to a point with updated spline IDs, x-coordinate, y-coordinate, and z-coordinate. The merged splines preserve the consistency of segment continuity and alignment.

Return type:

numpy.ndarray

class tardis_em.analysis.spatial_graph_utils.FilterSpatialGraph(connect_seg_if_closer_then=1000, cylinder_radius=200, filter_short_segments=1000)

A class for filtering and refining spatial graphs by connecting nearby segments and removing short segments.

This class is designed to process a given array of segments representing spatial structures, such as microtubules or similar graph-based representations. The primary tasks include connecting splines with endpoints within a specified distance and removing splines that are below a defined length threshold. Additionally, iterative optimization is performed to split connections at sharp angles.

class tardis_em.analysis.spatial_graph_utils.SpatialGraphCompare(distance_threshold: int, interaction_threshold: float)

Compares spatial graphs to identify matching microtubules (MTs) and classify them based on specific criteria.

This class is designed to analyze and compare spatial graphs, which represent microtubule structures, based on user-defined thresholds. It identifies matching microtubules between two spatial graphs by calculating probabilities of alignment. The class is used for both comparing spatial structures and filtering instances based on pre-defined distance and interaction thresholds.

class tardis_em.analysis.spatial_graph_utils.ComputeConfidenceScore

static normalized_length(points: ndarray, min_l: float, max_l: float)

Calculates the normalized length of a path defined by a sequence of points. The normalization is based on the minimum and maximum lengths provided. It utilizes the total_length function to compute the original length of the path. The returned normalized value lies between 0 and 1.

Parameters:

points – A numpy array representing the sequence of points that defines the path.
min_l – The minimum length to be used for normalization.
max_l – The maximum length to be used for normalization.

Returns:

Normalized length of the path as a float value.

combined_smoothness(points: ndarray, min_l: float, max_l: float)

Computes the combined smoothness score for a series of points based on both angle-based smoothness and normalized length. The method integrates these two metrics into a single smoothness score by averaging their values.

Parameters:

points – The array of points representing a series of coordinates. It should have shape (n, m) where n is the number of points and m is the dimensionality of each point.
min_l – The minimum length used for normalization.
max_l – The maximum length used for normalization.

Returns:

The combined smoothness score as a float value.

tardis_em.analysis.spatial_graph_utils.compare_splines_probability(spline_1: ndarray, spline_2: ndarray, threshold=100)

Compares the similarity of two splines based on a distance threshold and returns a probability measure of their intersection. The comparison is performed by calculating the distances between points on the splines and determining the proportion of points on the first spline that match the second spline, within the specified threshold.

Parameters:

spline_1 – A numpy array representing the first spline.
spline_2 – A numpy array representing the second spline.
threshold – A numeric value representing the distance threshold below which points on the splines are considered matching. Default is 100.

Returns:

A floating-point value representing the probability of intersection, i.e., the proportion of points on the first spline that match the second spline within the specified threshold.