Identify pixel content

Determines the type of content displayed by each pixel in the image, categorizing it as tissue from tissue segments or fragments, artifacts, or background.

identifyPixelContent(object, ...)

# S4 method for class 'SPATA2'
identifyPixelContent(
  object,
  method = "otsu",
  img_name = activeImage(object),
  sigma = 0,
  percentile = 0,
  compactness_factor = 10,
  superpixel = 600,
  eps = 1.414 * 2,
  minPts = 0.005,
  frgmt_threshold = c(0.001, 0.05),
  verbose = TRUE
)

# S4 method for class 'SpatialData'
identifyPixelContent(
  object,
  method = "otsu",
  sigma = 0,
  img_name = activeImage(object),
  percentile = 0,
  compactness_factor = 10,
  superpixel = 1000,
  eps = 1.414 * 2214,
  minPts = 0.005,
  frgmt_threshold = c(0.001, 0.05),
  verbose = TRUE
)

# S4 method for class 'HistoImage'
identifyPixelContent(
  object,
  method = "otsu",
  sigma = 0,
  percentile = 0,
  compactness_factor = 10,
  superpixel = 1000,
  eps = 1.414 * 2214,
  minPts = 0.005,
  frgmt_threshold = c(0.001, 0.05),
  verbose = TRUE
)

# S4 method for class 'Image'
identifyPixelContent(
  object,
  method = "otsu",
  sigma = 0,
  percentile = 0,
  compactness_factor = 10,
  superpixel = 1000,
  frgmt_threshold = c(0.001, 0.05),
  eps = 1.414 * 2214,
  minPts = 0.005,
  verbose = TRUE,
  ...
)

Arguments

object

An object of class SPATA2 or, in case of S4 generics, objects of classes for which a method has been defined.

...

Used to absorb deprecated arguments or functions.

method

Character value. The method to use. Either 'otsu' or 'sps'. See details for more information. Defaults to 'otsu'. ('sps' takes significantly longer, only recommened if 'otsu' does not provide any useful results).

img_name

Character value. The name of the image of interest. If NULL, the active image is chosen by default. Either way, must be one of getImageNames().

sigma

Numeric value specifying the standard deviation for the Gaussian blur applied to the grayscale image. Higher values result in more smoothing. 0 skips smoothing. Default is 0.

percentile

Numeric value between 0 and 100 (inclusive) specifying the percentile threshold for background color determination. If bigger than 0, it determines the top percentile of colors to identify as background based on the frequency they appear in the image. This can improve identifying tissue pixels in images where the edge between tissue and background is continuous rather than sharp and thus difficult to identify using computational approaches. It follows the hypothesis that the background consists of many pixels of equal color while the tissue consists of pixels of heterogenous colors.

Values between 0-100 are valid. Usually values between 0.5-2.5 work well. Test resuls with plotPixelContent().

compactness_factor

Numeric value controlling the compactness of superpixels. Given as an argument to $spixel_segmentation() function.

superpixel

Numeric value specifying the number of superpixels to compute. Given as an argument to $spixel_segmentation() function. Increased values can improve the output but increase runtime.

eps

Numeric value specifying the value of eps parameter used in dbscan::dbscan() when applied on the tissue pixels. If the value is less than 1, it is calculated as a percentage of the width or height of the image, depending on which is larger. If the value is greater than or equal to 1, it is taken as an absolute value.

Defaults to 1.41422, twice the distance between two diagonally adjacent pixels in a uniform pixel space.

minPts

Numeric value specifying the value of minPts parameter used in dbscan::dbscan() when applied on the tissue pixels identified as potential tissue. If the value is less than 1, it is calculated as a percentage of the width or height of the image, depending on which is larger. If the value is greater than or equal to 1, it is taken as an absolute value.

Defaults to 0.005, which is 0.5% of the total number of pixels.

frgmt_threshold

Numeric vector of length 2 specifying the range of the number of pixels an identified non-background-object in the image must have to be considered a tissue fragment. Objects with a lower number of pixels than the minimum threshold are considered artifacts, and objects with a higher number of pixels than the maximum threshold are considered tissue sections. If a threshold value is less than 1, it is calculated as a percentage of the total number of pixels in the image. If a threshold value is greater than or equal to 1, it is taken as an absolute value.

verbose

Logical. If TRUE, informative messages regarding the computational progress will be printed.

(Warning messages will always be printed.)

Value

The method for class Image returns a data.frame of the following variables.

  • pixel: character. Pixel index.

  • width: numeric. Pixel position on horizontal axis of the image.

  • height: numeric. Pixel position on the vertical axis of the image.

  • clusterK2: character. Either 'background' or 'tissue'. (if method = 'sps')

  • colTiss# : numeric. Numeric variables that correspond to the color dimensions of the image mask based on which the clustering of clusterK2 was conducted. (if method = 'sps')

  • clusterDBSCAN: character. Cluster results of dbscan::dbscan() after removal of background pixels.

  • clusterDBSCAN_size:numeric. Size of each dbscan cluster.

  • content: character. The identified content of each pixel.

Methods for S4-classes serving as containers return the input object with the the results stored in the corresponding slots.

Details

This function classifies pixels in an image as tissue, background, or artifacts using two primary methods: Otsu's method or Superpixel Segmentation (SPS), followed by DBSCAN clustering for refinement.

  • Otsu's Method: Applies global thresholding to separate tissue from the background using Otsu's method, which minimizes intra-class variance. Parameters that affect the output: sigma

  • Superpixel Segmentation (SPS): Divides the image into superpixels using the SLIC algorithm. Superpixels are classified into tissue or background using k-means clustering. Parameters that affect the output: percentile, compactness_factor, superpixel

The resulting binary image is refined with DBSCAN clustering to identify contiguous tissue sections, fragments, and artifacts.

Note

If img_name specifies multiple images, the function iterates over all of them. If it is NULL the active image is picked.

References

Nobuyuki Otsu, "A threshold selection method from gray-level histograms". IEEE Trans. Sys., Man., Cyber. 9 (1): 62-66. doi:10.1109/TSMC.1979.4310076 (1979)

See also

For subsequent image processing: identifyTissueOutline(..., method = 'image'). For visualization of results: plotImageMask(), plotPixelContent(). For extraction of results: getPixelDf().