Analysis -> MT Classification

MT Classification - Main

class tardis_em.analysis.mt_classification.mt_classes.MicrotubuleClassifier(surfaces: str, filaments: str, poles: str, pixel_size, gaps_size=100, kmt_dist_to_surf=1000, tardis_logo=True)

Manages the classification and preprocessing of data related to Microtubule (MT) analysis, including processing of surfaces, filaments, and poles. This class aims to facilitate segmentation and feature extraction for MT datasets, enabling further analysis tasks such as classification and structural evaluations.

It initializes with critical parameters, loads and corrects processed data, and offers methods to extract relevant structural information from the provided files.

get_vertices_file(dir_s: str, simplify: bool | None = None) → list

Extracts and returns the vertices information from a given directory containing data for an AM surface file. This method utilizes the load_am_surf function to process the data in the specified directory. Optionally, the simplification param can be used to streamline the vertices extraction process.

Parameters:

dir_s (str) – The directory containing the AM surface file.
simplify (bool, optional) – Defines whether simplification is applied during the loading process. This parameter is optional.

Returns:

A list of vertices extracted from the surface file.

Return type:

list

static get_filament_file(dir_s: str) → ndarray

Extracts and returns segmented points from the specified directory using the ImportDataFromAmira class. This function is a static method and does not rely on class instance attributes.

Parameters:: dir_s (str) – Directory path to the source AM file
Returns:: Numpy array of segmented points extracted from the specified directory
Return type:: np.ndarray

static get_poles_file(dir_s: str) → ndarray

Retrieve pole positions from a specified directory and returns them as a NumPy array.

This method uses the ImportDataFromAmira class to access data associated with vertex positions in the specified directory. It processes the data to extract pole positions and return them in a structured format suitable for further computations or analysis.

The directory passed must contain the required data structure that is compatible with ImportDataFromAmira functionality. The output is formatted as a NumPy array.

Parameters:: dir_s (str) – The file path to the directory containing the Amira data files
Returns:: A NumPy array containing the vertex data representing pole positions
Return type:: np.ndarray

correct_data()

Normalizes and processes filament data based on pixel size and assigned poles.

This method performs several operations including: - Normalization of filament coordinates using the pixel size. - Resampling of the filament data. - Normalization of vertex and pole coordinates. - Assignment of filaments to poles and subsequent reordering. - Stacking of corrected filaments into a unified structure.

get_filament_endpoints() → tuple[int, int]

Computes and returns the start and end indices of the unique filament IDs in the dataset. This function identifies unique filament IDs and uses them to derive the corresponding starting and ending positional indices.

Returns:: A tuple containing two integers: - The starting index of the first unique filament ID. - The ending index of the last unique filament ID.
Return type:: tuple[int, int]

assign_to_kmts(filaments, id_i=0) → list

Assigns filaments to kinetochores (KMTs) based on spatial and distance criteria.

The function performs several steps to identify filaments, represented by their unique IDs, that meet specific conditions relative to bounding boxes, surfaces, and distance thresholds. It uses unique identification, filtering within bounding boxes, various distance measurements, and thresholds to determine the final set of KMT-associated filaments.

Parameters:

filaments – A NumPy array representing the set of filaments.
id_i – An integer representing the index of the vertices and poles being processed. Defaults to 0.

Returns:

A list of unique filament IDs assigned to KMTs.

kmts_inside_outside(kmt_proposal, id_i=0) → tuple[ndarray, ndarray]

Determines whether the k-MTs (kinetochore MicroTubules) are inside or outside based on their distance to the surface. The function computes unique k-MTs and evaluates the proximity of their plus ends in comparison to a given pole surface. The result is segregated into k-MTs considered inside and outside.

Parameters:

kmt_proposal – A 2D numpy array where each row corresponds to an association of k-MTs, with the first column representing k-MT identifiers.
id_i – An integer representing the identifier of the current vertex and pole configuration to be used for computations. Defaults to 0.

Returns:

A tuple containing two numpy arrays. The first array contains unique k-MT identifiers classified as inside, while the second array contains unique k-MT identifiers classified as outside.

assign_to_mid_mt() → list

Assigns microtubules (MTs) to a middle set based on specific conditions and filters.

The function identifies MTs which are not part of specific pre-defined ID sets and selects candidate MTs with no more than one crossing. It further filters these selected MTs based on their distance to a defined set of vertices in comparison to poles. The final IDs of the specific MTs that meet all conditions are returned as a list.

Returns:: A list of MT IDs that belong to the middle set. These are filtered based on their geometric properties and crossing conditions.
Return type:: list

assign_to_int_mt() → list

Assigns intermediate microtubule IDs based on specific criteria.

This function identifies intermediate microtubules (MTs) from given input data, excluding specific MT IDs and using bounding boxes to further select relevant MTs. It then reassigns the identified MTs based on crossing criteria and returns their IDs as a list.

Raises:: ValueError – If the provided data structures have inconsistent shapes or types.
Returns:: A list of assigned intermediate microtubule IDs. If no IDs are found or assigned, an empty list is returned.
Return type:: list

assign_to_bridge_mt() → list

Assigns microtubules to the bridge class based on their ID exclusions and their spatial crossings with assigned vertices. It first filters out specific filament IDs that belong to other microtubule classes and then assigns remaining filaments to the bridge if they meet crossing conditions.

Returns:: A list of microtubule IDs assigned to the bridge class.
Return type:: list

assign_mt_with_crossing(filaments, vertices_l, class_l=[1]) → ndarray

Assigns microtubule (MT) IDs based on whether or not they cross a specific surface and belong to a specified class of interest.

The function evaluates a set of segmented microtubules (filaments) and determines to which class each should belong. This classification is based on their crossing behavior with a given surface defined by vertices, as well as a specified class parameter. It ensures that MTs crossing specific surfaces or having other characteristics are correctly classified.

Parameters:

filaments – A 2D numpy array where each row represents a segment of a microtubule. The first column contains microtubule IDs (integers), while the subsequent columns correspond to the spatial coordinates (e.g., x, y, z).
vertices_l – A 2D numpy array representing the vertices of the surface for comparison, each row specifying a spatial coordinate (e.g., x, y, z).
class_l – A list of integers representing the microtubule classification criteria. Default is [1], which selects microtubules matching the threshold condition.

Returns:

A numpy array containing IDs of microtubules that intersect the surface and fit the classification criteria specified by the class_ parameter.

classified_MTs()

Classifies microtubules (MTs) into different categories based on spatial properties, assignments to poles, and other criteria. The classification includes Kinetochore Microtubules (KMTs), Mid-MTs, Interdigitating-MTs, Bridging-MTs, and Standard Microtubules (SMTs). Coordinates are corrected to the original scale after assignments. Contains options for a logo display summarizing the classification process. This function integrates multiple steps such as endpoint determination, pole classifications, and other custom classifications.

Parameters:

self – The object instance invoking the method.

Raises:

ValueError – If any invalid indices are encountered during processing.
TypeError – If inputs to certain classification methods have mismatched types.
AttributeError – If required attributes are missing from the self instance.

Returns:

None

get_classified_indices() → list

Returns a list of classified indices, grouped into specific categories representing various groups of IDs. These categories include inside and outside IDs, mid-point IDs, intermediate IDs, bridge IDs, and SMT IDs.

Returns:: List containing groups of classified indices.
Return type:: list

get_classified_fibers() → list

Classifies and retrieves fibers based on their categories and identifiers. This method divides the fibers into multiple subcategories including kinetochore microtubules (kMT) for two different states (inside and outside), midplane microtubules (mid_MT), interpolar microtubules (int_MT), bridging microtubules (brg_MT), and other spindle microtubules (smt_MT). The classification is performed by checking the fiber identifiers against predefined ID collections.

Returns:: A nested list where each element represents a specific category or subcategory of classified fibers. It includes a list of kMT fibers for each state (inside, outside), and other categorized fibers (mid_MT, int_MT, brg_MT, smt_MT).
Return type:: list

get_filaments() → ndarray

Returns the filaments stored in the object.

The function provides direct access to the filaments as a numpy array. It is useful for retrieving the stored filaments data for further processing or analysis purposes.

Returns:: A numpy array containing filaments data.
Return type:: np.ndarray

get_vertices(simplify=128) → tuple[list, list]

Retrieve the vertices and triangles of the object, with optional simplification.

The method allows fetching the vertices and triangles that represent the geometry of the object. By default, an optional simplification value can be provided to reduce the complexity of the vertices. If the simplify parameter is None, an alternative retrieval process is utilized.

Parameters:: simplify (int or None) – Specifies the simplification factor for reducing vertex complexity. If None, returns the detailed geometry without simplification.
Returns:: A tuple containing a list of vertices and a list of triangles.
Return type:: tuple[list, list]

get_poles() → ndarray

Retrieves the poles data of a given instance and returns it as a NumPy array. Poles typically represent key computation parameters or specific physical characteristics depending on the context of implementation.

Returns:: An array containing the poles of the current instance.
Return type:: numpy.ndarray

MT Classification - Utils

tardis_em.analysis.mt_classification.utils.count_true_groups(bool_list) → int

Counts the number of ‘True’ groups in a list of booleans. A ‘True’ group is defined as a contiguous sequence of ‘True’ values, separated by at least one ‘False’ value or the start/end of the list non-‘True’ regions. This function iterates through the given list and counts distinct ‘True’ groups.

Parameters:: bool_list (list[bool]) – A list of boolean values.
Returns:: The number of ‘True’ groups identified in the boolean list.
Return type:: int

tardis_em.analysis.mt_classification.utils.distances_of_ends_to_surface(vertices_n: ndarray, pole_n: ndarray, ends: ndarray, d1_to_surf=False) → tuple[ndarray, ndarray]

Compute the distances from specified end points to a surface and optionally to a reference pole.

This function determines the distances of provided end points to the nearest vertex on a specified surface and optionally the further distance to a prespecified pole. The function makes use of the Nearest Neighbors algorithm for distance computation. If the additional parameter d1_to_surf is set, the calculated distances include intermediate computations involving the nearest neighbors of end points on the surface.

Parameters:

vertices_n – Array of coordinates of the vertices defining the surface.
pole_n – Array of coordinates representing the reference pole position.
ends – Array of coordinates of the end points for which distances are to be calculated.
d1_to_surf – Boolean flag. If True, distances from the end points to the surface include intermediate computations involving the nearest neighbors of specified vertices on the surface. Defaults to False.

Returns:

A tuple of two distance arrays. The first array represents distances computed involving d1_to_surf logic if True, otherwise from ends to the nearest vertices. The second array contains distances from end points to the reference pole.

tardis_em.analysis.mt_classification.utils.distance_to_the_pole(points: ndarray, distance_to: ndarray) → ndarray

Compute the Euclidean distances between each point and a reference point.

This function calculates the Euclidean distance from a given set of points to a specific reference point. The points and the reference point must be provided as numpy arrays. The expected shapes of the input arrays ensure that each row in the points array represents a single point in the same dimensional space as the distance_to point.

Parameters:

points – A numpy array of shape (n, m) where n is the number of points and m is the dimensionality of the points.
distance_to – A numpy array of shape (m,) that specifies the reference point in the m-dimensional space.

Returns:

A numpy array of shape (n,) representing the computed distances for each point to the given reference point.

tardis_em.analysis.mt_classification.utils.divide_into_sequences(arr) → list[list[int]]

Divides a list of integers into contiguous subsequences, where each subsequence contains consecutive numbers. The method processes the input list and groups elements into separate lists based on consecutive relationships.

Parameters:: arr (list[int]) – A list of integers to be divided into sequences. Must be non-empty.
Returns:: A list of lists, where each internal list represents a contiguous subsequence of consecutive integers from the input list.
Return type:: list[list[int]]

tardis_em.analysis.mt_classification.utils.fill_gaps(float_list: list, n: float) → ndarray

Fill gaps between consecutive elements in a list with evenly spaced values.

This function takes a list of floats and a threshold value, n, to determine the gap size between consecutive elements. If the gap between two consecutive elements is smaller than or equal to n, it fills the gap with evenly spaced values. The resulting list is then returned as a sorted NumPy array with unique values.

Parameters:

float_list (list) – A list of float numbers to process.
n (float) – A float threshold value for determining the maximum gap size.

Returns:

A NumPy array with gaps filled by evenly spaced unique values.

Return type:

numpy.ndarray

tardis_em.analysis.mt_classification.utils.pick_pole_to_surfaces(poles, vertices) → ndarray

Determine the order of poles based on their distance to the centroid of provided vertices.

This function calculates the centroid of the given vertices, computes the Euclidean distance of the two poles from the centroid, and orders the poles based on which is closer to the centroid. If the second pole is closer to the centroid than the first pole, their positions are swapped in the returned array.

Parameters:

poles – A 2D NumPy array with shape (2, N), where each row represents a pole’s coordinates.
vertices – A NumPy array with shape (1, M, N), where M represents the number of vertices and N represents the dimensions (e.g., 2D, 3D) of each vertex’s coordinates.

Returns:

A NumPy array containing the reordered poles based on their distance to the centroid of the vertices.

tardis_em.analysis.mt_classification.utils.points_on_mesh_knn(points: ndarray, vertices: ndarray) → tuple[ndarray, ndarray]

Computes the distances of points to a mesh and identifies if the distances are within a threshold.

The function calculates the nearest distances from given points to the provided mesh vertices using k-nearest neighbors. It also determines whether the points lie within a computed distance based on the mean edge length of the mesh (mean distance between vertices multiplied by 2). The output includes the actual distances and a boolean array indicating if the threshold was met.

Parameters:

points – Coordinates of the points that need to be tested against the mesh vertices. Expected to be a 2D NumPy array with each row representing a point in space.
vertices – Coordinates of the mesh vertices. Expected to be a 2D NumPy array with each row representing a vertex in space.

Returns:

A tuple containing two elements: - A NumPy array of distances from each point to the nearest mesh vertex. - A NumPy boolean array indicating whether each distance falls within the computed threshold.

tardis_em.analysis.mt_classification.utils.select_mt_ids_within_bb(vertices_n: ndarray, mt_ends1: ndarray, mt_ends2=None) → ndarray

Finds microtubule (MT) IDs whose end-points lie within a 3D bounding box defined by the vertices. If mt_ends2 is provided, it performs the filtering on this additional set of MT end-points as well.

Parameters:

vertices_n – A 2D numpy array of shape (n, 3) representing the vertices of a 3D bounding box. Each vertex is expected to have x, y, and z coordinates.
mt_ends1 – A 2D numpy array where each row represents an MT end-point. Column 0 should contain MT IDs, and columns 1, 2, and 3 should correspond to x, y, and z coordinates of the end-points, respectively.
mt_ends2 – Optional. A 2D numpy array structured similarly to mt_ends1. Each row represents an additional set of MT end-points. Default is None.

Returns:

A 1D numpy array containing unique MT IDs whose end-points lie within the 3D bounding box defined by vertices_. If mt_ends2 is provided, the function updates its result set to include filtered IDs from mt_ends2 as well.

tardis_em.analysis.mt_classification.utils.assign_filaments_to_poles(filaments, poles) → tuple[ndarray, ndarray]

Assigns filaments to the closest of two poles based on their minimal distance and reverses filament orientation if necessary to ensure the correct assignment.

The function calculates the minimal distance between each filament endpoint and two given poles, and assigns filaments to the pole they are closest to. If the start point of a filament is farther from the assigned pole than the endpoint, the function flips the filament orientation. The result is a tuple of two arrays, where each array contains the filaments assigned to a particular pole.

Parameters:

filaments – A 2D numpy array of filaments where each row represents a point in a filament. The first column contains filament IDs, and the remaining columns represent the coordinates of the points.
poles – A 2D numpy array of two poles, where each row corresponds to a pole, and the columns represent the coordinates of the pole.

Returns:

A tuple of two numpy arrays. The first element contains all filaments assigned to pole 1, and the second element contains all filaments assigned to pole 2. Each array has rows corresponding to filament points, with the first column representing the filament ID and the remaining columns representing the coordinates of the filament point.