vizAPOTC {APackOfTheClones} | R Documentation |
Directly visualize clonal expansion of a combined seurat object
Description
This function combines the functionality of both RunAPOTC and APOTCPlot. Given a Seurat object, it first runs the APackOfTheClones method (RunAPOTC) to compute clonal expansion information, and then generates a customizable ggplot2 object of the clonal expansion plot with a circle size legend (APOTCPlot).
Usage
vizAPOTC(
seurat_obj,
reduction_base = "umap",
clonecall = "strict",
...,
extra_filter = NULL,
alt_ident = NULL,
clone_scale_factor = "auto",
rad_scale_factor = 0.95,
order_clones = TRUE,
try_place = FALSE,
repulse = TRUE,
repulsion_threshold = 1,
repulsion_strength = 1,
max_repulsion_iter = 20L,
show_shared = NULL,
only_link = NULL,
clone_link_width = "auto",
clone_link_color = "black",
clone_link_alpha = 0.5,
res = 360L,
linetype = "blank",
use_default_theme = TRUE,
retain_axis_scales = FALSE,
alpha = 1,
show_labels = FALSE,
label_size = 5,
add_size_legend = TRUE,
legend_sizes = "auto",
legend_position = "auto",
legend_buffer = 0.2,
legend_color = "#808080",
legend_spacing = "auto",
legend_label = "Clone sizes",
legend_text_size = 5,
add_legend_background = TRUE,
add_legend_centerspace = 0,
detail = TRUE,
verbose = TRUE
)
Arguments
seurat_obj |
A seurat object that has been integrated with clonotype
data with |
reduction_base |
character. The seurat reduction to base the clonal
expansion plotting on. Defaults to |
clonecall |
character. The column name in the seurat object metadata to
use. See |
... |
additional "subsetting" keyword arguments indicating the rows
corresponding to elements in the seurat object metadata that should be
filtered by. E.g., |
extra_filter |
character. An additional string that should be formatted
exactly like a statement one would pass into dplyr::filter that does
additional filtering to cells in the seurat object - on top of the other
keyword arguments - based on the metadata. This means that it will be
logically AND'ed with any keyword argument filters. This is a more flexible
alternative / addition to the filtering keyword arguments. For example, if
one wanted to filter by the length of the amino acid sequence of TCRs, one
could pass in something like |
alt_ident |
character. By default, cluster identity is assumed to be
whatever is in |
clone_scale_factor |
Dictates how much to scale each circle(between 0,1)
radius when converting from clonotype counts into circles that represent
individual clonotypes. The argument defaults to the character |
rad_scale_factor |
numeric between 0 and 1. This value decreases the radius of the smallest clones by this scale factor. And the absolute value of this decrease will be applied to all packed circles, effectively shrinking all circles on the spot, and introduce more constant spacing in between. |
order_clones |
logical. Decides if the largest clone circles should be
near cluster centroids. This is highly recommended to be set to TRUE for
increased intuitiveness of the visualization, as resulting plots tend to
give an improved impression of the proportion of expanded clones. If
|
try_place |
If |
repulse |
If |
repulsion_threshold |
numeric. The radius that clonal circle clusters overlap is acceptable when repulsing. |
repulsion_strength |
numeric. The smaller the value the less the clusters repulse each other per iteration, and vice versa. |
max_repulsion_iter |
integer. The number of repulsion iterations. |
show_shared |
The output of getSharedClones can be inputted here,
and the resulting plot will overlay lines between clone circles if that
clonotype is common between clusters. Note that the input must be
generated from data in the correct |
only_link |
Optional integer indicating to only display clone links originating from this cluster if showing shared clones. |
clone_link_width |
numeric. The width of the lines that connect shared
clones. Defaults to |
clone_link_color |
character. The color of the lines that connect shared
clones. Defaults to |
clone_link_alpha |
numeric. The alpha of the lines that connect shared clones. |
res |
The number of points on the generated path per full circle. From
plot viewers, if circles seem slightly too pixelated, it is recommended to
first try to export the plot as an |
linetype |
The type of outline each circle should have. defaults to
|
use_default_theme |
logical that defaults to |
retain_axis_scales |
If |
alpha |
numeric. The alpha of the circles in (0, 1]. Defaults to 1. |
show_labels |
If |
label_size |
The text size of labels if shown. Defaults to 5. |
add_size_legend |
If |
legend_sizes |
numeric vector. Indicates the circle sizes to be
displayed on the legend, and will always be sorted from smallest to greatest.
Defaults to |
legend_position |
character or numeric. Can be set to either
|
legend_buffer |
numeric. Indicates how much to "push" the legend towards the center of the plot from the selected corner. If negative, will push away |
legend_color |
character. Indicates the hex color of the circles displayed on the legend. Defaults to the hex code for a gray tone |
legend_spacing |
numeric. Indicates the horizontal distance between each
stacked circle on the size legend. Defaults to |
legend_label |
character. The title of the legend, which defaults to
|
legend_text_size |
numeric. The text size of the letters and numbers on the legend |
add_legend_background |
logical. If |
add_legend_centerspace |
numeric. An additional amount of distance changed between the circle sizes on the left side of the legend and the numbers on the right. Useful to set to around 0.5 (or more / less) when there are particularly large clone sizes that may cover the numbers. |
detail |
logical. If |
verbose |
logical. Decides if visual cues are displayed to the R console of the progress. |
Details
Note that the subsetting arguments ...
and extra_filter
are only a
quick convenience to subset based on metadata, and the subset
S3 method
defined in Seurat
is much more mature are has more features. Additionally,
users need to work with data subsets are recommended to and likely already
are working with seurat objects subsetted/split with Seurat::SplitObject
.
Value
A ggplot object of the APackOfTheClones clonal expansion plot of the
seurat object. There is an additional 10th element in the object named
"APackOfTheClones"
used by other functions in this package and shouldn't
interfere with any other ggplot functionality. (As far as currently known)
Cluster labelling
For the ident that was used to cluster the clones, labels for each cluster
are inferred and stored in the run so that they can be used by other
functions and optionally overlaid on the plot over clusters. If the levels
of the ident used is a naturally ordered integer sequence, then the labels
generated would be "C1", "C2", "C3" ...
, else they would be the actual
ident levels themselves.
See Also
Examples
data("combined_pbmc")
# plot with default parameters
vizAPOTC(combined_pbmc, verbose = FALSE)
# use arguments from RunAPOTC and APOTCPlot
vizAPOTC(
combined_pbmc, try_place = TRUE, show_labels = TRUE, verbose = FALSE
)