Skip to contents

The SpatialCellData Object

S4 class representing a single-cell spatial biology experiment. Stores raw and normalised expression matrices, spatial coordinates, cell metadata, and spatial analysis results. Accessor methods let you interrogate and subset the object without touching slots directly.

SpatialCellData-class
The SpatialCellData Class
CreateSpatialObject()
Create a SpatialCellData Object from Existing Data
ReadSpatial()
Read Cell Segmentation Data into a SpatialCellData Object
NCells()
Get the Number of Cells
NMarkers()
Get the Number of Markers
Markers()
Get Marker Names
Coords()
Get Spatial Coordinates
Meta()
Get or Set Cell Metadata
GetData()
Get Expression Data
Idents()
Get Active Cell Identities
Embeddings()
Get a Dimensionality-Reduction Embedding
Reductions()
List Available Reductions
`$`(<SpatialCellData>)
Access Metadata Columns with $
dim(<SpatialCellData>)
Get Dimensions of a SpatialCellData Object
show(<SpatialCellData>)
Show a SpatialCellData Object
`[`(<SpatialCellData>)
Subset a SpatialCellData Object
`[[`(<SpatialCellData>)
Access Metadata Columns with [[

Data Import

Read cell segmentation CSV files from spatial imaging platforms and image analysis software. Three formats are auto-detected: QuPath Full Export, QuPath Minimal, and flat segmentation format.

read_spatial()
Read Single-Cell Spatial Biology Data
FromCellspec()
Import a Canonical Cell Table Without Losing Spatial Identity

Quality Control & Preprocessing

Filter cells by area and intensity thresholds, normalise marker intensities, and inspect QC distributions before downstream analysis.

qc_filter()
Quality Control Filter
QCFilter()
Quality Control Filter (SpatialCellData)
normalise_markers()
Normalise Marker Intensities
NormaliseData()
Normalise Marker Intensities (SpatialCellData)
QCPlot()
QC Scatter Plot

Phenotyping

Assign discrete phenotype labels to cells based on marker intensity thresholds and summarise phenotype composition per sample.

phenotype_cells()
Phenotype Cells by Marker Thresholds
PhenotypeCells()
Phenotype Cells (SpatialCellData)
summarise_phenotypes()
Summarise Phenotype Proportions
PhenotypeSummary()
Phenotype Summary (SpatialCellData)

Spatial Analysis

Compute spatial statistics including nearest-neighbour distances, local cell density, pairwise interaction matrices, spatial clustering, Delaunay networks, neighbourhood enrichment, Ripley’s K, Moran’s I, quadrat analysis, pair correlation, cross-nearest-neighbour distances, and expression-based clustering.

nearest_neighbours()
Compute Nearest Neighbour Distances
FindNeighbours()
Find Nearest Neighbours (SpatialCellData)
cell_density()
Compute Cell Density
CellDensity()
Cell Density (SpatialCellData)
interaction_matrix()
Spatial Interaction Matrix
InteractionMatrix()
Interaction Matrix (SpatialCellData)
spatial_clusters()
Spatial Cell Clustering
SpatialClusters()
Spatial Clusters (SpatialCellData)
DelaunayNetwork()
Delaunay Triangulation Network
NeighbourhoodEnrichment()
Neighbourhood Enrichment Analysis
RipleysK()
Ripley's K Function
MoransI()
Moran's I Spatial Autocorrelation
QuadratAnalysis()
Quadrat Analysis
AssignFixedGrid()
Assign Physical Cell Coordinates to Fixed Square Grids
SummarizeFixedGrid()
Summarize Cell Annotations Within Fixed Grids
SummarizeGroupedCountFractions()
Summarize Grouped Subset Counts as Fractions
CompleteRegisteredValues()
Complete Numeric Observations Against an Explicit Registry
ProjectSpatialTable()
Project Spatial Tables Without Changing Column Metadata
ApplyGroupedThresholds()
Apply Supplied Group Thresholds to Observations
SummarizeGroupedValues()
Summarize Continuous Observations in Explicit Groups
AssemblePairedSummaries()
Assemble Registered Paired Summaries
CorrelateGroupedRanks()
Correlate Paired Ranks Within Explicit Groups
ContrastGroupedRanks()
Compare Two Distributions Within Explicit Groups
CountDisjointEdges()
Count Undirected Edges Between Disjoint Node Sets
CountRadiusSets()
Count Reference Sets Within Explicit Euclidean Radii
BuildExactDelaunayEdges()
Build Explicitly Ordered Delaunay Graphs
PlanExactDelaunayWorkspace()
Preflight Integer Workspace Bounds for Exact Delaunay Construction
ContrastGroupedOverlap()
Contrast Explicit Groups Within Finite-Metric Overlap Strata
PairCorrelation()
Pair Correlation Function
CrossNNDistance()
Cross Nearest Neighbour Distance
ExpressionClusters()
Expression-Based Cell Clustering

Cellular Neighbourhoods & Domains

Higher-order spatial structure: group cells into cellular neighbourhoods (niches) by the phenotype composition of their local neighbourhood, or into spatial domains by their spatially smoothed expression. Annotate unsupervised clusters by their most enriched markers.

CellularNeighbourhoods()
Cellular Neighbourhoods (Niches)
SpatialDomains()
Spatial Domains
AnnotateClusters()
Annotate Clusters by Their Top Markers

Differential Testing

Compare phenotype composition across experimental conditions, using the sample as the unit of replication.

DifferentialAbundance()
Differential Abundance of Phenotypes Across Conditions
ExactPatientTests()
Exact Allocation Tests of Independent Patient Endpoints
LeaveOnePatientOut()
Exact Patient Omission Diagnostics for Declared Hypotheses
AdjustPatientFamilies()
Adjust Explicitly Declared Patient-Test Families
ContrastPatientEndpoints()
Exact Two-Group Contrasts for a Registry of Patient Endpoints
ExactPairedTests()
Exact Paired Sign-Flip Tests of Within-Subject Differences
PairedDifferences()
Build Paired Differences from Wide Subject Tables
BootstrapMedianInterval()
Bootstrap Percentile Interval of a Median
PermutationCorrelation()
Permutation Test of a Rank or Linear Correlation

Section Summaries and Parity Checks

Read cell tables from NumPy archives, summarise sections (nearest-target distances, composition, densities, Delaunay neighbour types) and compare recomputed tables or arrays with reference results by key and tolerance.

SummarizeNearestDistances()
Nearest-Target Distances Summarised per Cell Set
SummarizeCellComposition()
Cell-Type Composition, Densities and Declared State Fractions of a Section
NeighbourTypeCounts()
Count Neighbour Types over a Delaunay Graph with an Edge-Length Cut
CompareTables()
Compare a Recomputed Table with a Reference Table by Key
CompareArrays()
Compare Table Columns or Arrays with Arrays of a NumPy Archive
SummarizeComparisons()
Summarise Comparison Results into Pass/Fail Checks

Platform Readers

Import cell-level exports from imaging platforms. A general expression-plus-coordinates reader underlies per-vendor convenience wrappers for Xenium, CosMx, and MERSCOPE.

ReadMatrixCoords()
Read an Expression Matrix and a Coordinate/Metadata Table
ReadXenium()
Read 10x Xenium Cell Output
ReadCosMx()
Read NanoString CosMx Cell Output
ReadMERSCOPE()
Read Vizgen MERSCOPE Cell Output

Interoperability

Convert to and from the wider single-cell ecosystem (Seurat and SpatialExperiment).

as_Seurat()
Convert a SpatialCellData to a Seurat Object
as_SpatialExperiment()
Convert a SpatialCellData to a SpatialExperiment Object
as_SpatialCellData()
Convert a Seurat or SpatialExperiment Object to SpatialCellData

Dimensionality Reduction

Embed cells from their marker-expression profiles for visualisation. PCA uses base R and is always available; UMAP, t-SNE, and SONG are optional backends (uwot, Rtsne, and the CTTIR songR package). UMAP, t-SNE, and SONG run on the top principal components by default.

RunPCA()
Principal Component Analysis
RunUMAP()
UMAP Embedding
RunTSNE()
t-SNE Embedding
RunSONG()
SONG Embedding
Embeddings()
Get a Dimensionality-Reduction Embedding
Reductions()
List Available Reductions
VarianceExplained()
Variance Explained by Principal Components
EmbeddingPlot() DimPlot()
Plot a Dimensionality-Reduction Embedding
ScreePlot()
Scree Plot of PCA Variance

Visualisation

Publication-ready ggplot2 visualisations for cell maps, marker intensities, phenotype composition, spatial networks, and interaction heatmaps. High-level S4 methods work directly on a SpatialCellData object; lower-level helpers accept data.tables.

CellMap()
Plot Cell Map
FeaturePlot()
Feature Plot in Tissue Space
DensityPlot()
Plot Cell Density
SpatialNetworkPlot()
Plot Spatial Network
InteractionPlot()
Plot Spatial Interaction Heatmap
MarkerHeatmap()
Plot Marker Heatmap
ViolinPlot()
Violin Plot of Marker Expression
BoxPlot()
Box Plot of Marker Expression
DotPlot()
Dot Plot of Marker Expression
CompositionPlot()
Stacked Bar Plot of Phenotype Composition
RidgePlot()
Ridge Plot of Marker Expression
HistogramPlot()
Histogram of Marker Expression
QCPlot()
QC Scatter Plot
plot_cell_map()
Plot Cell Map
plot_density()
Plot Density Map
plot_heatmap()
Plot Marker Heatmap
plot_interactions()
Plot Interaction Heatmap

Manuscript Figures: Style and Composition

A compact journal figure style (typography, colours, line widths, tick placement and typesetting), page composition in millimetres with panel letters, headings, texts and legends, and figures rendered from declarative specifications.

ManuscriptStyle()
Manuscript Figure Style
ManuscriptPalettes()
Manuscript Palettes
ThemeManuscript()
Manuscript 'ggplot2' Theme
PtLinewidth()
Convert Points to a 'ggplot2' Line Width
NiceBreaks()
Tick Breaks of Common Plotting Code
FormatP()
Format P Values for Figures
FormatStatistic()
Format a Patient-Level Statistic Line
TypesetLabel()
Typeset Figure Text
FormatTemplate()
Fill Text Templates from Table Rows
ComposeFigure()
Compose a Multi-Panel Figure
FigurePanel()
Describe One Figure Panel
FigureText()
Place Text on a Figure Page
FigureGrob()
Place a Grob on a Figure Page
LegendKeys()
Legend Keys as a Grob
SaveFigure()
Save a Composed Figure as PDF and PNG
FigureGrammars()
Figure Plot Builders Available to Figure Specifications
RenderFigure()
Render a Figure from a Specification
ReadFigureSpec()
Read a Figure Specification
WriteFigure()
Write a Figure from a Specification
ReadPlotTable()
Read a Plot Data Table

Manuscript Figures: Plot Grammars

Panel builders registered in FigureGrammars(): patient-level displays, matrices, bars, embeddings, cell maps, territories and image fields.

PlotPairedPatients()
Paired Patient Lines
PlotQuantileCurves()
Summary Curves with Quantile Bands
PlotBandProfiles()
Profiles over Ordered Categories
PlotIntervalForest()
Interval Forest with Unit Values
PlotGroupDifferences()
Differences Between Groups as Segments
PlotVolcano()
Volcano Plot of Exact Group Tests
PlotGroupStrip()
Unit Values by Group
PlotScatterGroups()
Scatter or Dot Rows Coloured by Group
PlotBars()
Bars per Unit
PlotTextBlock()
Text Block or Text Table
PlotStackedBars()
Stacked Bars
PlotAnnotatedHeatmap()
Annotated Heatmap
PlotDotMatrix()
Dot Matrix
PlotAlterationMatrix()
Alteration Matrix
PlotEmbedding()
Embedding Scatter
PlotDensityOutlines()
Density Outlines on an Embedding
PlotCellMap()
Cell Map
PlotTerritories()
Cell Territory Map
PlotFluorescenceField()
Multichannel Fluorescence Field
PlotImage()
Image, Image Gallery or Schematic

Manuscript Figures: Plot Data

Generic table helpers (PlotData*) that select, reshape, join, recode, count and summarise tables for the grammars, and builders for embeddings, annotated matrices, families of tests and image panels.

PlotDataBindRows() PlotDataBindColumns()
Bind Plot Data Tables
PlotDataConstant()
Add a Constant Column
PlotDataContrastSummary()
Summary of a Family of Two-Group Tests
PlotDataCount()
Counts and Shares by Group
PlotDataCrossShares()
Shares of One Category within Another
PlotDataDirection()
Count of Units in the Direction of an Estimate
PlotDataDominant()
Order Groups by Their Dominant Category
PlotDataFromArrays()
Table from a List of Arrays
PlotDataJoin()
Join Columns of Another Table
PlotDataKeyColours()
Key Colours from a Categorical Palette
PlotDataLabels() PlotDataCollapse()
Text Labels from Table Rows
PlotDataLonger()
Reshape Wide Columns into Long Plot Data
PlotDataMembership()
Flag Rows Whose Key Occurs in Another Table
PlotDataPairRatio()
Ratios Between Two Levels of a Key Column
PlotDataProduct()
Product of Columns
PlotDataQuantiles()
Quantile Summaries of Plot Data
PlotDataRankRows()
Rank Rows by the Sum of Selected Columns
PlotDataRatio()
Ratios Between Columns
PlotDataRecode()
Recode the Values of a Column
PlotDataRelative()
Scale a Column to a Reference Row
PlotDataSelect()
Select Rows and Columns of Plot Data
PlotDataShares()
Shares of a Total in Several Columns
PlotDataSummarise()
Summarise Columns by Group
PlotDataTableCells()
Text-Table Cells from a Per-Unit Table
PlotDataUnite()
Paste Columns into a Key Column
ExactPermutationBound()
Lower Bound of an Exact Two-Sided Permutation P Value
EmbeddingLimits()
Display Limits of an Embedding
EmbeddingLayers()
Layered Point Data for an Embedding
ClusterLabelPositions()
Label Positions of Clusters on an Embedding
DensityLevelContour()
Density Level Region of Each Group on an Embedding
LookupNestedRows()
Look Up Values Stored on Nested Row Subsets
AnnotationTracks()
Coloured Annotation Tracks
AlterationMatrixData()
Alteration Classes for an Alteration Matrix
NearestLabelDistance()
Distance to the Nearest Cell of Given Labels
CellMapData()
Cells of a Map Field or Whole Section
FieldCentre()
Field Centre as Plot Data
DensestGridWindow()
Centre of the Densest Grid Window
NearestPartnerPairs()
Cells Paired with Their Nearest Partner Cell
FieldCellsRanked()
Cells of One Type inside a Field, Ranked
TerritoryTiles()
Voronoi Territory Tiles of the Cells in a Field
BestSubWindow()
Sub-Window with the Most Cells of a Kind
CompositeFields()
Composite Fluorescence Images from Channel Fields
SchematicShapes()
Schematic Shapes from a Specification
CellPositionsFor()
Attach Cell Positions to a Table of Cell References

Colour Palettes

Manage the global colour palette used by all plotting functions. Supports viridis options and custom gradients defined by 2-3 anchor colours.

SetPalette() GetPalette()
Set or Get the Default Colour Palette
PaletteContinuous()
Generate a Continuous Colour Palette Function
PaletteDiscrete()
Generate Discrete Colours
CustomGradient()
Create a Custom Gradient Palette from Anchor Colours

Shiny Application

Launch the interactive phenoscapR Shiny interface to explore bundled synthetic teaching data with live plots and tables.

run_app()
Launch the phenoscapR Shiny Application

Datasets

Bundled example data used throughout the documentation and vignettes.

phenoscapR_example
Synthetic multiplexed-imaging example dataset