topostats.grainstats#
Contains class for calculating the statistics of grains - 2d raster images.
Attributes#
Classes#
Class for calculating grain stats. |
Functions#
|
Create an empty data frame for returning when no results are found. |
Module Contents#
- topostats.grainstats.LOGGER_NAME = 'topostats'#
- topostats.grainstats.create_empty_dataframe(columns: set = ALL_STATISTICS_COLUMNS, index: str = 'molecule_number') pandas.DataFrame [source]#
Create an empty data frame for returning when no results are found.
- Parameters:
columns (list) – Columns of the empty dataframe.
index (str) – Column to set as index of empty dataframe.
- Returns:
Empty Pandas DataFrame.
- Return type:
pd.DataFrame
- topostats.grainstats.LOGGER#
- topostats.grainstats.GRAIN_STATS_COLUMNS = ['molecule_number', 'centre_x', 'centre_y', 'radius_min', 'radius_max', 'radius_mean',...#
- class topostats.grainstats.GrainStats(data: numpy.typing.NDArray, labelled_data: numpy.typing.NDArray, pixel_to_nanometre_scaling: float, direction: str, base_output_dir: str | pathlib.Path, image_name: str = None, edge_detection_method: str = 'binary_erosion', extract_height_profile: bool = False, cropped_size: float = -1, plot_opts: dict = None, metre_scaling_factor: float = 1e-09)[source]#
Class for calculating grain stats.
- Parameters:
data (npt.NDArray) – 2D Numpy array containing the flattened afm image. Data in this 2D array is floating point.
labelled_data (npt.NDArray) – 2D Numpy array containing all the grain masks in the image. Data in this 2D array is boolean.
pixel_to_nanometre_scaling (float) – Floating point value that defines the scaling factor between nanometres and pixels.
direction (str) – Direction for which grains have been detected (“above” or “below”).
base_output_dir (Path) – Path to the folder that will store the grain stats output images and data.
image_name (str) – The name of the file being processed.
edge_detection_method (str) – Method used for detecting the edges of grain masks before calculating statistics on them. Do not change unless you know exactly what this is doing. Options: “binary_erosion”, “canny”.
extract_height_profile (bool) – Extract the height profile.
cropped_size (float) – Length of square side (in nm) to crop grains to.
plot_opts (dict) – Plotting options dictionary for the cropped grains.
metre_scaling_factor (float) – Multiplier to convert the current length scale to metres. Default: 1e-9 for the usual AFM length scale of nanometres.
- static get_angle(point_1: tuple, point_2: tuple) float [source]#
Calculate the angle in radians between two points.
- Parameters:
point_1 (tuple) – Coordinate vectors for the first point to find the angle between.
point_2 (tuple) – Coordinate vectors for the second point to find the angle between.
- Returns:
The angle in radians between the two input vectors.
- Return type:
float
- static is_clockwise(p_1: tuple, p_2: tuple, p_3: tuple) bool [source]#
Determine if three points make a clockwise or counter-clockwise turn.
- Parameters:
p_1 (tuple) – First point to be used to calculate turn.
p_2 (tuple) – Second point to be used to calculate turn.
p_3 (tuple) – Third point to be used to calculate turn.
- Returns:
Indicator of whether turn is clockwise.
- Return type:
boolean
- calculate_stats()[source]#
Calculate the stats of grains in the labelled image.
- Returns:
Consists of a pd.DataFrame containing all the grain stats that have been calculated for the labelled image and a list of dictionaries containing grain data to be plotted.
- Return type:
tuple
- static calculate_points(grain_mask: numpy.typing.NDArray) list [source]#
Convert a 2D boolean array to a list of coordinates.
- Parameters:
grain_mask (npt.NDArray) – A 2D numpy array image of a grain. Data in the array must be boolean.
- Returns:
A python list containing the coordinates of the pixels in the grain.
- Return type:
list
- static calculate_edges(grain_mask: numpy.typing.NDArray, edge_detection_method: str) list [source]#
Convert 2D boolean array to list of the coordinates of the edges of the grain.
- Parameters:
grain_mask (npt.NDArray) – A 2D numpy array image of a grain. Data in the array must be boolean.
edge_detection_method (str) – Method used for detecting the edges of grain masks before calculating statistics on them. Do not change unless you know exactly what this is doing. Options: “binary_erosion”, “canny”.
- Returns:
List containing the coordinates of the edges of the grain.
- Return type:
list
- calculate_radius_stats(edges: list, points: list) tuple[float] [source]#
Calculate the radius of grains.
The radius in this context is the distance from the centroid to points on the edge of the grain.
- Parameters:
edges (list) – A 2D python list containing the coordinates of the edges of a grain.
points (list) – A 2D python list containing the coordinates of the points in a grain.
- Returns:
A tuple of the minimum, maximum, mean and median radius of the grain.
- Return type:
tuple[float]
- static _calculate_centroid(points: numpy.array) tuple [source]#
Calculate the centroid of a bounding box.
- Parameters:
points (list) – A 2D python list containing the coordinates of the points in a grain.
- Returns:
The coordinates of the centroid.
- Return type:
tuple
- static _calculate_displacement(edges: numpy.typing.NDArray, centroid: tuple) numpy.typing.NDArray [source]#
Calculate the displacement between the edges and centroid.
- Parameters:
edges (npt.NDArray) – Coordinates of the edge points.
centroid (tuple) – Coordinates of the centroid.
- Returns:
Array of displacements.
- Return type:
npt.NDArray
- static _calculate_radius(displacements: list[list]) numpy.typing.NDarray [source]#
Calculate the radius of each point from the centroid.
- Parameters:
displacements (List[list]) – A list of displacements.
- Returns:
Array of radii of each point from the centroid.
- Return type:
npt.NDarray
- convex_hull(edges: list, base_output_dir: pathlib.Path, debug: bool = False) tuple[list, list, list] [source]#
Calculate a grain’s convex hull.
Based off of the Graham Scan algorithm and should ideally scale in time with O(nlog(n)).
- Parameters:
edges (list) – A python list containing the coordinates of the edges of the grain.
base_output_dir (Path) – Directory to save output to.
debug (bool) – Default false. If true, debug information will be displayed to the terminal and plots for the convex hulls and edges will be saved.
- Returns:
A hull (list) of the coordinates of each point on the hull. Hull indices providing a way to find the points from the hill inside the edge list that was passed. Simplices (list) of tuples each representing a simplex of the convex hull, these are sorted in a counter-clockwise order.
- Return type:
tuple[list, list, list]
- calculate_squared_distance(point_2: tuple, point_1: tuple = None) float [source]#
Calculate the squared distance between two points.
Used for distance sorting purposes and therefore does not perform a square root in the interests of efficiency.
- Parameters:
point_2 (tuple) – The point to find the squared distance to.
point_1 (tuple) – Optional - defaults to the starting point defined in the graham_scan() function. The point to find the squared distance from.
- Returns:
The squared distance between the two points.
- Return type:
float
- sort_points(points: list) list [source]#
Sort points in counter-clockwise order of angle made with the starting point.
- Parameters:
points (list) – A python list of the coordinates to sort.
- Returns:
Points (coordinates) sorted counter-clockwise.
- Return type:
list
- get_start_point(edges: numpy.typing.NDArray) None [source]#
Determine the index of the bottom most point of the hull when sorted by x-position.
- Parameters:
edges (npt.NDArray) – Array of coordinates.
- graham_scan(edges: list) tuple[list, list, list] [source]#
Construct the convex hull using the Graham Scan algorithm.
Ideally this algorithm will take O( n * log(n) ) time.
- Parameters:
edges (list) – A python list of coordinates that make up the edges of the grain.
- Returns:
A hull (list) of the coordinates of each point on the hull. Hull indices providing a way to find the points from the hill inside the edge list that was passed. Simplices (list) of tuples each representing a simplex of the convex hull, these are sorted in a counter-clockwise order.
- Return type:
tuple[list, list, list]
- static plot(edges: list, convex_hull: list = None, file_path: pathlib.Path = None) None [source]#
Plot and save the coordinates of the edges in the grain and optionally the hull.
- Parameters:
edges (list) – A list of points to be plotted.
convex_hull (list) – Optional argument. A list of points that form the convex hull. Will be plotted with the coordinates if provided.
file_path (Path) – Path of the file to save the plot as.
- calculate_aspect_ratio(edges: list, hull_simplices: numpy.typing.NDArray, path: pathlib.Path, debug: bool = False) tuple [source]#
Calculate the width, length and aspect ratio of the smallest bounding rectangle of a grain.
- Parameters:
edges (list) – A python list of coordinates of the edge of the grain.
hull_simplices (npt.NDArray) – A 2D numpy array of simplices that the hull is comprised of.
path (Path) – Path to the save folder for the grain.
debug (bool) – If true, various plots will be saved for diagnostic purposes.
- Returns:
The smallest_bouning_width (float) in pixels (not nanometres) of the smallest bounding rectangle for the grain. The smallest_bounding_length (float) in pixels (not nanometres), of the smallest bounding rectangle for the grain. And the aspect_ratio (float) the width divided by the length of the smallest bounding rectangle for the grain. It will always be greater or equal to 1.
- Return type:
tuple
- static find_cartesian_extremes(rotated_points: numpy.typing.NDArray) dict [source]#
Find the limits of x and y of rotated points.
- Parameters:
rotated_points (npt.NDArray) – 2-D array of rotated points.
- Returns:
Dictionary of the x and y min and max.__annotations__.
- Return type:
Dict
- static get_shift(coords: numpy.typing.NDArray, shape: numpy.typing.NDArray) int [source]#
Obtain the coordinate shift to reflect the cropped image box for molecules near the edges of the image.
- Parameters:
coords (npt.NDArray) – Value representing integer coordinates which may be outside of the image.
shape (npt.NDArray) – Array of the shape of an image.
- Returns:
Max value of the shift to reflect the croped region so it stays within the image.
- Return type:
np.int64
- get_cropped_region(image: numpy.typing.NDArray, length: int, centre: numpy.typing.NDArray) numpy.typing.NDArray [source]#
Crop the image with respect to a given pixel length around the centre coordinates.
- Parameters:
image (npt.NDArray) – The image array.
length (int) – The length (in pixels) of the resultant cropped image.
centre (npt.NDArray) – The centre of the object to crop.
- Returns:
Cropped array of the image.
- Return type:
npt.NDArray