Analysis

Analysis -> Analysis wrappers

Analyzes filament data to compute various attributes including length, curvature, tortuosity, and intensity-related metrics. If image data is provided, intensity metrics such as average intensity, average length intensity, total intensity, and total length intensity are computed. Lengths can be scaled based on pixel size (px) if specified.

Parameters:

data (Union[np.ndarray, List, Tuple]) – Filament data used for analysis. Can be a numpy array or a sequence containing numpy arrays.
image (Union[np.ndarray, List, Tuple], optional) – Optional image data corresponding to the filaments. Used for computing intensity metrics. Can be a numpy array or a sequence containing numpy arrays.
thickness (int, optional) – Thickness of filaments used for intensity calculation. Defaults to 1.
px (Sequence, optional) – Scaling factors for pixel size to convert lengths into physical units. If None, lengths are computed directly without scaling. Defaults to None.

Returns:

A tuple containing:

length (list): Computed lengths of the filaments.
curvature (list): Computed mean curvatures of the filaments.
tortuosity (list): Computed mean tortuosity of the filaments.
avg_intensity (list): Computed average intensity per filament, or None if no image data is provided.
avg_length_intensity (list): Computed average filament intensity normalized by filament length, or None if no image data is provided.
sum_intensity (list): Computed total intensity per filament, or None if no image data is provided.
sum_length_intensity (list): Computed total filament intensity normalized by filament length, or None if no image data is provided.

Return type:

tuple

tardis_em.analysis.analysis.save_analysis(names: List | Tuple, analysis: List | Tuple, px=None, save: str | None = None) → None | ndarray

Saves or generates a detailed analysis file from the given analysis data. The function is capable of saving the processed analysis to a CSV file if a save path is provided or alternatively returns the processed analysis as a NumPy array. The analysis includes details such as filament lengths, curvatures, tortuosities, and intensity-related data. It is designed to handle multiple files and their corresponding filament data.

Parameters:

names – List or tuple containing the names of the files being analyzed.
analysis – Tuple or list containing multiple analysis metrics such as length, curvature, tortuosity, intensity, and their derivatives. Each metric corresponds to a specific aspect of the filament data.
px – Optional parameter containing pixel size for each file, which is used to calculate some metrics. If not specified, a default value is assumed.
save – Optional parameter specifying the path where the CSV file will be saved. If not provided, the function will not save the file and returns the analysis as a NumPy array.

Returns:

Returns a NumPy array containing the processed analysis, or None if the analysis is saved to a CSV file.

Analyzes and processes a list of filament data along with optional corresponding images. The function validates the input to ensure consistency between the length of the data and images before analyzing the filaments. The processed analysis is then saved to the specified path.

Parameters:

data (Union[List, Tuple]) – A collection of data representing filament structures. It must be a list or tuple.
names_l (Union[List, Tuple]) – A collection of filenames or identifiers corresponding to each set of data. It must be a list or tuple.
path (str) – A string representing the file path where the analysis results will be saved.
images (Optional[Union[List, Tuple]]) – Optional collection of images corresponding to the data, where each image represents the visual context of the filament. Default is None.
px (Optional[Union[List, Tuple]]) – Optional collection indicating pixel calibration or scaling of the images, if provided. Default is None.
thickness (int) – An integer specifying the thickness parameter used during filament analysis. Default is 1.

Returns:

None

tardis_em.analysis.analysis.analyse_mt_classes(filaments: ndarray, poles: ndarray, vertices: list) → tuple

Analyzes microtubule (MT) classes by assigning filaments to poles, then categorizing their ends as plus or minus ends. The process involves sorting poles relative to defined vertices, assigning filaments to corresponding poles, and subsequently determining the extremities of the filaments.

Parameters:

filaments – A NumPy array of filaments where each filament is defined as a collection of points.
poles – A NumPy array containing pole positions.
vertices – A list of vertex points used to determine pole-to-surface assignments.

Returns:

A tuple where the first element contains the mapping of filaments to poles and the second element is a tuple with two lists: one for the plus ends and another for the minus ends of the filaments.

Analysis -> Filament Structure

tardis_em.analysis.filament_structure.assign_filaments_to_poles(filaments, poles)

Assigns filaments to the closest poles and potentially flips their orientation to maintain consistency based on proximity to the assigned pole.

The function processes a set of filaments, identified by unique IDs, and calculates their start and end points. Distances from these points to given poles are computed, and each filament is assigned to the nearest pole. If needed, the points of a filament are reordered to ensure that their orientation starts closer to their assigned pole. Filaments are then grouped according to their assigned pole.

Parameters:

filaments – A 2D NumPy array where each row contains information about an individual point of a filament. The first column represents the filament ID, and the remaining columns represent the position coordinates of the point.
poles – A 2D NumPy array where each row contains the coordinates of a pole.

Returns:

A tuple containing two arrays. The first array represents the filaments assigned to the first pole, while the second array represents the filaments assigned to the second pole. Each filament is listed with its points in correct order to maintain proximity to the assigned pole.

Return type:

Tuple[np.ndarray, np.ndarray]

Analysis -> Geometry metrics

tardis_em.analysis.geometry_metrics.curvature(coord: ndarray, tortuosity_b=False) → float | tuple

Computes the curvature of a curve specified by input coordinates. Optionally, it can also compute the tortuosity of the curve if the tortuosity_ parameter is set to True. The curvature is calculated as the norm of the cross product of the first and second derivatives divided by the norm of the first derivative raised to the power of three. Tortuosity is defined as the ratio of the curve’s arc length to the straight-line distance between its endpoints.

Parameters:

coord – A NumPy array representing the coordinates of the curve where curvature calculations are performed.
tortuosity_b – A boolean flag indicating whether to calculate the tortuosity value in addition to the curvature. If True, tortuosity is calculated as the ratio of the curve length to the straight-line distance between the endpoints.

Returns:

If tortuosity_b is False, a single float is returned representing the average curvature; if tortuosity_b is True, a tuple is returned containing the average curvature as the first element and the tortuosity value as the second element.

tardis_em.analysis.geometry_metrics.curvature_list(coord: ndarray, tortuosity_b=False, mean_b=False) → list | tuple

Computes curvature and optionally tortuosity of splines corresponding to unique coordinate groups in a given array. The input consists of a 2D array where the first column represents group identifiers and the subsequent columns represent the coordinates of points in each group. Curvature computation is based on groups with at least six points.

Parameters:

coord – A 2D numpy array where the first column indicates grouping identifiers and the remaining columns represent coordinates of points.
tortuosity_b – A boolean indicating whether to compute and return the tortuosity for each group. Default is False.
mean_b – A boolean flag. When set to True, the mean curvature value for each group is computed instead of returning individual curvatures. Default is False.

Returns:

If tortuosity_b is False, returns a list of curvatures for each unique group. If tortuosity_b is True, returns a tuple containing two elements: a list of curvatures and a list of tortuosity values (as floats) for each group.

tardis_em.analysis.geometry_metrics.tortuosity(coord: ndarray) → float

Calculates the tortuosity of a curve.

This function computes the ratio of the total length of a curve defined by a series of coordinates to the straight-line distance between the first and last points of the curve. If there is only one coordinate or none, it returns a default value of 1.0 as the tortuosity cannot be defined.

Parameters:: coord – A numpy array containing the coordinates of the curve, where each coordinate is a point in n-dimensional space.
Returns:: A float representing the tortuosity, which is computed as the ratio of the total length of the curve to the straight-line distance between the start and end points.

tardis_em.analysis.geometry_metrics.tortuosity_list(coord: ndarray) → list

Calculates the tortuosity for each unique coordinate id in the provided array. The function groups the input coordinates by their unique first column values, computes the tortuosity for each group, and returns the results as a list of floats.

Parameters:: coord (numpy.ndarray) – A 2-dimensional numpy array where the first column represents unique ids and the subsequent columns represent coordinates.
Returns:: A list of tortuosity values as floats, each corresponding to a unique id from the first column of input.
Return type:: list

tardis_em.analysis.geometry_metrics.total_length(coord: ndarray) → float

Computes the total length of a path defined by a sequence of coordinates.

This function calculates the total distance between consecutive points in a path represented by an array of coordinates. The distance is computed using the Euclidean norm.

Parameters:: coord – A numpy array where each row represents a point’s coordinates in the path.
Returns:: Sum of the Euclidean distances between consecutive points in the path.
Return type:: float

tardis_em.analysis.geometry_metrics.length_list(coord: ndarray) → list

Calculate the total lengths of grouped coordinates and return them as a list.

This function processes a numpy array of coordinates, groups them based on the unique values in the first column, calculates the lengths of each group of coordinates using an external total_length function, and returns the lengths of these groups as a list of floats.

Parameters:: coord – A numpy array of shape (N, M) where the first column describes a grouping attribute, and the remaining columns define the coordinates for which the lengths are calculated.
Returns:: A list of float values representing the calculated lengths for each group of coordinates based on the unique grouping from the first column of the input array.

tardis_em.analysis.geometry_metrics.angle_between_vectors(v1: ndarray, v2: ndarray) → float

Calculates the angle between two vectors in degrees. This function computes the angle based on the dot product and magnitudes of the input vectors. The arc cosine of the cosine similarity is calculated to derive the angle between the vectors. A small value is added to the magnitudes to prevent division by zero.

cos(theta) = (A . B) / (||A|| ||B||)

Parameters:

v1 (np.ndarray) – The first vector represented as a numpy array.
v2 (np.ndarray) – The second vector represented as a numpy array.

Returns:

The angle between v1 and v2 in degrees.

Return type:

float

tardis_em.analysis.geometry_metrics.intensity(data: ndarray, image: ndarray, thickness=1) → ndarray

Computes the intensity values along a parametric spline through a given dataset and subtracts the background intensity estimated from parallel shifted spline paths. This function is designed specifically for tasks involving intensity extraction in image processing.

Parameters:

data (np.ndarray) – 2D array containing the coordinates corresponding to the data points the spline is fitted to.
image (np.ndarray) – 2D image array from which pixel intensity values will be extracted.
thickness (int, optional) – Integer denoting the thickness of the line for which pixel intensities will be aggregated. Default value is 1.

Returns:

1D array containing the adjusted intensity values along the spline after background subtraction.

Return type:

np.ndarray

tardis_em.analysis.geometry_metrics.pixel_intensity(coord: ndarray, image: ndarray) → list | None

Extracts pixel intensities from an image at specified coordinates. The function supports both 2D and 3D images and handles out-of-bound coordinates with None. If any extracted pixel value is None, it replaces them with the minimum valid pixel value present in the list. If no valid pixel values are found, it returns None.

Parameters:

coord – A numpy array of shape (N, 3) for 3D or (N, 2) for 2D, containing the coordinates where pixel intensities are to be extracted.
image – A numpy array representing the image from which pixel intensities are to be extracted. Can be either 2D or 3D.

Returns:

A list of extracted pixel intensities. If any coordinate is invalid, its corresponding intensity is initially None but replaced with the minimum valid pixel value in the list. Returns None if no valid pixel values exist.

tardis_em.analysis.geometry_metrics.thicken_line_coordinates(coords: ndarray, thickness: int)

Expands the thickness of a set of 3D coordinates to represent a line or shape with a specified thickness. This is achieved by creating a grid of points around each coordinate based on the specified thickness.

This function is useful for visualizing or processing lines/shapes in three-dimensional space with a specific thickness, often needed in environments like 3D geometry processing or voxel-based computations.

Parameters:

coords – A NumPy array containing 3D coordinates to be thickened. Each coordinate is represented as a tuple (x, y, z).
thickness – An integer that defines the extent of expansion around the input coordinates. The thickness is centered on each coordinate, producing a local grid.

Returns:

A NumPy array containing the updated set of 3D coordinates, including all points within the specified thickness range.

tardis_em.analysis.geometry_metrics.intensity_list(coord: ndarray, image: ndarray, thickness=1)

Extracts intensity values along spline coordinates from the given image.

This function computes the intensity values along a set of spline coordinates within a given image, using the specified thickness for sampling. It iterates through unique spline identifiers in the coordinate array, processes points associated with each identifier, and computes the intensity or returns a zero value if there are insufficient points.

Parameters:

coord – A 2D array containing the spline coordinates. The first column represents unique identifiers for each spline, and the remaining columns represent the spatial coordinates of each point.
image – A 2D numpy array representing the image from which intensity values are to be extracted.
thickness – An optional parameter specifying the thickness used for sampling intensity values. Defaults to 1.

Returns:

A list of intensity values computed for each unique spline identifier. The list contains a computed intensity value for identifiers with sufficient points and 0.0 for those with insufficient points.