plotImageAnnotations: Plot image annotations

In kueckelj/SPATA2: A Toolbox for Spatial Gene Expression Analysis

Plot image annotations

Description

Plots structures and areas that were annotated with createImageAnnotations().

Usage

plotImageAnnotations(
  object,
  ids = NULL,
  tags = NULL,
  test = "any",
  expand = "25%",
  square = TRUE,
  encircle = TRUE,
  inner = TRUE,
  unit = getSpatialMethod(object)@unit,
  round = 2,
  line_color = "black",
  line_size = 1.5,
  line_type = "solid",
  fill = "orange",
  alpha = 0.25,
  sb_dist = FALSE,
  display_title = FALSE,
  display_subtitle = TRUE,
  display_caption = FALSE,
  ggpLayers = list(),
  nrow = NULL,
  ncol = NULL,
  plot = TRUE,
  ...
)

Arguments

object	An object of class spata2.
ids	Character vector or NULL. If character, specifies the IDs of the image annotations of interest. If numeric, the image annotations are picked by number. If NULL, all image annotations are included - subsequent selection with tags and test is possible.
tags	Character vector or NULL. If character, the tags for the image annotation selection. See section Selection of image annotation with tags for more information.
test	Character value. One of any. all, identical, not_identical and none. Specifies how input for tags is used to select image annotations. See section Selection of image annotation with tags for more information.
expand	Specifies image expansion. An image that is cropped based on an image annotation centers around the image annotation. If expand = 0, the default, the dimensions of the image, that is width/x-axis and height/y-axis, are set to include only the image annotation area and nothing more. Using expand, the cropped image section can be adjusted. See section Expansion of cropped image sections for more information.
square	Logical value. Most image annotations come in variable shapes and have different horizontal and vertical diameters. Therefore, height and width of the image section are usually not equal. If square = TRUE, the cropped section of the image that contains the annotated structure is forced into a square: the bigger diameter of both is taken as default. E.g. if the horizontal diameter of the image annotation is 1mm and the vertical diameter is 1.5mm, the output image will have height and width of 1.5mm. That is, in terms of coordinates, an x-range and a y-range of 1.5mm. Processing of the image output depending on argument expand happens afterwards.
encircle	Logical value. If TRUE, a polygon is drawn around the exact extent of the annotated structure encircled drawn in createImageAnnotations().
inner	Logical value. Only applies if an image annotation contains a secondary image annotation within its own area. If FALSE, the inner borders of the image annotation are not included in the output.
unit	Character value. The unit in which the x- and y-axis text are displayed. Use validUnitsOfLengthSI() to obtain all valid input options.
round	Numeric value or FALSE. If numeric and unit is not px, rounds axes text.
line_color	Character. Affects color of the main lines of the plot.
line_size	Numeric. Affects size of the main lines of the plot.
line_type	Character. The line type. One of 'blank', 'solid', 'dashed', 'dotted', 'dotdash', 'longdash' and 'twodash'.
sb_dist	Distance measure or FALSE. If distance measure, defines the distance in SI units that a scale bar illustrates. Scale bar is plotted with ggpLayerScaleBarSI(). If FALSE, no scale bar is plotted.
display_title	Logical value. If TRUE, the number of each image annotation is plotted in the title.
display_subtitle	Logical value. If TRUE, the ID of each image annotation is plotted in the subtitle.
display_caption	Logial value. If TRUE, the tags of each image annotation are plotted in the caption.
ggpLayers	List of ggproto-objects that are added to each plot. Skim ggpLayer*()-functions for more options.
nrow, ncol	Numeric values or NULL. Used to arrange multiple plots.
plot	Logical value. If TRUE, the plots are plotted immediately via gridExtra.grid.arrange() and the list of plots is returned invisibly. Else the list of plots is simply returned.
...	Additional arguments given to ggpLayerScaleBarSI() if input for sb_dist is a valid distance measure. Exception: xrange and yrange are set to the ranges of the image that was cropped to display the image annotation.

Details

At first, the image section that contains the image annotation is cropped such that it only contains the extent of the polygon that represents the borders of the annotation (ranges can be obtained with getImageAnnotatationRange()). Using arguments square and expand can be used to expand the displayed image section individually.

Value

A list of ggplots. Each slot contains a plot that visualizes an image annotation.

Distance measures

Several functions in SPATA2 have arguments that take distance input. To specifically refer to a distance the unit must be specified. There are three ways to create valid input for these arguments.

1. In pixel:

There are two valid input options to specify the distance in pixel:

• numeric: Single numeric values, e.g. arg_input = c(2, 3.554, 69, 100.67). If no unit is specified the input will be interpreted as pixels.

• character: Suffixed with 'px', e.g. arg_input = c('2px', '3.554px', '69px', '100.67px')

Note: The unit pixel (px) is used for distances as well as for areas. If pixel refers to a distance the pixel side length is meant. If pixel refers to an area the number of pixels is meant.

2. According to the Systeme international d'unites (SI):

Specifying distances in SI units e.g. arg_input = c('2mm', '4mm') etc. requires the input to be a character as the unit must be provided as suffix. Between the numeric value and the unit must be no empty space! Valid suffixes can be obtained using the function validUnitsOfLengthSI().

3. As vectors of class unit:

Behind the scenes SPATA2 works with the units package. Input is converted into vectors of class units. Therefore, input can be directly provided this way: arg_input = units::set_unit(x = c(2,4), value = 'mm') Note that pixel is not a valid unit in the units package. If you want to specify the input in pixel you have to use input option 1. In pixel.

Expansion of cropped image sections

The argument expand is a versatile way, to specify how a cropped image section is extracted. If you want the cropped image as is, specify expand = 0. Else, there are multiple options. In general, expand takes three kinds of values, namely percentages, distances and distance exclamations.

• Percentage: A string suffixed with %. E.g. expand = '50%' adds 50% of the distance from the center to the border of the image annotation to the image frame.

• Distance measures: In pixel or European units of length. E.g. expand = list(x = '1mm') expands the x-axis on both sides with 1mm. ⁠expand = list(x = c('0.5mm', 1.5mm')⁠ expands the x-axis on the left side with 0.5mm and on the right side with 1.5mm.

• Exclam distance measures: Distance measure with an exclamation mark suffix. E.g. expand = '1mm!' centers the image and forces an axis length of 1 millimeter. (Example 5)

Depending on how the values are specified different parts of the image can be expanded.

Single values, like expand = 50, are recycled: Every end of each image axis is expanded by 50 pixel. (Example 2)

Vectors of length two, like expand = c('1mm', '2mm'), are recycled: The beginning of each axis is expanded by 1 millimeter. The end of each axis is expanded by 2mm. (Example 3)

Named lists can be more precise. expand = list(x = c('1mm', '0.5mm'), y = c('0.25mm', '1mm')). Applies the vectors to expand the corresponding axis. (Example 4)

Using exclam input the side of the axis must not be specified as the axis is fixed as a whole. E.g expand = list(x = '1mm!', y = '2mm!') results in the same output as ⁠expand = list(x = c('1mm!', '1mm!'), y = c('2mm!', '2mm!')⁠.

Selection of image annotations with tags

Input for argument tags specifies the tags of interest. Argument test decides about how the specified tags are used to select the image annotations of interest. There are multiple options:

1. Argument test set to 'any' or 1: To be included, an image annotation must be tagged with at least one of the input tags.

2. Argument test set to 'all' or 2: To be included, an image annotation must be tagged with all of the input tags. Can contain tags that are not specified.

3. Argument test set to 'identical' or 3: To be included, an image annotation must be tagged with all of the input tags. Can not be tagged with anything else.

4. Argument test set to not_identical or 4: To be included, an image annotation must not be tagged with the combination of input tags.

5. Argument test set to 'none' or 5: To be included, an image annotation must not contain any of the input tags.

Note that the filtering process happens after the filtering by input for argument ids. You can first select a group of image annotations by naming their IDs and then select among them via tags and test. If ids is NULL, you select among all image annotations via tags and test. And if tags is also NULL, the function uses all image annoations.

See Also

getImageAnnotations()

Examples

library(SPATA2)
library(SPATAData)

object <- downloadSpataObject(sample_name = "275_T", verbose = FALSE)

data("image_annotations")

object <- setImageAnnotations(object, img_anns = image_annotations[["275_T"]])

plotImageAnnotations(
 object = object,
 ids = "img_ann_1",
 expand = "0.5mm",
 encircle = T # no encircling possible if expand = 0
 )

### Example 1

plotImageAnnotations(
 object = object,
 ids = "img_ann_1",
 expand = 0,
 encircle = FALSE # no encircling possible if expand = 0
 )

 process_expand_input(0)

### Example 2
plotImageAnnotations(
 object = object,
 ids = "img_ann_1",
 expand = 50, # all sides are expanded with 50px -> 100px gain per axis
 encircle = TRUE
 )

 process_expand_input(50)

### Example 3
plotImageAnnotations(
 object = object,
 ids = "img_ann_1",
 expand = c("1mm", "2mm"),
 encircle = TRUE
 )

 process_expand_input(c("1mm", "2mm"))

### Example 4
plotImageAnnotations(
 object = object,
 ids = "img_ann_1",
 expand = list(x = c('1mm', '0.5mm'), y = c('0.25mm', '1mm')),
 encircle = TRUE
 )

 process_expand_input(list(x = c('1mm', '0.5mm'), y = c('0.25mm', '1mm')))


### Example 5
plotImageAnnotations(
 object = object,
 ids = "img_ann_1",
 expand = "1mm!", # center image and force axis length of 1mm
 encircle = TRUE,
 dist_sb = "100um",
 text_color = "white",
 sgmt_color = "white",
 pos = "bottom_right",
 )

 process_expand_input("1mm!")

kueckelj/SPATA2 documentation built on March 16, 2024, 10:25 a.m.