Add pointer towards image annotations — ggpLayerImgAnnPointer • SPATA2

Adds segments and, if desired, labels to the surface plot that point towards and highlight the position of image annotations.

ggpLayerImgAnnPointer(
  object,
  ids = NULL,
  tags = NULL,
  test = "any",
  color_by = NULL,
  ptr_angles = 45,
  ptr_labels = NULL,
  ptr_lengths = "250um",
  ptr_alpha = 0.9,
  ptr_arrow = NULL,
  ptr_color = "black",
  ptr_size = 1,
  text_alpha = 0.9,
  text_color = "black",
  text_dist = 0,
  text_nudge_x = 0,
  text_nudge_y = 0,
  text_size = 4,
  point_at = "center",
  seed = NULL,
  clrp = NULL,
  clrp_adjust = NULL
)

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.
color_by: Character value or NULL. If character, one of 'id' or 'label' which colors the the pointers accordingly.
ptr_angles, ptr_lengths: Numeric value of length 1 or of length equal to the number of image annotations. Specifies the angle from which the segments points towards the image annotation as well as their length. ptr_lengths works within the SPATA2 distance framework. See section Distance measures for more information.
ptr_labels: Specifies if and how the pointers are labeled. If NULL, the default, the image annotations are labeled by their ID. If character, specifies the exact label of each image annotation and should be of length 1 or of length equal to the number of image annotations. If FALSE, no text is displayed.
ptr_alpha: Numeric value. Specifies the transparency of the pointers.
ptr_arrow: NULL or arrow as displayed by grid::arrow().
ptr_color: Character value. Specifies the color of the pointers if color_by is not a character.
ptr_size: Numeric value. Specifies the size (thickness) of the pointers.
text_dist: Distance measure. Specifies the distance from the text to the pointer.
point_at: Character value. If 'center', the pointer is directed at the center of the image annotation. If 'border', the pointer points at a random point of the image annotation border - recommended if the image annotation is big.
seed: Numeric value or NULL. If numeric, sets seed before picking a random point of the image annotation border if point_at = 'border'.
clrp: Character value. Specifies the color palette to be used to represent groups of discrete variables. Run validColorPalettes() to obtain valid input options.
clrp_adjust: Named character vector or NULL. If character, it adjusts the color palette that is used to represent the groups. Names of the input vector must refer to the group and the respective named element denotes the color with which to represent the group.

Value

ggpLayer*()-functions return lists of ggproto objects that can be added to ggplots via the + operator. In most of the cases they are supposed to be added to plots created with the plotSurface*()

family.

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.