topostats.utils#

Utilities.

Attributes#

LOGGER

COLUMN_SETS

Exceptions#

ResolutionError

Raised when the image resolution is too small for accuurate tracing.

Functions#

convert_path(→ pathlib.Path)

Ensure path is Path object.

update_config(→ dict)

Update the configuration with any arguments.

update_plotting_config(→ dict)

Update the plotting config for each of the plots in plot_dict.

_get_mask(→ numpy.typing.NDArray)

Calculate a mask for pixels that exceed the threshold.

get_mask(→ numpy.typing.NDArray)

Mask data that should not be included in flattening.

get_thresholds(→ dict)

Obtain thresholds for masking data points.

create_empty_dataframe(→ pandas.DataFrame)

Create an empty data frame for returning when no results are found.

bound_padded_coordinates_to_image(→ tuple)

Ensure the padding of coordinates points does not fall outside of the image shape.

convolve_skeleton(→ numpy.typing.NDArray)

Convolve skeleton with a 3x3 kernel.

coords_2_img(→ numpy.ndarray)

Convert coordinates to a binary image.

Module Contents#

topostats.utils.LOGGER#
topostats.utils.COLUMN_SETS#
topostats.utils.convert_path(path: str | pathlib.Path) → pathlib.Path[source]#

Ensure path is Path object.

Parameters:

path (str | Path) – Path to be converted.

Returns:

Pathlib object of path.

Return type:

Path

topostats.utils.update_config(config: dict, args: dict | argparse.Namespace) → dict[source]#

Update the configuration with any arguments.

Parameters:

  • config (dict) – Dictionary of configuration (typically read from YAML file specified with ‘-c/–config <filename>’).

  • args (Namespace) – Command line arguments.

Returns:

Dictionary updated with command arguments.

Return type:

dict

topostats.utils.update_plotting_config(plotting_config: dict) → dict[source]#

Update the plotting config for each of the plots in plot_dict.

Ensures that each entry has all the plotting configuration values that are needed.

Parameters:

plotting_config (dict) – Plotting configuration to be updated.

Returns:

Updated plotting configuration.

Return type:

dict

topostats.utils._get_mask(image: numpy.typing.NDArray, thresh: float, threshold_direction: str, img_name: str = None) → numpy.typing.NDArray[source]#

Calculate a mask for pixels that exceed the threshold.

Parameters:

  • image (np.array) – Numpy array representing image.

  • thresh (float) – A float representing the threshold.

  • threshold_direction (str) – A string representing the direction that should be thresholded. (“above”, “below”).

  • img_name (str) – Name of image being processed.

Returns:

Numpy array of image with objects coloured.

Return type:

npt.NDArray

topostats.utils.get_mask(image: numpy.typing.NDArray, thresholds: dict, img_name: str = None) → numpy.typing.NDArray[source]#

Mask data that should not be included in flattening.

Parameters:

  • image (npt.NDArray) – 2D Numpy array of the image to have a mask derived for.

  • thresholds (dict) – Dictionary of thresholds, at a bare minimum must have key ‘below’ with an associated value, second key is to have an ‘above’ threshold.

  • img_name (str) – Image name that is being masked.

Returns:

2D Numpy boolean array of points to mask.

Return type:

npt.NDArray

topostats.utils.get_thresholds(image: numpy.typing.NDArray, threshold_method: str, otsu_threshold_multiplier: float = None, threshold_std_dev: dict = None, absolute: dict = None, **kwargs) → dict[source]#

Obtain thresholds for masking data points.

Parameters:

  • image (npt.NDArray) – 2D Numpy array of image to be masked.

  • threshold_method (str) – Method for thresholding, ‘otsu’, ‘std_dev’ or ‘absolute’ are valid options.

  • otsu_threshold_multiplier (float) – Scaling value for Otsu threshold.

  • threshold_std_dev (dict) – Dict of above and below thresholds for the standard deviation method.

  • absolute (tuple) – Dict of below and above thresholds.

  • **kwargs – Dictionary passed to ‘topostats.threshold(**kwargs)’.

Returns:

Dictionary of thresholds, contains keys ‘below’ and optionally ‘above’.

Return type:

dict

topostats.utils.create_empty_dataframe(column_set: str = 'grainstats', index_col: str = 'grain_number') → pandas.DataFrame[source]#

Create an empty data frame for returning when no results are found.

Parameters:

  • column_set (str) – The name of the set of columns for the empty dataframe.

  • index_col (str) – Column to set as index of empty dataframe.

Returns:

Empty Pandas DataFrame.

Return type:

pd.DataFrame

topostats.utils.bound_padded_coordinates_to_image(coordinates: numpy.typing.NDArray, padding: int, image_shape: tuple) → tuple[source]#

Ensure the padding of coordinates points does not fall outside of the image shape.

This function is primarily used in the dnaTrace.get_fitted_traces() method which aims to adjust the points of a skeleton to sit on the highest points of a traced molecule. In order to do so it takes the ordered skeleton, which may not lie on the highest points as it is generated from a binary mask that is unaware of the heights, and then defines a padded boundary of 3nm profile perpendicular to the backbone of the DNA (which at this point is the skeleton based on a mask). Each point along the skeleton therefore needs padding by a minimum of 2 pixels (in this case each pixel equates to a cell in a NumPy array). If a point is within 2 pixels (i.e. 2 cells) of the border then we can not pad beyond this region, we have to stop at the edge of the image and so the coordinates is adjusted such that the padding will lie on the edge of the image/array.

Parameters:

  • coordinates (npt.NDArray) – Coordinates of a point on the mask based skeleton.

  • padding (int) – Number of pixels/cells to pad around the point.

  • image_shape (tuple) – The shape of the original image from which the pixel is obtained.

Returns:

Returns a tuple of coordinates that ensure that when the point is padded by the noted padding width in subsequent calculations it will not be outside of the image shape.

Return type:

tuple

topostats.utils.convolve_skeleton(skeleton: numpy.typing.NDArray) → numpy.typing.NDArray[source]#

Convolve skeleton with a 3x3 kernel.

This produces an array where the branches of the skeleton are denoted with ‘1’, endpoints are denoted as ‘2’, and pixels at nodes as ‘3’.

Parameters:

skeleton (npt.NDArray) – Single pixel thick binary trace(s) within an array.

Returns:

The skeleton (=1) with endpoints (=2), and crossings (=3) highlighted.

Return type:

npt.NDArray

exception topostats.utils.ResolutionError[source]#

Bases: Exception

Raised when the image resolution is too small for accuurate tracing.

topostats.utils.coords_2_img(coords, image, ordered=False) → numpy.ndarray[source]#

Convert coordinates to a binary image.

Parameters:

  • coords (np.ndarray) – An array of 2xN integer coordinates.

  • image (np.ndarray) – An MxL array to assign the above coordinates onto.

  • ordered (bool, optional) – If True, incremements the value of each coord to show order.

Returns:

An array the same shape as ‘image’ with the coordinates highlighted.

Return type:

np.ndarray