Skip to contents

ClonalDynamicsPlot

Source: R/clonalstatplot.R
ClonalDynamicsPlot.Rd

Visualize the dynamics of the clones using TrendPlot or SankeyPlot.

Usage

ClonalDynamicsPlot(
  data,
  clones = NULL,
  top = 10,
  orderby = NULL,
  clone_call = "aa",
  chain = "both",
  plot_type = c("sankey", "alluvial", "trend"),
  group_by = "Sample",
  groups = NULL,
  subgroup_by = NULL,
  subgroups = NULL,
  relabel = FALSE,
  facet_by = NULL,
  split_by = NULL,
  ...
)

Arguments

data

The product of scRepertoire::combineTCR, scRepertoire::combineTCR, or scRepertoire::combineExpression.

clones

The specific clones to track. This argument must be provided. If a single character value is provided, it will be evaluated as an expression to select the clones. If multiple character values are provided, they will be treated as clone IDs. For expression, see also clone_selectors.

top

The number of top clones to select. Default is 10.

orderby

An expression to order the clones by. Default is NULL. Note that the clones will be ordered by the value of this expression in descending order.

clone_call

How to call the clone - VDJC gene (gene), CDR3 nucleotide (nt), CDR3 amino acid (aa), VDJC gene + CDR3 nucleotide (strict) or a custom variable in the data

chain

indicate if both or a specific chain should be used - e.g. "both", "TRA", "TRG", "IGH", "IGL"

plot_type

The type of plot to use. Default is "sankey". Possible values are "trend", "sankey", and "alluvial" (alias of "sankey").

group_by

The column name in the meta data to group the cells. Default: "Sample"

groups

The groups to include in the plot. Default is NULL. If NULL, all the groups in group_by will be included.

subgroup_by

The column name in the meta data to subgroup the nodes (group nodes on each x). Default: NULL. This argument is only supported for "sankey"/"alluvial" plot. If NULL, the nodes will be grouped/colored by the clones

subgroups

The subgroups to include in the plot. Default is NULL.

relabel

Whether to relabel the clones. Default is FALSE. The clone ids, especially using CDR3 sequences, can be long and hard to read. If TRUE, the clones will be relabeled as "clone1", "clone2", etc.

facet_by

The column name in the meta data to facet the plots. Default: NULL. This argument is not supported and will raise an error if provided.

split_by

The column name in the meta data to split the plots. Default: NULL

...

Other arguments passed to the specific plot function.

Value

A ggplot object or a list if combine is FALSE

Examples

# \donttest{
set.seed(8525)
data(contig_list, package = "scRepertoire")
data <- scRepertoire::combineTCR(contig_list,
    samples = c("P17B", "P17L", "P18B", "P18L", "P19B","P19L", "P20B", "P20L"))
data <- scRepertoire::addVariable(data,
    variable.name = "Type",
    variables = rep(c("B", "L"), 4)
)
data <- scRepertoire::addVariable(data,
    variable.name = "Subject",
    variables = rep(c("P17", "P18", "P19", "P20"), each = 2)
)

# showing the top 10 clones in P17B and P17L
ClonalDynamicsPlot(data, group_by = "Sample", groups = c("P17B", "P17L"))


# showing the top 10 clones in P17B and P17L, with the clones relabeled
ClonalDynamicsPlot(data, group_by = "Sample", groups = c("P17B", "P17L"), relabel = TRUE)


# showing the top 10 clones in P17B and P17L, with subgroups in each group
ClonalDynamicsPlot(data, group_by = "Type", subgroup_by = "Sample",
    subgroups = c("P17B", "P17L", "P18B", "P18L", "P19B","P19L"), relabel = TRUE)


# showing selected clones in P17B and P17L
ClonalDynamicsPlot(data, group_by = "Sample", groups = c("P17B", "P17L"),
    clones = c("CVVSDNTGGFKTIF_CASSVRRERANTGELFF", "NA_CASSVRRERANTGELFF"), relabel = TRUE)


# facetting is supported
ClonalDynamicsPlot(data, group_by = "Subject", groups = c("P17", "P19"),
    facet_by = "Type", relabel = TRUE)


# as well as splitting
ClonalDynamicsPlot(data, group_by = "Subject", groups = c("P17", "P19"),
    split_by = "Type", relabel = TRUE)


# showing shared clones between P17B and P17L (clones that are present in both samples)
ClonalDynamicsPlot(data, group_by = "Sample", groups = c("P17B", "P17L"),
     clones = "shared(P17B, P17L)", relabel = TRUE)


# showing shared clones but with a different order
ClonalDynamicsPlot(data, group_by = "Sample", groups = c("P17B", "P17L"),
     clones = "shared(P17B, P17L)", relabel = TRUE, orderby = "P17L - P17B")


# showing clones larger than 10 in P17L and ordered by the clone size in P17L descendingly
ClonalDynamicsPlot(data, group_by = "Sample", groups = c("P17B", "P17L"),
     clones = "select(P17L > 10)", relabel = TRUE, top = 5, orderby = "P17L")


# using trend plot
ClonalDynamicsPlot(data, group_by = "Sample", groups = c("P17B", "P17L"),
    clones = "intersect(select(P17L > 20), shared(P17L, P17B))", relabel = TRUE, orderby = "P17L",
    plot_type = "trend")

# }