phenoscapR provides a complete toolkit for reading, processing, analysing, and visualising single-cell spatial biology data from multiplexed imaging platforms. It handles the full workflow from raw cell segmentation CSV files through quality control, marker normalisation, cell phenotyping, spatial statistics, and publication-ready visualisation — using an efficient data.table backend and a clean S4 object model (SpatialCellData).
Features
Data Import & Object Model
- Auto-detect and parse three CSV formats: QuPath Full Export, QuPath Minimal, and flat segmentation output
-
SpatialCellDataS4 class stores counts, normalised data, coordinates, metadata, and spatial results in one object - Familiar accessors:
NCells(),Markers(),Coords(),Meta(),GetData(),Idents(),[,[[,$
Quality Control & Preprocessing
- Filter cells by area and intensity range (
qc_filter()/QCFilter()) - Three normalisation methods: z-score, min-max, quantile (
normalise_markers()/NormaliseData()) - QC scatter plots (
QCPlot())
Phenotyping
- Marker-threshold-based cell phenotyping (
phenotype_cells()/PhenotypeCells()) - Per-sample phenotype proportion summaries (
summarise_phenotypes()/PhenotypeSummary())
Spatial Analysis
- Nearest-neighbour distances, local cell density, interaction matrices, spatial clustering
- Advanced statistics: Neighbourhood Enrichment, Ripley’s K, Moran’s I, Quadrat Analysis, Pair Correlation Function, Cross Nearest-Neighbour Distance, Delaunay Networks, Expression Clustering
Patient-level Inference and Registered Summaries
- Exact label-allocation tests for declared patient contrasts (
ExactPatientTests()) - Declared-family BH/BY adjustment with unavailable hypotheses retained (
AdjustPatientFamilies()) - Explicit registries, denominator provenance, grouped summaries, and spatial table projection without inferring patient identity or biological labels
Installation
phenoscapR requires R 4.1.0 or newer and is not on CRAN yet. Install it from GitHub:
if (!requireNamespace("pak", quietly = TRUE)) install.packages("pak")
pak::pak("CTTIR/phenoscapR")Optional canonical cell-table imports and SONG embeddings require packages available from the CTTIR R-universe:
# For FromCellspec()
install.packages("cellspecR", repos = c("https://cttir.r-universe.dev", getOption("repos")))
# For RunSONG()
install.packages("songR", repos = c("https://cttir.r-universe.dev", getOption("repos")))These packages are optional. Calling the corresponding function without its dependency reports an error; phenoscapR does not install packages automatically.
Quick Start
The package ships a synthetic two-sample example dataset, so you can run the whole workflow without any files of your own:
library(phenoscapR)
data(phenoscapR_example)
obj <- phenoscapR_example
obj <- NormaliseData(obj, method = "zscore")
obj <- PhenotypeCells(obj, thresholds = list(CD20 = 1, CD3 = 1, CD8 = 1,
CD68 = 1, PanCK = 1, FoxP3 = 1))
# Per-sample spatial structure
im <- InteractionMatrix(obj, radius = 40)
InteractionPlot(im)
# Single-tissue point-pattern statistics
a <- obj[obj$sample_id == "tonsil_A", ]
RipleysK(a, correction = "border")
NeighbourhoodEnrichment(a, radius = 40, n_perm = 199)
CellMap(a)A typical real analysis starts from your own segmentation output:
# 1. Read cell segmentation CSV (or a directory of them)
obj <- ReadSpatial("path/to/segmentation.csv", sample_id = "sample1")
# 2. Quality control
obj <- QCFilter(obj, min_area = 50, max_area = 500)
# 3. Normalise marker intensities
obj <- NormaliseData(obj, method = "zscore")
# 4. Assign phenotypes by marker thresholds
obj <- PhenotypeCells(obj, thresholds = list(CD3 = 0.5, CD8 = 0.3,
CD20 = 0.4, PanCK = 0.6))
# 5. Spatial analysis
obj <- FindNeighbours(obj, k = 5)
obj <- CellDensity(obj, radius = 50)
obj <- DelaunayNetwork(obj)
ne <- NeighbourhoodEnrichment(obj[obj$sample_id == "sample1", ],
radius = 50, n_perm = 100)
# 6. Visualise
CellMap(obj)
FeaturePlot(obj, features = c("CD3", "CD8"))
MarkerHeatmap(obj)
InteractionPlot(InteractionMatrix(obj, radius = 50))
SpatialNetworkPlot(obj)Input identity and figure files
Coordinate columns must contain actual numeric values; factor labels are not silently converted to integer codes. CSV readers preserve leading zeros in declared and reserved identifier columns: 001 and 1 remain distinct. QuPath Image names are retained in source_image. If different Image labels collapse to the same legacy sample identifier, import stops so you can supply distinct identities explicitly.
as_SpatialCellData() retains available normalized assays when importing from Seurat or SpatialExperiment. Seurat’s marker-name rewriting is refused on export; use SpatialExperiment when those exact names must be preserved.
SaveFigure() requires distinct PDF and PNG destinations in existing folders. It renders both formats before replacing either file. A reported rendering failure leaves previous files intact; a replacement failure attempts restoration and reports the path of any original backup it cannot restore. This recovery does not cover process termination or another program writing the same paths.
Interactive app
phenoscapR ships a Hugo Coder–themed Shiny app for the bundled synthetic teaching data and known simulated phenotypes. Explore QC, spatial statistics, cellular neighbourhoods, spatial domains, PCA/UMAP, and differential abundance with a light/dark toggle. It does not import user objects or export results; use the package functions for those workflows. Each example section is one sample in its own condition, so the displayed differential-abundance results are a demonstration, not replicated group inference.
# one-time: install the optional app dependencies
install.packages(c("shiny", "bslib", "sass", "thematic", "reactable",
"bsicons", "brand.yml"))
phenoscapR::run_app()Branding requires bslib >= 0.9.0. UMAP additionally requires uwot; selecting UMAP without it shows an installation hint, while PCA remains available. If a QC filter removes every cell, widen it or use Reset cell-area filter; the same session recovers without restarting the app.
The app’s visual design is adapted from the Hugo Coder theme (MIT) — colour tokens and flat aesthetic only, no source copied.
Documentation
Full documentation and vignettes are available at https://cttir.github.io/phenoscapR/
| Vignette | Description |
|---|---|
| Getting Started | End-to-end workflow with simulated data |
| The SpatialCellData Object | S4 class internals, accessors, and subsetting |
| Advanced Spatial Analysis | Ripley’s K, Moran’s I, neighbourhood enrichment, and choosing a statistic |
| Visualisation Gallery | Every plotting function, demonstrated on the example data |
Contributing
Bug reports and feature requests are welcome at https://github.com/CTTIR/phenoscapR/issues.
Authors
- R. Heller (author, maintainer; Ulm University) — ORCID 0000-0001-8006-9742
- E. Chteinberg (author; Ulm University) — ORCID 0000-0002-9231-9291
- H. Witte (author; Ulm University) — ORCID 0000-0001-5767-7125
Citation
citation("phenoscapR")R. Heller, E. Chteinberg, H. Witte (2026). phenoscapR: Read, Analyse, and Visualise Single-Cell Spatial Biology Data. R package version 1.0.0. https://cttir.github.io/phenoscapR/
Branding
Editable R sources and regeneration instructions are in tools/branding.
