---
title: "Visualisation Gallery"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Visualisation Gallery}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
resource_files:
- figures/logo.svg
- figures/logo-dark.svg
---
[](https://github.com/CTTIR/phenoscapR/actions/workflows/R-CMD-check.yaml)
[](https://cttir.github.io/phenoscapR/)
[](https://app.codecov.io/gh/CTTIR/phenoscapR?branch=main)
[](https://opensource.org/licenses/MIT)
[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.width = 7,
fig.height = 4.5,
dpi = 96
)
has_uwot <- requireNamespace("uwot", quietly = TRUE)
has_deldir <- requireNamespace("deldir", quietly = TRUE)
```
## Overview
Every phenoscapR plotting function returns a **ggplot** object, so you can add
themes, facets, or annotations as usual, and they all draw from the global
palette system for consistent colours across a figure panel. This gallery
shows each one on the bundled example data.
```{r prep}
library(phenoscapR)
library(ggplot2)
data(phenoscapR_example)
obj <- phenoscapR_example
obj@meta_data$phenotype <- obj@meta_data$phenotype_true
obj <- NormaliseData(obj, method = "zscore")
# A single tissue for the spatial maps.
a <- obj[obj$sample_id == "tonsil_A", ]
# Cell subsetting invalidates cached local density; compute it on this tissue.
a <- CellDensity(a, radius = 40)
markers <- c("CD20", "CD3", "CD8", "PanCK")
```
## Tissue maps
### `CellMap()` — phenotype map
```{r cellmap, fig.alt = "Synthetic tonsil A cell positions coloured by simulated phenotype."}
CellMap(a)
```
### `FeaturePlot()` — marker intensity in space
```{r featureplot, fig.height = 5, fig.alt = "Spatial distributions of normalised CD20, CD3, CD8 and PanCK intensity in synthetic tonsil A."}
FeaturePlot(a, features = markers)
```
### `DensityPlot()` — local cell density
```{r densityplot, fig.alt = "Synthetic tonsil A cell positions coloured by local cell density within radius 40."}
DensityPlot(a)
```
### `SpatialNetworkPlot()` — cell-contact graph
```{r network, eval = has_deldir, fig.alt = "Delaunay network of synthetic tonsil A cells, retaining edges no longer than 60."}
a_net <- DelaunayNetwork(a, max_edge = 60)
SpatialNetworkPlot(a_net)
```
## Marker distributions
### `ViolinPlot()` and `BoxPlot()`
```{r violin, fig.alt = "Violin distributions of four normalised marker intensities by simulated phenotype."}
ViolinPlot(a, features = markers, group_by = "phenotype")
```
```{r box, fig.alt = "Box plots of four normalised marker intensities by simulated phenotype."}
BoxPlot(a, features = markers, group_by = "phenotype")
```
### `RidgePlot()` and `HistogramPlot()`
```{r ridge, fig.alt = "Distributions of four normalised marker intensities by simulated phenotype."}
RidgePlot(a, features = markers, group_by = "phenotype")
```
```{r histogram, fig.height = 4, fig.alt = "Histograms of normalised CD20 intensity by simulated phenotype."}
HistogramPlot(a, feature = "CD20", group_by = "phenotype")
```
### `DotPlot()` — mean expression × fraction expressing
```{r dotplot, fig.height = 4, fig.alt = "Marker expression by simulated phenotype; dot colour shows mean expression and size shows the expressing fraction."}
DotPlot(a, features = c("CD3", "CD4", "CD8", "CD20", "CD68", "PanCK", "FoxP3"))
```
## Summaries
### `MarkerHeatmap()` — phenotype signatures
```{r heatmap, fig.height = 5, fig.alt = "Mean normalised marker intensities for each simulated phenotype."}
MarkerHeatmap(obj)
```
### `CompositionPlot()` — phenotype proportions
```{r composition, fig.height = 4, fig.alt = "Stacked simulated phenotype proportions in each synthetic section."}
CompositionPlot(obj, group_by = "sample_id")
```
### `InteractionPlot()` — co-localisation scores
```{r interactions, fig.alt = "Pairwise simulated phenotype interaction scores within the synthetic sections at radius 40."}
InteractionPlot(InteractionMatrix(obj, radius = 40))
```
### `QCPlot()` — any metadata pair
```{r qcplot, fig.height = 4, fig.alt = "Cell area versus local density in synthetic tonsil A, coloured by simulated phenotype."}
QCPlot(a, x = "cell_area", y = "density", colour_by = "phenotype")
```
## Dimensionality reductions
Reduce marker space and plot it with `DimPlot()` / `EmbeddingPlot()`.
```{r pca, fig.alt = "PCA embedding of synthetic cells coloured by simulated phenotype."}
obj <- RunPCA(obj, n_pcs = 10)
DimPlot(obj, reduction = "pca", colour_by = "phenotype")
```
```{r umap, eval = has_uwot, fig.alt = "UMAP embedding of synthetic cells coloured by simulated phenotype."}
# Base SVD is sufficient for this small marker panel and avoids dependence
# on an optional truncated-SVD solver when disconnected groups need PCA init.
obj <- RunUMAP(obj, dims = 10, n_neighbors = 15, seed = 1,
pca_method = "svd", n_threads = 1)
EmbeddingPlot(obj, reduction = "umap", colour_by = "phenotype")
```
## Theming and palettes
Because each plot is a plain ggplot, standard customisation just works:
```{r theme, fig.alt = "Synthetic tonsil A phenotype map with a customised title."}
CellMap(a) +
labs(title = "Tonsil A — phenotype map") +
theme(plot.title = element_text(face = "bold"))
```
The package palette is global. Set it once and every plot follows. Any
viridis-family option works (`"viridis"`, `"inferno"`, `"plasma"`,
`"cividis"`, `"rocket"`, `"mako"`):
```{r palette, fig.alt = "Stacked simulated phenotype proportions in each section using the rocket palette."}
SetPalette("rocket")
CompositionPlot(obj, group_by = "sample_id")
```
```{r reset-palette, include = FALSE}
SetPalette("viridis")
```
`PaletteDiscrete()`, `PaletteContinuous()`, and `CustomGradient()` expose the
same colours for use in bespoke plots.
```{r palette-fns}
PaletteDiscrete(5)
```
## See also
- **[Getting Started](phenoscapR.html)** — the end-to-end workflow
- **[Advanced Spatial Analysis](phenoscapR-03-spatial-analysis.html)** — the statistics behind these plots
