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"))

## Arguments

cell_seg_path 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.

## Details

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.

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

## Examples

# NOT RUN {
# 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,
output_path=out_path)

# 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,
output_path=out_path)
# }