TissueMask

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:

1. Bins points onto a regular grid.
2. Convolves the occupancy grid with a 2-D Gaussian of width raster_sigma (in coordinate units).
3. Thresholds at raster_threshold x max. Cells above threshold are "inside".
4. Dissolves all "inside" cells via GEOS union — holes and islands emerge from the geometry automatically, with no ring-winding logic required.
5. 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 solver

Documentation

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_sigma sweep

License

MIT (c) Raredon Laboratory, Yale School of Medicine