Creates an HTML report visualizing the location and nearest-neighbor relations for cells of pairs of phenotypes in a single field.

spatial_distribution_report(cell_seg_path, pairs, colors,
  phenotype_rules = NULL, output_path = NULL,
  pixels_per_micron = getOption("phenoptr.pixels.per.micron"))



Path to a cell seg data file.


A list of pairs of phenotypes. Each entry is a two-element vector. The report will contain one section for each pair showing the nearest neighbor relations between the two phenotypes.


A named list of phenotype colors to use when drawing the output.


(Optional) A named list. Item names are phenotype names and must match entries in pairs. Item values are selectors for select_rows.


Optional, path to the output HTML file. If omitted, output will be written to the directory containing cell_seg_path.


Conversion factor to microns (default 2 pixels/micron, the resolution of 20x MSI fields taken on Vectra Polaris and Vectra 3.). Set to NA to skip conversion.


A cell seg data file for the field is required. If a tissue segmentation or composite image of the field is available, it will be used as a background.

The report is saved to the same directory as the input file.

See the tutorial Selecting cells within a cell segmentation table for more on the use of pairs and phenotype_rules.

See also

Other distance functions: compute_all_nearest_distance, count_touching_cells, count_within_batch, count_within, distance_matrix, find_nearest_distance, subset_distance_matrix


# This example creates a report in the current user's
# home or Document directory.

cell_seg_path <- sample_cell_seg_path()

pairs <- list(
  c("CK+", "CD8+"),
  c("CK+", "CD68+"))
colors <- c('CK+'="cyan", "CD68+"="magenta", "CD8+"="yellow")
out_path <- path.expand('~/spatial_distribution_report.html')

spatial_distribution_report(cell_seg_path, pairs, colors,

# This example extends the previous example to restrict tumor cells to
# only PDL1+ cells.
# Note that spatial_distribution_report uses read_cell_seg_table
# so units are removed from the expression column names.

pairs <- list(
  c("CK+ PDL1+", "CD8+"),
  c("CK+ PDL1+", "CD68+"))
colors <- c("CK+ PDL1+"="cyan", "CD68+"="magenta", "CD8+"="yellow")
phenotype_rules <- list(
  "CK+ PDL1+"=list("CK+", ~`Entire Cell PDL1 (Opal 520) Mean`>3))

spatial_distribution_report(cell_seg_path, pairs, colors, phenotype_rules,
# }