TissueMask fits polygon spatial masks to XY point coordinate data — cell centroids, single-molecule transcript locations, or any spatial point process — and returns an sf geometry object that faithfully captures tissue shape, including internal voids (vessel lumens, necrotic cores) and disconnected fragments.
It is the first component of the TissueSuite family developed at the Raredon Laboratory, Yale School of Medicine.
Installation
# Install from GitHub (requires pak)
# install.packages("pak")
pak::pkg_install("RaredonLab/TissueMask")Optional method dependencies:
install.packages(c("concaveman", "MASS", "isoband", "ggplot2"))Quick start
library(TissueMask)
library(sf)
set.seed(42)
coords <- data.frame(
x = c(rnorm(500, 0, 5), rnorm(500, 20, 5)),
y = c(rnorm(500, 0, 5), rnorm(500, 20, 5))
)
# Fit mask with the recommended raster method
mask <- fit_spatial_mask(coords, method = "raster", plot = TRUE)
# Confirm all points are contained
pts <- sf::st_as_sf(coords, coords = c("x", "y"), crs = sf::NA_crs_)
stopifnot(all(sf::st_within(pts, sf::st_union(mask), sparse = FALSE)[, 1]))Methods
method |
Topology | Speed | Key packages |
|---|---|---|---|
"raster" (default)
|
Holes + islands | Fast |
sf only |
"kde" |
Holes + islands | Moderate |
MASS, isoband
|
"concave" |
No holes | Fast | concaveman |
"convex" |
No holes | Instant |
sf only |
Raster method (recommended)
The raster method:
- Bins points onto a regular grid.
- Convolves the occupancy grid with a 2-D Gaussian of width
raster_sigma(in coordinate units). - Thresholds at
raster_threshold x max. Cells above threshold are “inside”. - Dissolves all “inside” cells via GEOS union — holes and islands emerge from the geometry automatically, with no ring-winding logic required.
- Applies a morphological close to smooth the staircase boundary.
Key tuning parameters:
| Parameter | Effect |
|---|---|
raster_sigma up |
Holes fill in, islands merge, boundary smooths |
raster_sigma down |
Holes and fine structure preserved |
raster_threshold up |
Mask shrinks (requires denser coverage) |
raster_threshold down |
Mask grows (accepts sparse regions) |
Part of TissueSuite
TissueSuite
+-- TissueMask <- you are here
| fit_spatial_mask() -> sf sfc mask geometry
+-- TissueField (depends on TissueMask)
estimate_concentration_field() -> diffusion-clearance PDE solverDocumentation
Full documentation and rendered vignettes: https://raredonlab.github.io/TissueMask/
- Getting Started — all four methods with worked examples
-
Holes, Islands, and Parameter Tuning — donut, swiss-cheese, and archipelago topologies;
raster_sigmasweep