RunAPOTC {APackOfTheClones} | R Documentation |
Run the APackOfTheClones method on a combined Seurat object for downstream visualization of clonal expansion
Description
Computes necessary information for an APackOfTheClones
clonal expansion plot (APOTCPlot) and stores it in the seurat object.
Gets sizes of unique clones and utilizes a circle-packing algorithm to
pack circles representing individual clones in approximately the same
dimensional reduction (reduction_base
) coordinates based on some cell
ident (defaults to the active ident).
The parameter extra_filter
along with an unlimited number of additional
keyword arguments can be used to filter the cells by certain conditions
in the metadata, and new results will be stored in addition to other runs
the users may have done.
Each APackOfTheClones run is uniquely identified by the parameters
reduction_base
, clonecall
, extra_filter
, and any additional keywords
passed to filter the metadata. Each distinct run result is stored in the
seurat object and has an associated Id generated from the aforementioned
parameters. To view the id of the latest run, call getLastApotcDataId.
To view all the ids of previous runs, call getApotcDataIds. To work further
with a specific run (most importantly, plotting), the user can use this id
in the arguments with is slightly more convenient than passing in the
original RunAPOTC parameters again but both ways work.
If the user wishes to manually customize/fix the expansion plot generated, the circular packing information can be modified with the AdjustAPOTC function.
Usage
RunAPOTC(
seurat_obj,
reduction_base = "umap",
clonecall = "strict",
...,
extra_filter = NULL,
alt_ident = NULL,
run_id = 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,
override = FALSE,
verbose = TRUE
)
Arguments
seurat_obj |
Seurat object with one or more dimension reductions and
already have been integrated with a TCR/BCR library 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 |
run_id |
character. This will be the ID associated with the data of a
run, and will be used by other important functions like APOTCPlot and
AdjustAPOTC. Defaults to
where if keyword arguments and extra_filter are underscore characters if
there was no input for the |
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. |
override |
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
.
All APackOfTheClones run data is stored in the Seurat object under
seurat_object@misc$APackOfTheClones
, which is a list of S4 objects of the
type "ApotcData", with each element corresponding to a unique run. The id of
each run is the name of each element in the list. The user
really shouldn't manually modify anything in the list as it may cause
unexpected behavior with many other functions.
Additionally, it logs a seurat command associated with the run in the
seurat_object@commands
slot as a "SeuratCommand" object (from Seurat),
where the name of the object in the list is formatted as RunAPOTC.run_id
.
Value
A modified version of the input seurat object, which harbors data necessary for visualizing the clonal expansion of the cells with APOTCPlot and has a friendly user interface to modify certain attributes with AdjustAPOTC.
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
APOTCPlot, AdjustAPOTC, getApotcDataIds
Examples
data("combined_pbmc")
# this is the recommended approach to use a custom run_id with default params
combined_pbmc <- RunAPOTC(combined_pbmc, run_id = "default", verbose = FALSE)
# here's a seperate run with some filters to the meta data, where
# `orig.ident` is a custom column in the example data. Notice that it is not
# a `RunAPOTC` parameter but a user keyword argument
combined_pbmc <- RunAPOTC(
combined_pbmc, run_id = "sample17", orig.ident = c("P17B", "P17L"),
verbose = FALSE
)
# the exact same thing can be achieved with the `extra_filter` parameter
combined_pbmc <- RunAPOTC(
combined_pbmc,
run_id = "sample17",
extra_filter = "substr(orig.ident, 2, 3) == '17'",
override = TRUE,
verbose = FALSE
)