ggpLayerScaleBarSI.RdAdds 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 = 5,
xrange = NULL,
yrange = NULL,
offset = c(0.8, 0.8),
theme_opt = "none"
)An object of class spata2.
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.
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.
The color in which the scale bar is displayed.
Affect the appearance of the segment. sgmt_type
should be one of validLineTypes().
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.
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.
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.
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.
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.
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.
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.
object <- downloadPubExample("313_T", verbose = FALSE)
plotImageGgplot(object) +
ggpLayerEncirclingIAS(
object = object,
id = "necrotic_area",
distance = "2.25mm"
) +
ggpLayerScaleBarSI(
object = object,
sb_dist = "2.25mm",
sb_pos = "top_right"
)