topostats.scars#

Contains image artefact correction functions that take a 2D np.ndarray image, and return the image with interpolated values filling the space of any detected scars.

Attributes#

LOGGER

Functions#

_mark_if_positive_scar(→ None)

Determine if the points below and including the pixel at the specified row and column are a positive scar (a

_mark_if_negative_scar(→ None)

Determine if the points below and including the pixel at the specified row and column are a negative scar (a

_spread_scars(→ None)

Spread high-marked pixels into adjacent low-marked pixels. This is a smudging function that attempts to catch

_remove_short_scars(→ None)

Removes scars that are too short (horizontally), based on the min_scar_length argument.

_mark_scars(→ numpy.ndarray)

Mark scars within an image, returning a boolean 2D np.ndarray of pixels that have been detected as scars.

_remove_marked_scars(→ None)

Interpolate values covered by marked scars. Takes an image, and a marked scar boolean mask for that

remove_scars(img, filename[, removal_iterations, ...])

Remove scars from an image.

Module Contents#

topostats.scars.LOGGER#
topostats.scars._mark_if_positive_scar(row_col: tuple, stddev: float, img: numpy.ndarray, marked: numpy.ndarray, threshold_low: float, max_scar_width: int) → None[source]#

Determine if the points below and including the pixel at the specified row and column are a positive scar (a ridge rather than a dip). If they are, mark them in the marked 2d np.ndarray. Note that this only detects positive scars. :param row_col: A tuple containing the row and column indices of the pixel for the top of the potential scar. Note that

the first value is the row index, and the second is the column index.

Parameters:

  • stddev (float) – The standard deviation, or the root-mean-square value for the image.

  • img (np.ndarray) – A 2-D image of the data to remove scars from.

  • marked (np.ndarry) – A 2-D image of pixels that stores the positions of scars marked for removal. The value of the pixel is a floating point value that represents how strongly the algorithm considers it to be a scar. This may or may not already contain non-zero values given that previous iterations of scar removal may have been performed.

  • threshold_low (float) – A value that when multiplied with the standard deviation, acts as a threshold to determine if an increase or decrease in height might constitute the top or bottom of a scar.

  • max_scar_width (int) – A value that dictates the maximum width that a scar can be. Note that this does not mean horizontal width, rather vertical, this is because we conside scars to be laying flat, horizontally, so their width is vertical and their length is horizontal.

Return type:

None

topostats.scars._mark_if_negative_scar(row_col: tuple, stddev: float, img: numpy.ndarray, marked: numpy.ndarray, threshold_low: float, max_scar_width: int) → None[source]#

Determine if the points below and including the pixel at the specified row and column are a negative scar (a dip rather than a ridge). If they are, mark them in the marked 2d np.ndarray. Note that this only detects negative scars.

Parameters:

  • row_col (tuple) – A tuple containing the row and column indices of the pixel for the top of the potential scar. Note that the first value is the row index, and the second is the column index.

  • stddev (float) – The standard deviation, or the root-mean-square value for the image.

  • img (np.ndarray) – A 2-D image of the data to remove scars from.

  • marked (np.ndarry) – A 2-D image of pixels that stores the positions of scars marked for removal. The value of the pixel is a floating point value that represents how strongly the algorithm considers it to be a scar. This may or may not already contain non-zero values given that previous iterations of scar removal may have been performed.

  • threshold_low (float) – A value that when multiplied with the standard deviation, acts as a threshold to determine if an increase or decrease in height might constitute the top or bottom of a scar.

  • max_scar_width (int) – A value that dictates the maximum width that a scar can be. Note that this does not mean horizontal width, rather vertical, this is because we conside scars to be laying flat, horizontally, so their width is vertical and their length is horizontal.

Return type:

None

topostats.scars._spread_scars(marked: numpy.ndarray, threshold_low: float, threshold_high: float) → None[source]#

Spread high-marked pixels into adjacent low-marked pixels. This is a smudging function that attempts to catch any pixels that are parts of scars that might not have been extreme enough to get marked above the high_threshold. Any remaining marked pixels below high_threshold are considered not to be scars and are removed from the mask.

Parameters:

  • marked (np.ndarray) – A 2-D image of pixels that stores the positions of scars marked for removal. The value of the pixel is a floating point value that represents how strongly the algorithm considers it to be a scar. This may or may not already contain non-zero values given that previous iterations of scar removal may have been performed.

  • threshold_low (float) – A floating point value, that when multiplied by the standard deviation of the image, acts as a threshold for sharp inclines or descents in pixel values and thus marks potential scars. A lower value will make the algorithm more sensitive, and a higher value will make it less sensitive.

  • threshold_high (float) – A floating point value that is used similarly to threshold_low, however sharp inclines or descents that result in values in the mask higher than this threshold are automatically considered scars.

Return type:

None

topostats.scars._remove_short_scars(marked: numpy.ndarray, threshold_high: float, min_scar_length: int) → None[source]#

Removes scars that are too short (horizontally), based on the min_scar_length argument.

Parameters:

  • marked (np.ndarray) – A 2-D image of pixels that stores the positions of scars marked for removal. The value of the pixel is a floating point value that represents how strongly the algorithm considers it to be a scar. This may or may not already contain non-zero values given that previous iterations of scar removal may have been performed.

  • threshold_high (float) – A floating point value that is used similarly to threshold_low, however sharp inclines or descents that result in values in the mask higher than this threshold are automatically considered scars.

  • min_scar_length (int) – A value that dictates the maximum width that a scar can be. Note that this does not mean horizontal width, rather vertical, this is because we conside scars to be laying flat, horizontally, so their width is vertical and their length is horizontal.

Return type:

None

topostats.scars._mark_scars(img: numpy.ndarray, direction: str, threshold_low: float, threshold_high: float, max_scar_width: int, min_scar_length: int) → numpy.ndarray[source]#

Mark scars within an image, returning a boolean 2D np.ndarray of pixels that have been detected as scars.

Parameters:

  • img (np.ndarray) – A 2-D image of the data to detect scars in.

  • direction (str) – Options: ‘positive’, ‘negative’. The direction of scars to detect. For example, to detect scars that lie above the data, select ‘positive’.

  • threshold_low (float) – A floating point value, that when multiplied by the standard deviation of the image, acts as a threshold for sharp inclines or descents in pixel values and thus marks potential scars. A lower value will make the algorithm more sensitive, and a higher value will make it less sensitive.

  • threshold_high (float) – A floating point value that is used similarly to threshold_low, however sharp inclines or descents that result in values in the mask higher than this threshold are automatically considered scars.

  • max_scar_width (int) – An integer that restricts the algorithm to only mark scars that are as thin or thinner than this width. This is important for ensuring that legitimate grain data is not detected as scarred data. Note that width here is vertical, as scars are thin, horizontal features.

  • min_scar_length (int) – An integer that restricts the algorithm to only mark scars that are as long or longer than this length. This is important for ensuring that noise or legitimate but sharp datapoints do not get detected as scars. Note that length here is horizontal, as scars are thin, horizontal features.

Returns:

marked – Returns a 2-D image of the same shape as the data image, where each pixel’s value represents a metric for how strongly that pixel is considered to be a scar. Higher values mean more likely to be a scar.

Return type:

np.ndarray

topostats.scars._remove_marked_scars(img: numpy.ndarray, scar_mask: numpy.ndarray) → None[source]#

Interpolate values covered by marked scars. Takes an image, and a marked scar boolean mask for that image. Returns the image where the marked scars are replaced by interpolated values.

Parameters:

  • img (np.ndarray) – A 2-D image of the data to remove scars from.

  • scar_mask (np.ndarray) – A boolean image of pixels that determine which values are flagged as scars and therefore should be interpolated over in the original data image.

Return type:

None

topostats.scars.remove_scars(img: numpy.ndarray, filename: str, removal_iterations: int = 2, threshold_low: float = 0.25, threshold_high: float = 0.666, max_scar_width: int = 4, min_scar_length: int = 16)[source]#

Remove scars from an image. Scars are long, typically 1-4 pixels wide streaks of high or low data in AFM images. They are a problem resulting from random errors in the AFM data collection process and are hard to avoid. This function detects and removes these artefacts by interpolating over them between the pixels above and below them. This method takes no parameters as it uses parameters already established as instance variables when the class was instantiated.

Parameters:

  • img (np.ndarray) – A 2-D image to remove scars from.

  • filename (str) – The filename (used for logging outputs only).

  • removal_iterations (int) – The number of times the scar removal should run on the image. Running just once sometimes isn’t enough to remove some of the more difficult to remove scars.

  • threshold_low (float) – A value that when multiplied with the standard deviation, acts as a threshold to determine if an increase or decrease in height might constitute the top or bottom of a scar.

  • threshold_high (float) – A floating point value that is used similarly to threshold_low, however sharp inclines or descents that result in values in the mask higher than this threshold are automatically considered scars.

  • max_scar_width (int) – A value that dictates the maximum width that a scar can be. Note that this does not mean horizontal width, rather vertical, this is because we conside scars to be laying flat, horizontally, so their width is vertical and their length is horizontal.

  • min_scar_length (int) – An integer that restricts the algorithm to only mark scars taht are as long or longer than this length. This is important for ensuring that noise or legitimate but sharp datapoints do not get detected as scars. Note that length here is horizontal, as scars are thin, horizontal features.

Returns:

The original 2-D image with scars removed, unless the config has run set to False, in which case it will not remove the scars.

Return type:

self.img