dittoScatterPlot: Show RNAseq data overlayed on a scatter plot
In dtm2451/dittoSeq: User Friendly Single-Cell and Bulk RNA Sequencing Visualization
View source: R/DittoScatterPlot.R
dittoScatterPlot R Documentation
Show RNAseq data overlayed on a scatter plot
Description
Show RNAseq data overlayed on a scatter plot
Usage
dittoScatterPlot(
object,
x.var,
y.var,
color.var = NULL,
shape.by = NULL,
split.by = NULL,
extra.vars = NULL,
cells.use = NULL,
multivar.split.dir = c("col", "row"),
show.others = FALSE,
split.show.all.others = TRUE,
size = 1,
opacity = 1,
color.panel = dittoColors(),
colors = seq_along(color.panel),
split.nrow = NULL,
split.ncol = NULL,
split.adjust = list(),
assay.x = .default_assay(object),
slot.x = .default_slot(object),
adjustment.x = NULL,
assay.y = .default_assay(object),
slot.y = .default_slot(object),
adjustment.y = NULL,
assay.color = .default_assay(object),
slot.color = .default_slot(object),
adjustment.color = NULL,
assay.extra = .default_assay(object),
slot.extra = .default_slot(object),
adjustment.extra = NULL,
swap.rownames = NULL,
shape.panel = c(16, 15, 17, 23, 25, 8),
rename.color.groups = NULL,
rename.shape.groups = NULL,
min.color = "#F0E442",
max.color = "#0072B2",
min = NA,
max = NA,
order = c("unordered", "increasing", "decreasing", "randomize"),
xlab = x.var,
ylab = y.var,
main = "make",
sub = NULL,
theme = theme_bw(),
do.hover = FALSE,
hover.data = NULL,
hover.assay = .default_assay(object),
hover.slot = .default_slot(object),
hover.adjustment = NULL,
do.contour = FALSE,
contour.color = "black",
contour.linetype = 1,
add.trajectory.lineages = NULL,
add.trajectory.curves = NULL,
trajectory.cluster.meta,
trajectory.arrow.size = 0.15,
do.letter = FALSE,
do.ellipse = FALSE,
do.label = FALSE,
labels.size = 5,
labels.highlight = TRUE,
labels.repel = TRUE,
labels.split.by = split.by,
labels.repel.adjust = list(),
legend.show = TRUE,
legend.color.title = "make",
legend.color.size = 5,
legend.color.breaks = waiver(),
legend.color.breaks.labels = waiver(),
legend.shape.title = shape.by,
legend.shape.size = 5,
do.raster = FALSE,
raster.dpi = 300,
data.out = FALSE
)
Arguments
object
A Seurat, SingleCellExperiment, or SummarizedExperiment object.
x.var, y.var
Single string giving a gene or metadata that will be used for the x- and y-axis of the scatterplot.
Note: must be continuous.
Alternatively, can be a directly supplied numeric vector of length equal to the total number of cells/samples in object.
color.var
Single string giving a gene or metadata that will set the color of cells/samples in the plot.
Alternatively, can be a directly supplied numeric or string vector or a factor of length equal to the total number of cells/samples in object.
shape.by
Single string giving a metadata (Note: must be discrete.) that will set the shape of cells/samples in the plot.
Alternatively, can be a directly supplied string vector or a factor of length equal to the total number of cells/samples in object.
split.by
1 or 2 strings naming discrete metadata to use for splitting the cells/samples into multiple plots with ggplot faceting.
When 2 metadatas are named, c(row,col), the first is used as rows and the second is used for columns of the resulting grid.
When 1 metadata is named, shape control can be achieved with split.nrow and split.ncol
extra.vars
String vector providing names of any extra metadata to be stashed in the dataframe supplied to ggplot(data).
Useful for making custom alterations after dittoSeq plot generation.
cells.use
String vector of cells'/samples' names OR an integer vector specifying the indices of cells/samples which should be included.
Alternatively, a Logical vector, the same length as the number of cells in the object, which sets which cells to include.
multivar.split.dir
"row" or "col", sets the direction of faceting used for 'var' values when var is given multiple genes or metadata, and when split.by is used to provide additional data to facet by.
show.others
Logical. FALSE by default, whether other cells should be shown in the background in light gray.
split.show.all.others
Logical which sets whether gray "others" cells of facets should include all cells of other facets (TRUE) versus just cells left out by cell.use (FALSE).
size
Number which sets the size of data points. Default = 1.
opacity
Number between 0 and 1.
Great for when you have MANY overlapping points, this sets how solid the points should be:
1 = not see-through at all. 0 = invisible. Default = 1.
(In terms of typical ggplot variables, = alpha)
color.panel
String vector which sets the colors to draw from. dittoColors() by default, see dittoColors for contents.
colors
Integer vector, the indexes / order, of colors from color.panel to actually use
split.nrow, split.ncol
Integers which set the dimensions of faceting/splitting when a single metadata is given to split.by.
split.adjust
A named list which allows extra parameters to be pushed through to the faceting function call.
List elements should be valid inputs to the faceting functions, e.g. 'list(scales = "free")'.
For options, when giving 1 metadata to split.by, see facet_wrap,
OR when giving 2 metadatas to split.by, see facet_grid.
assay.x, assay.y, assay.color, assay.extra, slot.x, slot.y, slot.color, slot.extra
single strings or integers (SCEs and SEs) or an optionally named vector of such values that set which expression data to use for each given data target.
See GeneTargeting for specifics and examples – Seurat and SingleCellExperiment objects deal with these differently, and functionality additions in dittoSeq have led to some minimal divergence from the native methodologies.
adjustment.x, adjustment.y, adjustment.color, adjustment.extra
For the given data target, when targeting gene / feature expression, should that data be used directly (default) or should it be adjusted to be
"z-score": scaled with the scale() function to produce a relative-to-mean z-score representation
"relative.to.max": divided by the maximum expression value to give percent of max values between [0,1]
swap.rownames
optionally named string or string vector.
For SummarizedExperiment or SingleCellExperiment objects, its value(s) specifies the column name of rowData(object) to be used to identify features instead of rownames(object).
When targeting multiple modalities (alternative experiments), names can be used to specify which level / alternative experiment (use 'main' for the top-level) individual values should be used for.
See GeneTargeting for more specifics and examples.
shape.panel
Vector of integers corresponding to ggplot shapes which sets what shapes to use.
When discrete groupings are supplied by shape.by, this sets the panel of shapes.
When nothing is supplied to shape.by, only the first value is used.
Default is a set of 6, c(16,15,17,23,25,8), the first being a simple, solid, circle.
Note: Unfortunately, shapes can be hard to see when points are on top of each other & they are more slowly processed by the brain.
For these reasons, even as a color blind person myself writing this code, I recommend use of colors for variables with many discrete values.
rename.color.groups, rename.shape.groups
String vector containing new names for the identities of the color or shape overlay groups.
min.color
color for min value of color.var data. Default = yellow
max.color
color for max value of color.var data. Default = blue
min, max
Number which sets the values associated with the minimum or maximum colors.
order
String. If the data should be plotted based on the order of the color data, sets whether to plot (from back to front) in "increasing", "decreasing", "randomize" order.
If left as "unordered", plot order is simply based on the order of cells within the object.
xlab, ylab
Strings which set the labels for the axes. To remove, set to NULL.
main
String, sets the plot title.
A default title is automatically generated if based on color.var and shape.by when either are provided.
To remove, set to NULL.
sub
String, sets the plot subtitle.
theme
A ggplot theme which will be applied before dittoSeq adjustments.
Default = theme_bw().
See https://ggplot2.tidyverse.org/reference/ggtheme.html for other options and ideas.
do.hover
Logical which controls whether the object will be converted to a plotly object so that data about individual points will be displayed when you hover your cursor over them.
hover.data argument is used to determine what data to use.
hover.data
String vector of gene and metadata names, example: c("meta1","gene1","meta2","gene2") which determines what data to show on hover when do.hover is set to TRUE.
hover.assay, hover.slot, hover.adjustment
Similar to the x, y, color, and extra versions, when showing expression data upon hover, these set what data will be shown.
do.contour
Logical. Whether density-based contours should be displayed.
contour.color
String that sets the color(s) of the do.contour contours.
contour.linetype
String or numeric which sets the type of line used for do.contour contours.
Defaults to "solid", but see linetype for other options.
add.trajectory.lineages
List of vectors representing trajectory paths, each from start-cluster to end-cluster, where vector contents are the names of clusters provided in the trajectory.cluster.meta input.
If the slingshot package was used for trajectory analysis,
you can provide add.trajectory.lineages = slingLineages('object').
add.trajectory.curves
List of matrices, each representing coordinates for a trajectory path, from start to end, where matrix columns represent x and y coordinates of the paths.
trajectory.cluster.meta
String name of metadata containing the clusters that were used for generating trajectories. Required when plotting trajectories using the add.trajectory.lineages method. Names of clusters inside the metadata should be the same as the contents of add.trajectory.lineages vectors.
trajectory.arrow.size
Number representing the size of trajectory arrows, in inches. Default = 0.15.
do.letter
Logical which sets whether letters should be added on top of the colored dots. For extended colorblindness compatibility.
NOTE: do.letter is ignored if do.hover = TRUE or shape.by is provided a metadata because
lettering is incompatible with plotly and with changing the dots' to be different shapes.
do.ellipse
Logical. Whether the groups should be surrounded by median-centered ellipses.
do.label
Logical. Whether to add text labels near the center (median) of clusters for grouping vars.
labels.size
Size of the the labels text
labels.highlight
Logical. Whether the labels should have a box behind them
labels.repel
Logical, that sets whether the labels' placements will be adjusted with ggrepel to avoid intersections between labels and plot bounds.
TRUE by default.
labels.split.by
String of one or two metadata names which controls the facet-split calculations for label placements.
Defaults to split.by, so generally there is no need to adjust this except when you are utilizing the extra.vars input to achieve manual faceting control.
labels.repel.adjust
A named list which allows extra parameters to be pushed through to ggrepel function calls.
List elements should be valid inputs to the geom_label_repel by default, or geom_text_repel when labels.highlight = FALSE.
legend.show
Logical. Whether any legend should be displayed. Default = TRUE.
legend.color.title, legend.shape.title
Strings which set the title for the color or shape legends.
legend.color.size, legend.shape.size
Numbers representing the size at which shapes should be plotted in the color and shape legends (for discrete variable plotting).
Default = 5. *Enlarging the icons in the colors legend is incredibly helpful for making colors more distinguishable by color blind individuals.
legend.color.breaks
Numeric vector which sets the discrete values to label in the color-scale legend for continuous data.
legend.color.breaks.labels
String vector, with same length as legend.breaks, which sets the labels for the tick marks of the color-scale.
do.raster
Logical. When set to TRUE, rasterizes the internal plot layer, changing it from individually encoded points to a flattened set of pixels.
This can be useful for editing in external programs (e.g. Illustrator) when there are many thousands of data points.
raster.dpi
Number indicating dots/pixels per inch (dpi) to use for rasterization. Default = 300.
data.out
Logical. When set to TRUE, changes the output, from the plot alone, to a list containing the plot ("p"),
a data.frame containing the underlying data for target cells ("Target_data"),
and a data.frame containing the underlying data for non-target cells ("Others_data").
Details
This function creates a dataframe with X, Y, color, shape, and faceting data determined by x.var, y.var, color.var, shape.var, and split.by.
Any extra gene or metadata requested with extra.var is added as well.
For expression/counts data, assay, slot, and adjustment inputs (.x, .y, and .color) can be used to change which data is used, and if it should be adjusted in some way.
Next, if a set of cells or samples to use is indicated with the cells.use input, then the dataframe is split into Target_data and Others_data based on subsetting by the target cells/samples.
Finally, a scatter plot is created using these dataframes.
Non-target cells are colored in gray if show.others=TRUE,
and target cell data is displayed on top, colored and shaped based on the color.var- and shape.by-associated data.
If split.by was used, the plot will be split into a matrix of panels based on the associated groupings.
Value
a ggplot scatterplot where colored dots and/or shapes represent individual cells/samples. X and Y axes can be gene expression, numeric metadata, or manually supplied values.
Alternatively, if data.out=TRUE, a list containing three slots is output: the plot (named 'p'), a data.table containing the underlying data for target cells (named 'Target_data'), and a data.table containing the underlying data for non-target cells (named 'Others_data').
Alternatively, if do.hover is set to TRUE, the plot is coverted from ggplot to plotly &
cell/sample information, determined by the hover.data input, is retrieved, added to the dataframe, and displayed upon hovering the cursor over the plot.
Many characteristics of the plot can be adjusted using discrete inputs
-
size and opacity can be used to adjust the size and transparency of the data points.
Colors used can be adjusted with color.panel and/or colors for discrete data, or min, max, min.color, and max.color for continuous data.
Shapes used can be adjusted with shape.panel.
Color and shape labels can be changed using rename.color.groups and rename.shape.groups.
Titles and axes labels can be adjusted with main, sub, xlab, ylab, and legend.title arguments.
Legends can also be adjusted in other ways, using variables that all start with "legend." for easy tab completion lookup.
Author(s)
Daniel Bunis and Jared Andrews
See Also
getGenes and getMetas to see what the x.var, y.var, color.var, shape.by, and hover.data options are of an object.
dittoDimPlot for making very similar data representations, but where dimensionality reduction (PCA, t-SNE, UMAP, etc.) dimensions are the scatterplot axes.
dittoDimHex and dittoScatterHex for showing very similar data representations, but where nearby cells are summarized together in hexagonal bins.
Examples
example(importDittoBulk, echo = FALSE)
myRNA
# Mock up some nCount_RNA and nFeature_RNA metadata
# == the default way to extract
myRNA$nCount_RNA <- runif(60,200,1000)
myRNA$nFeature_RNA <- myRNA$nCount_RNA*runif(60,0.95,1.05)
# and also percent.mito metadata
myRNA$percent.mito <- sample(c(runif(50,0,0.05),runif(10,0.05,0.2)))
dittoScatterPlot(
myRNA, x.var = "nCount_RNA", y.var = "nFeature_RNA")
# Shapes or colors can be overlaid representing discrete metadata
# or (only colors) continuous metadata / expression data by providing
# metadata or gene names to 'color.var' and 'shape.by'
dittoScatterPlot(
myRNA, x.var = "gene1", y.var = "gene2",
color.var = "groups",
shape.by = "SNP",
size = 3)
dittoScatterPlot(
myRNA, x.var = "gene1", y.var = "gene2",
color.var = "gene3")
# Note: scatterplots like this can be very useful for dataset QC, especially
# with percentage of mitochondrial reads as the color overlay.
dittoScatterPlot(myRNA,
x.var = "nCount_RNA", y.var = "nFeature_RNA",
color.var = "percent.mito")
# Data can be "split" or faceted by a discrete variable as well.
dittoScatterPlot(myRNA, x.var = "gene1", y.var = "gene2",
split.by = "timepoint") # single split.by element
dittoScatterPlot(myRNA, x.var = "gene1", y.var = "gene2",
split.by = c("groups","SNP")) # row and col split.by elements
# OR with 'extra.vars' plus manually faceting for added control
dittoScatterPlot(myRNA, x.var = "gene1", y.var = "gene2",
extra.vars = c("SNP")) +
facet_wrap("SNP", ncol = 1, strip.position = "left")
# Countours can also be added to help illuminate overlapping samples
dittoScatterPlot(myRNA, x.var = "gene1", y.var = "gene2",
do.contour = TRUE)
# Multiple continuous metadata or genes can also be plotted together by
# giving that vector to 'color.var':
dittoScatterPlot(myRNA, x.var = "gene1", y.var = "gene2",
color.var = c("gene3", "gene4"))
# This functionality can be combined with 1 additional 'split.by' variable,
# with the directionality then controlled via 'multivar.split.dir':
dittoScatterPlot(myRNA, x.var = "gene1", y.var = "gene2",
color.var = c("gene3", "gene4"),
split.by = "timepoint",
multivar.split.dir = "col")
dittoScatterPlot(myRNA, x.var = "gene1", y.var = "gene2",
color.var = c("gene3", "gene4"),
split.by = "timepoint",
multivar.split.dir = "row")
dtm2451/dittoSeq documentation built on May 5, 2024, 11:19 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
View source: R/DittoScatterPlot.R
| dittoScatterPlot | R Documentation |
Show RNAseq data overlayed on a scatter plot
Description
Show RNAseq data overlayed on a scatter plot
Usage
dittoScatterPlot(
object,
x.var,
y.var,
color.var = NULL,
shape.by = NULL,
split.by = NULL,
extra.vars = NULL,
cells.use = NULL,
multivar.split.dir = c("col", "row"),
show.others = FALSE,
split.show.all.others = TRUE,
size = 1,
opacity = 1,
color.panel = dittoColors(),
colors = seq_along(color.panel),
split.nrow = NULL,
split.ncol = NULL,
split.adjust = list(),
assay.x = .default_assay(object),
slot.x = .default_slot(object),
adjustment.x = NULL,
assay.y = .default_assay(object),
slot.y = .default_slot(object),
adjustment.y = NULL,
assay.color = .default_assay(object),
slot.color = .default_slot(object),
adjustment.color = NULL,
assay.extra = .default_assay(object),
slot.extra = .default_slot(object),
adjustment.extra = NULL,
swap.rownames = NULL,
shape.panel = c(16, 15, 17, 23, 25, 8),
rename.color.groups = NULL,
rename.shape.groups = NULL,
min.color = "#F0E442",
max.color = "#0072B2",
min = NA,
max = NA,
order = c("unordered", "increasing", "decreasing", "randomize"),
xlab = x.var,
ylab = y.var,
main = "make",
sub = NULL,
theme = theme_bw(),
do.hover = FALSE,
hover.data = NULL,
hover.assay = .default_assay(object),
hover.slot = .default_slot(object),
hover.adjustment = NULL,
do.contour = FALSE,
contour.color = "black",
contour.linetype = 1,
add.trajectory.lineages = NULL,
add.trajectory.curves = NULL,
trajectory.cluster.meta,
trajectory.arrow.size = 0.15,
do.letter = FALSE,
do.ellipse = FALSE,
do.label = FALSE,
labels.size = 5,
labels.highlight = TRUE,
labels.repel = TRUE,
labels.split.by = split.by,
labels.repel.adjust = list(),
legend.show = TRUE,
legend.color.title = "make",
legend.color.size = 5,
legend.color.breaks = waiver(),
legend.color.breaks.labels = waiver(),
legend.shape.title = shape.by,
legend.shape.size = 5,
do.raster = FALSE,
raster.dpi = 300,
data.out = FALSE
)
Arguments
object |
A Seurat, SingleCellExperiment, or SummarizedExperiment object. |
x.var, y.var |
Single string giving a gene or metadata that will be used for the x- and y-axis of the scatterplot. Note: must be continuous. Alternatively, can be a directly supplied numeric vector of length equal to the total number of cells/samples in |
color.var |
Single string giving a gene or metadata that will set the color of cells/samples in the plot. Alternatively, can be a directly supplied numeric or string vector or a factor of length equal to the total number of cells/samples in |
shape.by |
Single string giving a metadata (Note: must be discrete.) that will set the shape of cells/samples in the plot. Alternatively, can be a directly supplied string vector or a factor of length equal to the total number of cells/samples in |
split.by |
1 or 2 strings naming discrete metadata to use for splitting the cells/samples into multiple plots with ggplot faceting. When 2 metadatas are named, c(row,col), the first is used as rows and the second is used for columns of the resulting grid. When 1 metadata is named, shape control can be achieved with |
extra.vars |
String vector providing names of any extra metadata to be stashed in the dataframe supplied to Useful for making custom alterations after dittoSeq plot generation. |
cells.use |
String vector of cells'/samples' names OR an integer vector specifying the indices of cells/samples which should be included. Alternatively, a Logical vector, the same length as the number of cells in the object, which sets which cells to include. |
multivar.split.dir |
"row" or "col", sets the direction of faceting used for 'var' values when |
show.others |
Logical. FALSE by default, whether other cells should be shown in the background in light gray. |
split.show.all.others |
Logical which sets whether gray "others" cells of facets should include all cells of other facets ( |
size |
Number which sets the size of data points. Default = 1. |
opacity |
Number between 0 and 1. Great for when you have MANY overlapping points, this sets how solid the points should be: 1 = not see-through at all. 0 = invisible. Default = 1. (In terms of typical ggplot variables, = alpha) |
color.panel |
String vector which sets the colors to draw from. |
colors |
Integer vector, the indexes / order, of colors from color.panel to actually use |
split.nrow, split.ncol |
Integers which set the dimensions of faceting/splitting when a single metadata is given to |
split.adjust |
A named list which allows extra parameters to be pushed through to the faceting function call. List elements should be valid inputs to the faceting functions, e.g. 'list(scales = "free")'. For options, when giving 1 metadata to |
assay.x, assay.y, assay.color, assay.extra, slot.x, slot.y, slot.color, slot.extra |
single strings or integers (SCEs and SEs) or an optionally named vector of such values that set which expression data to use for each given data target.
See |
adjustment.x, adjustment.y, adjustment.color, adjustment.extra |
For the given data target, when targeting gene / feature expression, should that data be used directly (default) or should it be adjusted to be
|
swap.rownames |
optionally named string or string vector.
For SummarizedExperiment or SingleCellExperiment objects, its value(s) specifies the column name of rowData(object) to be used to identify features instead of rownames(object).
When targeting multiple modalities (alternative experiments), names can be used to specify which level / alternative experiment (use 'main' for the top-level) individual values should be used for.
See |
shape.panel |
Vector of integers corresponding to ggplot shapes which sets what shapes to use.
When discrete groupings are supplied by Note: Unfortunately, shapes can be hard to see when points are on top of each other & they are more slowly processed by the brain. For these reasons, even as a color blind person myself writing this code, I recommend use of colors for variables with many discrete values. |
rename.color.groups, rename.shape.groups |
String vector containing new names for the identities of the color or shape overlay groups. |
min.color |
color for |
max.color |
color for |
min, max |
Number which sets the values associated with the minimum or maximum colors. |
order |
String. If the data should be plotted based on the order of the color data, sets whether to plot (from back to front) in "increasing", "decreasing", "randomize" order.
If left as "unordered", plot order is simply based on the order of cells within the |
xlab, ylab |
Strings which set the labels for the axes. To remove, set to |
main |
String, sets the plot title.
A default title is automatically generated if based on |
sub |
String, sets the plot subtitle. |
theme |
A ggplot theme which will be applied before dittoSeq adjustments.
Default = |
do.hover |
Logical which controls whether the object will be converted to a plotly object so that data about individual points will be displayed when you hover your cursor over them.
|
hover.data |
String vector of gene and metadata names, example: |
hover.assay, hover.slot, hover.adjustment |
Similar to the x, y, color, and extra versions, when showing expression data upon hover, these set what data will be shown. |
do.contour |
Logical. Whether density-based contours should be displayed. |
contour.color |
String that sets the color(s) of the |
contour.linetype |
String or numeric which sets the type of line used for |
add.trajectory.lineages |
List of vectors representing trajectory paths, each from start-cluster to end-cluster, where vector contents are the names of clusters provided in the If the |
add.trajectory.curves |
List of matrices, each representing coordinates for a trajectory path, from start to end, where matrix columns represent x and y coordinates of the paths. |
trajectory.cluster.meta |
String name of metadata containing the clusters that were used for generating trajectories. Required when plotting trajectories using the |
trajectory.arrow.size |
Number representing the size of trajectory arrows, in inches. Default = 0.15. |
do.letter |
Logical which sets whether letters should be added on top of the colored dots. For extended colorblindness compatibility.
NOTE: |
do.ellipse |
Logical. Whether the groups should be surrounded by median-centered ellipses. |
do.label |
Logical. Whether to add text labels near the center (median) of clusters for grouping vars. |
labels.size |
Size of the the labels text |
labels.highlight |
Logical. Whether the labels should have a box behind them |
labels.repel |
Logical, that sets whether the labels' placements will be adjusted with ggrepel to avoid intersections between labels and plot bounds. TRUE by default. |
labels.split.by |
String of one or two metadata names which controls the facet-split calculations for label placements.
Defaults to |
labels.repel.adjust |
A named list which allows extra parameters to be pushed through to ggrepel function calls.
List elements should be valid inputs to the |
legend.show |
Logical. Whether any legend should be displayed. Default = |
legend.color.title, legend.shape.title |
Strings which set the title for the color or shape legends. |
legend.color.size, legend.shape.size |
Numbers representing the size at which shapes should be plotted in the color and shape legends (for discrete variable plotting). Default = 5. *Enlarging the icons in the colors legend is incredibly helpful for making colors more distinguishable by color blind individuals. |
legend.color.breaks |
Numeric vector which sets the discrete values to label in the color-scale legend for continuous data. |
legend.color.breaks.labels |
String vector, with same length as |
do.raster |
Logical. When set to |
raster.dpi |
Number indicating dots/pixels per inch (dpi) to use for rasterization. Default = 300. |
data.out |
Logical. When set to |
Details
This function creates a dataframe with X, Y, color, shape, and faceting data determined by x.var, y.var, color.var, shape.var, and split.by.
Any extra gene or metadata requested with extra.var is added as well.
For expression/counts data, assay, slot, and adjustment inputs (.x, .y, and .color) can be used to change which data is used, and if it should be adjusted in some way.
Next, if a set of cells or samples to use is indicated with the cells.use input, then the dataframe is split into Target_data and Others_data based on subsetting by the target cells/samples.
Finally, a scatter plot is created using these dataframes.
Non-target cells are colored in gray if show.others=TRUE,
and target cell data is displayed on top, colored and shaped based on the color.var- and shape.by-associated data.
If split.by was used, the plot will be split into a matrix of panels based on the associated groupings.
Value
a ggplot scatterplot where colored dots and/or shapes represent individual cells/samples. X and Y axes can be gene expression, numeric metadata, or manually supplied values.
Alternatively, if data.out=TRUE, a list containing three slots is output: the plot (named 'p'), a data.table containing the underlying data for target cells (named 'Target_data'), and a data.table containing the underlying data for non-target cells (named 'Others_data').
Alternatively, if do.hover is set to TRUE, the plot is coverted from ggplot to plotly &
cell/sample information, determined by the hover.data input, is retrieved, added to the dataframe, and displayed upon hovering the cursor over the plot.
Many characteristics of the plot can be adjusted using discrete inputs
-
sizeandopacitycan be used to adjust the size and transparency of the data points. Colors used can be adjusted with
color.paneland/orcolorsfor discrete data, ormin,max,min.color, andmax.colorfor continuous data.Shapes used can be adjusted with
shape.panel.Color and shape labels can be changed using
rename.color.groupsandrename.shape.groups.Titles and axes labels can be adjusted with
main,sub,xlab,ylab, andlegend.titlearguments.Legends can also be adjusted in other ways, using variables that all start with "
legend." for easy tab completion lookup.
Author(s)
Daniel Bunis and Jared Andrews
See Also
getGenes and getMetas to see what the x.var, y.var, color.var, shape.by, and hover.data options are of an object.
dittoDimPlot for making very similar data representations, but where dimensionality reduction (PCA, t-SNE, UMAP, etc.) dimensions are the scatterplot axes.
dittoDimHex and dittoScatterHex for showing very similar data representations, but where nearby cells are summarized together in hexagonal bins.
Examples
example(importDittoBulk, echo = FALSE)
myRNA
# Mock up some nCount_RNA and nFeature_RNA metadata
# == the default way to extract
myRNA$nCount_RNA <- runif(60,200,1000)
myRNA$nFeature_RNA <- myRNA$nCount_RNA*runif(60,0.95,1.05)
# and also percent.mito metadata
myRNA$percent.mito <- sample(c(runif(50,0,0.05),runif(10,0.05,0.2)))
dittoScatterPlot(
myRNA, x.var = "nCount_RNA", y.var = "nFeature_RNA")
# Shapes or colors can be overlaid representing discrete metadata
# or (only colors) continuous metadata / expression data by providing
# metadata or gene names to 'color.var' and 'shape.by'
dittoScatterPlot(
myRNA, x.var = "gene1", y.var = "gene2",
color.var = "groups",
shape.by = "SNP",
size = 3)
dittoScatterPlot(
myRNA, x.var = "gene1", y.var = "gene2",
color.var = "gene3")
# Note: scatterplots like this can be very useful for dataset QC, especially
# with percentage of mitochondrial reads as the color overlay.
dittoScatterPlot(myRNA,
x.var = "nCount_RNA", y.var = "nFeature_RNA",
color.var = "percent.mito")
# Data can be "split" or faceted by a discrete variable as well.
dittoScatterPlot(myRNA, x.var = "gene1", y.var = "gene2",
split.by = "timepoint") # single split.by element
dittoScatterPlot(myRNA, x.var = "gene1", y.var = "gene2",
split.by = c("groups","SNP")) # row and col split.by elements
# OR with 'extra.vars' plus manually faceting for added control
dittoScatterPlot(myRNA, x.var = "gene1", y.var = "gene2",
extra.vars = c("SNP")) +
facet_wrap("SNP", ncol = 1, strip.position = "left")
# Countours can also be added to help illuminate overlapping samples
dittoScatterPlot(myRNA, x.var = "gene1", y.var = "gene2",
do.contour = TRUE)
# Multiple continuous metadata or genes can also be plotted together by
# giving that vector to 'color.var':
dittoScatterPlot(myRNA, x.var = "gene1", y.var = "gene2",
color.var = c("gene3", "gene4"))
# This functionality can be combined with 1 additional 'split.by' variable,
# with the directionality then controlled via 'multivar.split.dir':
dittoScatterPlot(myRNA, x.var = "gene1", y.var = "gene2",
color.var = c("gene3", "gene4"),
split.by = "timepoint",
multivar.split.dir = "col")
dittoScatterPlot(myRNA, x.var = "gene1", y.var = "gene2",
color.var = c("gene3", "gene4"),
split.by = "timepoint",
multivar.split.dir = "row")
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.