Add a scale bar in SI units

Adds a scale bar to the surface plot that visualizes distance in SI units.

ggpLayerScaleBarSI(
  object,
  sb_dist = "1mm",
  sb_pos = "bottom_right",
  sb_alpha = 1,
  sb_color = "black",
  sgmt_size = 1,
  sgmt_type = "solid",
  text_nudge_x = 0,
  text_nudge_y = 0,
  text_pos = NULL,
  text_size = 10,
  xrange = getCoordsRange(object)$x,
  yrange = getCoordsRange(object)$y,
  offset = c(0.8, 0.8),
  theme_opt = "none"
)

Arguments

object

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

sb_dist

The distance in SI units that the scale bar illustrates (e.g. '1mm', '200um'). Must not be bigger than the range of the image of the plot.

sb_pos

Character value or vector of length two.

If character, one of top_right, top_left, bottom_right or bottom_left. The scale bar is positioned accordingly.

If vector of length two, distance measures that specify the positioning of the segment. Text is lifted slightly to hover above. First value sets positioning on the x- and second value sets positioning on the y-axis.

sb_color

The color in which the scale bar is displayed.

sgmt_size, sgmt_type

Affect the appearance of the segment. sgmt_type should be one of validLineTypes().

text_nudge_x, text_nudge_y

Numeric value or NULL. Moves the scale bar along the axis in pixel units. If NULL, nudging is computed based on the input of yrange.

text_pos

Numeric vector of length two or NULL. If numeric, sets the position of the scale bar text precisely. text_nudge_x and text_nudge_y is still applied.

xrange, yrange

The range of the image that is considered if the positioning of the scale is calculated via sb_pos as one of top_right, top_left, bottom_right or bottom_left. Defaults to the image range.

offset

Numeric vector of length two. Used to move the position of the scale bar away from the center. Values should range from 0 to 1. First value is used to move along the x-axis. Second value is used for the y-axis.

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.

Details

The scale bar consists of two graphical objects. The segment of the scale bar is plotted with geom_segment_fixed(). The text of the scale bar is plotted with geom_text_fixed().

If sb_pos is one of top_right, top_left, bottom_right or bottom_left, the position of the scale bar is computed in combination with the input for argument offset. Argument offset is used to repel the scale bar away from the center into the corner specified in sb_pos. Thus, if offset = c(0,0), the scale bar is positioned in the center of the plot regardless of the specification of sb_pos. Offset values specify the percentage of the distance between the center of the plot and its limits. For instance, if sb_pos = c(0.5, 0.75) and sb_pos = 'top_right' the scale bar is moved to the right (50% of the distance between the center the limits of the x-axis) and to the top (75% of the distance between the center and the limits of the y-axis).

If numeric, sb_pos explicitly sets positioning of the segment (not the text). The text is automatically lifted such that it hovers over the segment. If this does not work or you want to manipulate the text positioning you can use arguments text_nudge_x and text_nudge_y or set the position precisely with text_pos.

Distance measures

The vignette on distance measures in SPATA2 has been replaced. Click here to read it.

Examples

library(SPATA2)
library(tidyverse)

object <- loadExampleObject("UKF275T")

object <-
 createNumericAnnotations(
   object = object,
   variable = "HM_HYPOXIA",
   threshold = "kmeans_high",
   id = "hypoxia_ann",
   force1 = TRUE
   )

plotSurface(object, color_by = "HM_HYPOXIA", outline = T, pt_clrsp = "Reds 3") +
 ggpLayerHorizonSAS(object, id = "hypoxia_ann", distance = "3mm") +
 ggpLayerScaleBarSI(object, sb_pos = c("3mm", "2mm"))