plotSpatialAnnotations.Rd
Plots image sections containing the areas that were annotated via
createGroupAnnotations()
, createImageAnnotations()
or
createNumericAnnotations()
.
plotSpatialAnnotations(object, ...)
# S4 method for class 'SPATA2'
plotSpatialAnnotations(
object,
ids = NULL,
tags = NULL,
test = "any",
expand = "25%",
square = TRUE,
outline = 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,
...
)
# S4 method for class 'SpatialData'
plotSpatialAnnotations(
object,
ids = NULL,
tags = NULL,
test = "any",
expand = "25%",
square = TRUE,
outline = 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,
...
)
An object of class SPATA2
or, in case of S4 generics,
objects of classes for which a method has been defined.
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 spatial annotation.
Character vector or NULL
. If character, the tags for the image annotation
selection. See section Selection of spatial annotations for more information.
Character value. One of c('any'. 'all', 'identical', 'not_identical', 'none').
Specifies how input for tags
is used to select spatial annotations.
See section Selection of spatial annotations for more information.
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.
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.
Logical value. If TRUE, a polygon is drawn around the exact extent of the annotated structure.
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.
Character value. The unit in which the x- and y-axis text
are displayed. Use validUnitsOfLengthSI()
to obtain all valid input options.
Numeric value or FALSE
. If numeric and unit
is not px, rounds
axes text.
Character. Affects color of the main lines of the plot.
Numeric. Affects size of the main lines of the plot.
Character. The line type. One of 'blank', 'solid', 'dashed', 'dotted', 'dotdash', 'longdash' and 'twodash'.
Character value or NA. If character, specifies the color with which the outline of the spatial annotation is filled.
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.
Logical value. If TRUE, the number of each spatial annotation is plotted in the title.
Logical value. If TRUE, the ID of each spatial annotation is plotted in the subtitle.
Logial value. If TRUE, the tags of each spatial annotation are plotted in the caption.
List of ggproto
-objects that are added to each plot.
Skim ggpLayer*()
-functions for more options.
Numeric values or NULL. Used to arrange multiple plots.
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.
A list of ggplots. Each slot contains a plot that visualizes an spatial annotation.
At first, the image section that contains the spatial 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 getSpatAnnRange()
).
Using arguments square
and expand
can be used to expand the displayed
image section individually.
The vignette on distance measures in SPATA2 has been replaced. Click
here
to read it.
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 spatial annotations via the arguments ids
, class
, tags
and
test
works in three steps:
First, if ids
is a character it prefilters the annotations by ID and only
the specified ones are submitted to the next steps. If it is NULL
, all
annotations are submitted to the next steps.
Secondd, if class
is a character it filters the annotations remaining
after the first step by their class. If NULL
, the step is skipped.
Third, if tags
is a character it is used in combination with test
to select
from the spatial annotations that remain after the second step based on the meta data
they are tagged with. There are multiple options:
Argument test
set to 'any' or 1: To be included, an image annotation
must be tagged with at least one of the input tags.
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.
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.
Argument test
set to not_identical or 4: To be included, an image
annotation must not be tagged with the combination of input tags.
Argument test
set to 'none' or 5: To be included, an image annotation
must not contain any of the input tags.
If tags
is NULL
, the step is skipped. Therefore, if ids
, class
and tags
are all NULL, which is the default, all annotations are selected as all subsetting
steps are skipped. Eventually, the remaining spatial annotations are submitted to
whatever the respective function does.
library(SPATA2)
data("example_data")
object <- example_data$object_UKF313T_diet
ids <- getSpatAnnIds(object, tags = c("necrotic", "compr"), test = "identical")
plotSpatialAnnotations(object, ids = ids)
plotSpatialAnnotations(object, ids = ids, square = T)
plotSpatialAnnotations(object, id = ids, fill = "orange", square = T, expand = "50%")