Create ternary plots that show similarity between single cells and selected three terminals in a ternary baricentric coordinate.
Usage
plotTernary(x, ...)
# S3 method for default
plotTernary(
x,
clusterVar,
vertices,
features = NULL,
veloGraph = NULL,
byCluster = NULL,
processed = FALSE,
method = c("euclidean", "cosine", "pearson", "spearman"),
force = FALSE,
sigma = 0.08,
scale = TRUE,
dotColorBy = NULL,
dotColor = NULL,
palette = "D",
direction = 1,
breaks = NULL,
legendTitle = NULL,
returnData = FALSE,
...
)
Arguments
- x
Input data. Can be a
matrix
ordgCMatrix
object with cells as columns, aSeurat
orSingleCellExperiment
object. "simMat" method takes intermediate values.- ...
Arguments passed on to
plotTernary.simMat
title
Title text of the plot. Default
NULL
.nGrid
Number of grids along the bottom side of the equilateral triangle. Default
10
.radius
Arrow length of unit velocity. Lower this when arrows point outside of the coordinate. Default
0.1
.dotSize
Dot aesthetics passed to
geom_point
. Default0.6
when not interactive,4
when interactive.dotShuffle
Whether to shuffle the order of dots being added to the plot, useful when categorical colors are used and mixing of categories is expected. Default
NULL
does shuffle whendotColorBy
given is categorical and does not otherwise.labelColors
Colors of the axis lines and vertex labels. Default
c("#3B4992FF", "#EE0000FF", "#008B45FF")
(blue, red and green)vertexLabelSize
Size of vertex labels. Default
6
when not interactive,16
when interactive.vertexLabelDrift
Position adjustment of the vertex labels, only applied to non-interactive view. Default
0.03
.axisBreak
Number of breaks to be labeled along axis. Default
5
.axisTextShow
Logical, whether to show axis text. Default
TRUE
.axisTextSize
Size of text along each axis break. Default
4
for non-interactive view,12
for interactive view.axisTextDrift
Position adjustment of the axis text, only applied to non-interactive view. Default
0.01
.gridLineAlpha
Transparency of background grid lines. Default
0.6
.arrowLinewidth
Line width of the velocity arrows. Default
0.25
for non-interactive view,2
for interactive view.arrowAngle
Controls the angle of the arrowhead, only applied to non-interactive view. Default
20
.arrowLen
Control length in centimetre from arrow tip to arrow tail, only applied to non-interactive view. Default
0.2
.titleSize
Size of title text. Default
14
for non-interactive view,20
for interactive view.equilateral
Logical, whether to always display the triangle as equilateral. Default
TRUE
.margin
Margin allowed around of the triangle plotting region when
equilateral = TRUE
interactive
Logical. Whether to display plotly interactive view. Default
FALSE
.
- clusterVar
A vector/factor assigning the cluster variable to each column of the matrix object. For "Seurat" method,
NULL
(default) forIdents(x)
, or a variable name inmeta.data
slot. For "SingleCellExperiment" method,NULL
(default) forcolLabels(x)
, or a variable name incolData
slot.- vertices
Vector of three unique cluster names that will be used for plotting. Or a named list that groups clusters as three terminal vertices. There must not be any overlap between groups.
- features
Valid matrix row subsetting index to select features for similarity calculation. Default
NULL
uses all available features.- veloGraph
Cell x cell
dgCMatrix
object containing velocity information. Shows velocity grid-arrow layer when specified. DefaultNULL
does not show velocity.- byCluster
Default
NULL
to generate one plot with all cells. Set"all"
to split cells in plot by cluster and returns a list of subplots for each cluster as well as the plot including all cells. Otherwise, a vector of cluster names to generate a list of subplots for the specified clusters.- processed
Logical. Whether the input matrix is already processed.
TRUE
will bypass internal preprocessing and input matrix will be directly used for similarity calculation. DefaultFALSE
and raw count input is recommended. If missing in call, usingslot = "counts"
in "Seurat" method or usingassay.type = "counts"
in "SingleCellExperiment" method will force this argument to beFALSE
and others forTRUE
.- method
Similarity calculation method. Default
"euclidean"
. Choose from"euclidean"
,"cosine"
,"pearson"
,"spearman"
.- force
Whether to force calculate the similarity when more then 500 features are detected, which is generally not recommended. Default
FALSE
.- sigma
Gaussian kernel parameter that controls the effect of variance. Only effective when using a distance metric (i.e.
method
is"euclidian"
or"cosine"
). Larger values tighten the dot spreading on figure. Default0.08
.- scale
Whether to min-max scale the distance matrix by clusters. Default
TRUE
.- dotColorBy
A vector/factor for coloring dots, can be either categorical (must be character or factor) or continuous. Default
NULL
.- dotColor
Character vector of color codes. When
dotColorBy
isNULL
, use one or as many colors as the number of cells. IfdotColorBy
is categorical, specify as many colors as the number of categories indotColorBy
or ggplot2 categorical color palette is used by default. IfdotColorBy
is continuous, specify together withbreaks
argument.- palette
Color palette to use when
dotColorBy
is given. Default"D"
(viridis) for continuous value and ggplot2 default for categorical value. See detail for alternatives.- direction
Sets the order of colors in the scale. Default
1
orders as palette default. If-1
, the order of colors is reversed.- breaks
Number of breaks for continuous color scale passed to non-interactive "plot3D::scatter3D" call. Default
NULL
.- legendTitle
Title on the legend/colorbar. Default
NULL
uses"cluster"
ifdotColorBy
is missing (default); user-end variable expression ifdotColorBy
is directly specified from plotQuaternary.default method; variable name ifdotColorBy
is specified from Seurat or SingleCellExperiment method.- returnData
Logical. Whether to return similarity and aggregated velocity data if applicable instead of generating plot. Default
FALSE
.
Value
By default, a "ggplot" object when byCluster
is not specified,
a list of "ggplot" object when byCluster
is specified. When
interactive = TRUE
, a "plotly" object is returned. When
returnData = TRUE
, a list of similarity matrix and aggregated velocity
matrix is returned.
Details
Argument inheritance - For matrix/dgCMatrix ("default" method), we first calculate the similarity matrix and obtain a "simMat" object. Then the "simMat" method is internally called. For data container objects (e.g. Seurat), we obtain the correct data matrix first and then call the "default" method. The arguments inherits as the flow described above.
The calculation of similarity matrix - The similarity is calculated either by converting a distance metric ("euclidean" or "cosine") with Gaussian kernel, or directly computed with correlation metrics ("pearson" or "spearman"). The centroid of each terminal is obtained first, and the specified metric from each cell to each terminal is calculated. The similarity matrix (n cells by v terminals) is lastly normalized to sum to 1 for each cell, so it becomes a baricentric coordinate.
See also
Other plotTernary:
plotTernary.Seurat()
,
plotTernary.SingleCellExperiment()
Examples
gene <- selectTopFeatures(rnaRaw, rnaCluster, c("OS", "RE", "CH"))
#> Selected 30 features for "CH".
#> Selected 30 features for "OS".
#> Selected 30 features for "RE".
plotTernary(rnaRaw, rnaCluster, c("OS", "RE", "CH"), gene)