nnana#

class cryocat.analysis.nnana.NearestNeighbors(input_data=None, feature_id='tomo_id', nn_type='closest_dist', type_param=None, remove_qp=None, remove_duplicates=False)#

Bases: object

drop_symmetric_duplicates()#

get_angular_distances(rotation_type='all')#

get_nn_rotations()#

get_nn_subset(motl_values, feature_values)#

get_normalized_coord(add_to_df=True)#

get_qp_rotations()#

get_unique_values()#

cryocat.analysis.nnana.filter_nn_radial_stats(input_stats, binary_mask)#

Filter nearest neighbor radial statistics based on a binary mask.

Parameters:

input_statspandas.DataFrame: A DataFrame containing the nearest neighbor statistics, which must include columns for coordinates and a grouping identifier.
binary_maskstr: Path to a binary mask file that will be read to create a boolean mask for filtering.

Returns:

pandas.DataFrame: A DataFrame containing the filtered nearest neighbor statistics, with rows removed based on the provided binary mask.

Notes

The function adjusts the coordinates of the input statistics, ensuring they fall within the bounds of the binary mask. It then applies the mask to filter the statistics for each group defined by the ‘qp_subtomo_id’ column.

cryocat.analysis.nnana.get_feature_nn_indices(fm_a, fm_nn, nn_number=1, remove_qp=False)#

Get the indices and distances of nearest neighbors for given feature coordinates.

Parameters:

fm_acryomotl.Motl: A motl for which nearest neighbors are to be found.
fm_nncryomotl.Motl: A motl in which the nearest neighbors will be searched for.
nn_numberint, default=1: The number of nearest neighbors to retrieve for each feature. Default is 1.

Returns:

ordered_idxndarray: An array of indices corresponding to the ordered features in fm_a.
nn_idxndarray: A 2D array of shape (n_features, nn_count) containing the indices of the nearest neighbors for each feature in fm_a.
nn_distndarray: A 2D array of shape (n_features, nn_count) containing the distances to the nearest neighbors for each feature in fm_a.
nn_countint: The actual number of nearest neighbors retrieved, which is the minimum of nn_number and the number of available neighbors.
remove_qp: bool, default=False: Whether to remove nn correspodning to the query point. Should be set to True, if the function is called on the same motl.

Notes

This function uses a KDTree for efficient nearest neighbor search.

cryocat.analysis.nnana.get_feature_nn_within_radius(fm_a, fm_nn, radius, remove_qp=False)#

Get nearest neighbors within a specified radius from a set of coordinates which are feature specific.

Parameters:

fm_acryomotl.Motl: A motl for which nearest neighbors are to be found.
fm_nncryomotl.Motl: A motl in which the nearest neighbors will be searched for.
radiusfloat: The distance within which to search for nearest neighbors.
remove_qpbool, default=False: If True, the query point will be removed from nn_indices. Default is False.

Returns:

qp_indicesnumpy.ndarray: An array of indices representing the query particles for which neighbors are found.
nn_indiceslist of list of int: A list where each element is a list of indices of the nearest neighbors corresponding to each center index.

Notes

This function uses a KDTree for efficient spatial querying of nearest neighbors. If unique_only is set to True, it ensures that each neighbor is unique by removing duplicates.

cryocat.analysis.nnana.get_nn_distances(motl_a, motl_nn, pixel_size=1.0, nn_number=1, feature='tomo_id', rotation_type='angular_distance')#

Get nearest neighbor distances and related information between two sets of particles.

Parameters:

motl_astr or Motl: Path to the first motl file or a Motl object containing the first set of particles.
motl_nnstr or Motl: Path to the second motl file or a Motl object containing the second set of particles.
pixel_sizefloat, default=1.0: The size of a pixel in the same units as the coordinates. Default is 1.0.
nn_numberint, default=1: The number of nearest neighbors to consider. Default is 1.
featurestr, default=’tomo_id’: The feature to use for splitting the particles. Default is ‘tomo_id’.
rotation_typestr, default=’angular_distance’: The type of rotation distance to compute. Default is ‘angular_distance’.

Returns:

centered_coordnp.ndarray: The coordinates of the nearest neighbors centered around the reference particles.
rotated_coordnp.ndarray: The coordinates of the nearest neighbors after applying the rotation.
nn_distnp.ndarray: The distances to the nearest neighbors.
angular_distancesnp.ndarray: The angular distances between the reference particles and their nearest neighbors.
subtomo_idxnp.ndarray: The subtomo IDs of the reference motifs.
subtomo_idx_nnnp.ndarray: The subtomo IDs of the nearest neighbors.

Notes

This function assumes that the input motifs have angle information and that the motl files are compatible with the Motl class. The function will only work with the intersection of features present in both motls.

cryocat.analysis.nnana.get_nn_rotations(motl_a, motl_nn, nn_number=1, feature='tomo_id', type_id='geom1')#

Get nearest neighbor rotations based on specified features from two motl objects.

Parameters:

motl_astr or Motl: The path to the first motl file or a Motl object containing the first set of data.
motl_nnstr or Motl: The path to the second motl file or a Motl object containing the nearest neighbor data.
nn_numberint, default=1: The number of nearest neighbors to consider for each feature. Dfault is 1.
featurestr, default=’tomo_id’: The feature used to identify unique elements in the motl data. Default is ‘tomo_id’.
type_idstr, default=’geom1’: The type identifier for the geometry. Default is ‘geom1’.

Returns:

points_on_spherendarray: An array of points on the sphere representing the rotations.
anglesndarray: An array of Euler angles corresponding to the computed rotations in degrees.

Notes

This function assumes that the input motl objects or paths contain the necessary data and that the get_motl_subset and get_angles methods are available for the Motl class.

cryocat.analysis.nnana.get_nn_stats(motl_a, motl_nn, pixel_size=1.0, feature_id='tomo_id', nn_number=1, rotation_type='angular_distance')#

For each particle in motl_a, this function computes nn_number nearest neighbors in motl_nn and returns the associated data: distance of neighbor to query point, coordinates of nearest neighbors, coordinates of nearest neighbors after being rotated with respect to the coordinate frame of the query point, angular distance between query point and nearest neighbor, representations of associated rotation via rotated unit vector + Euler angles, subtomogram-id of query point of its associated nearest neighbors.

Parameters:

motl_acryocat.cryomotl.Motl or str: Input particle list of query points.
motl_nncryocat.cryomotl.Motl or str: Input particle list of with nearest neighbors of interest.
pixel_sizefloat, default=1.0: Pixel size. Defaults to 1.0.
feature_idstr, default=’tomo_id’: Particle list feature to distinguish between subsets of input motls. Defaults to “tomo_id”.
nn_numberint, default=1: Number of requested nearest neighbors in motl_nn for each particle in motl_a. Defaults to 1.
rotation_typestr, default=’angular_distance’: For comparison of rotations. Choice between “all”, “angular_distance”, “cone_distance”, and “in_plane_distance”. Defaults to “angular_distance”.

Returns:

pandas dataframe: Contains statistics of nearest neighbors analysis between input particle lists.

cryocat.analysis.nnana.get_nn_stats_within_radius(input_motl, nn_radius, feature='tomo_id', index_by_feature=True)#

Get nearest neighbor statistics within a specified radius from a given input motl.

Parameters:

input_motlstr or Motl object: Path to the input motl file or Motl object to be loaded.
nn_radiusfloat: The radius within which to search for nearest neighbors.
featurestr, default=’tomo_id’: The feature to index by. Default is ‘tomo_id’.
index_by_featurebool, default=True: If True, the output will be indexed by the specified feature; otherwise, it will be indexed by the original df of the motl. Default is True.

Returns:

pd.DataFrame: A DataFrame containing the nearest neighbor statistics, including: - qp_subtomo_id: Subtomo ID of the query point. - nn_subtomo_id: Subtomo ID of the nearest neighbor. - coord_x, coord_y, coord_z: Coordinates of the centered neighbor. - coord_rx, coord_ry, coord_rz: Rotated coordinates of the neighbor. - angular_distance: Angular distance between the query and nearest neighbor. - cone_distance: Cone distance between the query and nearest neighbor. - inplane_distance: In-plane distance between the query and nearest neighbor. - rot_x, rot_y, rot_z: Rotation angles of the nearest neighbor. - phi, theta, psi: Euler angles of the nearest neighbor. - qp_motl_id: Motl index of the query point. - nn_motl_idx: Motl index of the nearest neighbor.

cryocat.analysis.nnana.get_nn_within_distance(feature_motl, radius, unique_only=True)#

Get nearest neighbors within a specified distance from a set of coordinates.

Parameters:

feature_motlcryomotl.Motl: A motl for which each particle should be analyzed.
radiusfloat: The distance within which to search for nearest neighbors.
unique_onlybool, default=True: If True, only unique nearest neighbors are returned. Default is True.

Returns:

center_idxnumpy.ndarray: An array of indices representing the center particles for which neighbors are found.
nn_idxlist of list of int: A list where each element is a list of indices of the nearest neighbors corresponding to each center index.

Notes

This function uses a KDTree for efficient spatial querying of nearest neighbors. If unique_only is set to True, it ensures that each neighbor is unique by removing duplicates.

cryocat.analysis.nnana.get_nn_within_radius(motl_a, motl_nn, nn_radius, pixel_size=1.0, feature='tomo_id')#

Get the number of nearest neighbors within a specified radius for features in two motls.

Parameters:

motl_astr or Motl: Path to the first Motl file or a Motl object containing the particles to analyze.
motl_nnstr or Motl: Path to the second Motl file or a Motl object containing the particles for NN search.
nn_radiusfloat: The radius within which to count the nearest neighbors.
pixel_sizefloat, default=1.0: The size of the pixel/voxel that corresponds to the motls. Default is 1.0.
featurestr, default=’tomo_id’: The feature identifier to use for matching between the two motls. Default is ‘tomo_id’.

Returns:

numpy.ndarray: An array containing the count of nearest neighbors for each particle in the first motl within the specified radius.

cryocat.analysis.nnana.plot_nn_coord(coord, displ_threshold=None, marker_size=20)#

Plot 2D scatter distributions of 3D coordinates.

Parameters:

coordnumpy.ndarray: A 2D array of shape (n, 3) where n is the number of points and each row represents a point in 3D space (x, y, z).
displ_thresholdfloat, optional: A threshold value to set the limits of the scatter plots. If provided, the x and y limits of each subplot will be set to [-displ_threshold, displ_threshold]. Default is None.
marker_sizeint, default=20: The size of the markers in the scatter plots. Default is 20.

Returns:

None: This function does not return any value. It displays the scatter plots of the coordinates.

cryocat.analysis.nnana.plot_nn_coord_df(df, circle_radius, output_name=None, displ_threshold=None, title=None, marker_size=20)#

Plot 2D scatter plots of nearest neighbor coordinates.

Parameters:

dfpandas.DataFrame: DataFrame containing the coordinates with columns ‘coord_x’, ‘coord_y’, and ‘coord_z’.
circle_radiusfloat: Radius of the circles to be drawn on the plots.
output_namestr, optional: Name of the file to save the figure. If None, the figure will not be saved. Default is None.
displ_thresholdfloat, optional: Threshold for displaying limits on the axes. If None, limits will not be set. Default is None.
titlestr, optional: Title for the entire figure. If None, no title will be set. Default is None.
marker_sizeint, default=20: Size of the markers in the scatter plots. Default is 20.

Returns:

None: The function displays the plots and optionally saves the figure to a file.

cryocat.analysis.nnana.plot_nn_rot_coord_df(df, output_name=None, displ_threshold=None, title=None, marker_size=20)#

Plot 2D scatter plots of nearest neighbor coordinates that are rotated to the reference frame.

Parameters:

dfpandas.DataFrame: DataFrame containing the coordinates with columns ‘coord_x’, ‘coord_y’, and ‘coord_z’.
output_namestr, optional: Name of the file to save the figure. If None, the figure will not be saved. Default is None.
displ_thresholdfloat, optional: Threshold for displaying limits on the axes. If None, limits will not be set. Default is None.
titlestr, optional: Title for the entire figure. If None, no title will be set. Default is None.
marker_sizeint, default=20: Size of the markers in the scatter plots. Default is 20.

Returns:

None: The function displays the plots and optionally saves the figure to a file.

cryocat.analysis.nnana.plot_nn_rot_coord_df_plotly(df, coord_columns, desc, displ_threshold=None, title=None, marker_size=5, output_name=None)#

Create 2D scatter plots of rotated NN coordinates using Plotly (XY, XZ, YZ).

Parameters:

dfpd.DataFrame: DataFrame with columns ‘coord_rx’, ‘coord_ry’, ‘coord_rz’, and ‘type’.
coord_columnslist: List of names with columns to use for display, in x, y, z order.
descstr: Name of the column to use as description for the points.
displ_thresholdfloat, optional: Axis limit for all plots (symmetric), default: None.
titlestr, optional: Overall figure title.
marker_sizeint: Size of scatter markers.
output_namestr, optional: If given, saves the figure as HTML or image.

Returns:

plotly.graph_objects.Figure: A Plotly figure with 3 subplots.