Package 'phenoscapR'

Description

Subset a SpatialCellData Object

Usage

## S4 method for signature 'SpatialCellData'
x[i, j, drop = FALSE]

Arguments

Value

A subsetted SpatialCellData object.

Description

Access Metadata Columns with [[

Usage

## S4 method for signature 'SpatialCellData'
x[[i]]

Arguments

Value

The requested metadata column.

Description

Access Metadata Columns with $

Usage

## S4 method for signature 'SpatialCellData'
x$name

Arguments

Value

The requested metadata column.

Description

Computes finite-only BH for historical comparison and declared-family BH/BY using every registered hypothesis as the adjustment count. Unavailable p values remain NA. Family IDs define the entire correction scope: include setting and contrast in the ID only when separate families are intended. A retrospective family registry is not prospective registration, and neither adjustment establishes biological validity or study-wide error control.

Usage

AdjustPatientFamilies(tests, policy, method = c("BH", "BY"))

Arguments

Value

A list with tests (input columns plus all adjustment variants, selected p_adjusted, policy and method) and families (declared, testable and unavailable counts). Every NA is retained in the original row order.

Examples

x <- data.frame(hypothesis_id = c("h1", "h2"), family_id = "f",
                p_value = c(0.03, NA))
AdjustPatientFamilies(x, policy = "declared")

Description

Turns a gene-by-sample table of alteration types (several types joined by a separator) into one class per gene and item: types are mapped to classes (for example nonsense, frameshift and splice variants to "Truncating"), and a gene with more than one class in a sample is "Multiple". Genes are selected and ordered as first, then genes altered in at least min_count samples by decreasing count (ties in table order), then last.

Usage

AlterationMatrixData(
  matrix,
  gene = NULL,
  ids,
  id_map = NULL,
  map_from = NULL,
  map_to = NULL,
  first = NULL,
  last = NULL,
  min_count = 1,
  classes = list(Truncating = c("Nonsense", "Frameshift", "Splice")),
  multiple = "Multiple",
  separator = "|"
)

Arguments

Value

A long data frame with gene, id, class (missing if none), count (altered samples of the gene in the table), percent (count relative to the number of items) and gene_rank.

Examples

m <- data.frame(gene = c("G1", "G2"), S1 = c("Missense", ""),
                S2 = c("Nonsense|Missense", "Deletion"))
AlterationMatrixData(m, ids = c("S1", "S2"), min_count = 1)

Description

Labels each cluster (or any categorical grouping) by the markers most enriched in it relative to the global mean, producing human-readable names such as "CD3+CD8".

Usage

AnnotateClusters(
  object,
  group = "expr_cluster",
  slot = "data",
  n_markers = 2L,
  add_column = TRUE
)

Arguments

Value

A named character vector mapping each group level to its marker label. If add_column the object is returned instead, with the label column added (access the mapping via attr(., "labels")).

Examples

data(phenoscapR_example)
obj <- NormaliseData(phenoscapR_example, "zscore")
obj <- ExpressionClusters(obj, k = 6)
AnnotateClusters(obj, add_column = FALSE)

Description

Builds categorical annotation tracks (for example clinical group, co-mutation, architecture) for a set of items: each track takes a value column, maps values to colours by exact values or regular expressions and uses a default colour otherwise.

Usage

AnnotationTracks(data, id, tracks, style = ManuscriptStyle())

Arguments

Value

A long data frame with id, track, value, colour and track_rank.

Examples

d <- data.frame(p = c("a", "b"), grp = c("x", "y"), mut = c("yes", "no"))
AnnotationTracks(d, "p", list(
  list(name = "Group", column = "grp", colours = c(x = "groups/group1", y = "groups/group2")),
  list(name = "Mutation", column = "mut", colours = c(yes = "#222222"), default = "#E0E0E0")))

Description

Looks up one supplied threshold per composite group and tests strictly greater than. Thresholds are not estimated; equality is FALSE. Eligibility and numeric availability remain explicit. No labels, units or observation universe are inferred. Unknown groups fail, including groups of ineligible observations.

Usage

ApplyGroupedThresholds(
  data,
  thresholds,
  groups,
  id,
  value,
  threshold,
  eligible
)

Arguments

Value

A data frame with all original observation columns unchanged, followed by threshold_value (double), threshold_available and value_available (logical), above_threshold (logical or NA), and threshold_status (character). Original columns with these reserved names fail. Status precedence is INELIGIBLE, UNKNOWN_ELIGIBILITY, MISSING_VALUE_AND_THRESHOLD, MISSING_THRESHOLD, MISSING_VALUE, COMPLETE. Availability flags retain numeric missingness independently of eligibility. Only eligible observations with both numbers known receive a comparison. Empty inputs retain typed outputs; nonempty observations require complete group-reference coverage. Metadata classes and the original value storage type are preserved. Units must agree upstream; no conversion is performed.

Examples

d <- data.frame(group = "a", id = c("x", "y"), value = c(1, 2), eligible = TRUE)
r <- data.frame(group = "a", cutoff = 1)
ApplyGroupedThresholds(d, r, "group", "id", "value", "cutoff", "eligible")

Description

Builds a Seurat object with raw counts, normalised data, cell metadata, and the spatial coordinates stored both in metadata (x, y) and as a "spatial" dimensional reduction. Cell IDs repeated across samples are made unique with make.unique() for the Seurat cell names; the metadata keep the original cell_id. Export refuses marker identifiers that Seurat would rewrite (such as underscores); use as_SpatialExperiment() for unchanged identifiers, or rename markers explicitly before export.

Usage

as_Seurat(object)

Arguments

Value

A Seurat object.

Examples

if (requireNamespace("Seurat", quietly = TRUE)) {
  data(phenoscapR_example)
  se <- as_Seurat(phenoscapR_example)
}

Description

Imports an object from the wider ecosystem. Coordinates are taken from spatialCoords (SpatialExperiment) or from x/y metadata columns or a "spatial" reduction (Seurat). The normalized logcounts assay (SpatialExperiment) or data layer (Seurat) is retained when present; raw counts are used as data only when it is absent. Normalized assays must contain the same cells and features as counts; named axes are aligned, and incompatible partial assays are refused. All-missing features are retained. Existing cell identifiers are kept; absent cell_id metadata use the source cell names when available. No normalization method is inferred or applied.

Usage

as_SpatialCellData(x, ...)

Arguments

Value

A SpatialCellData-class object.

Examples

if (requireNamespace("Seurat", quietly = TRUE)) {
  counts <- matrix(c(5, 0, 3, 1, 2, 7, 0, 4, 6, 1, 2, 3), nrow = 4,
                   dimnames = list(NULL, c("CD3", "CD8", "CD20")))
  obj <- CreateSpatialObject(counts, data.frame(x = c(1, 5, 9, 4), y = c(2, 8, 3, 6)))
  seurat_object <- as_Seurat(obj)
  as_SpatialCellData(seurat_object)
}

Description

Builds a SpatialExperiment with counts and logcounts assays (markers x cells), the metadata as colData, and the coordinates as spatialCoords.

Usage

as_SpatialExperiment(object)

Arguments

Value

A SpatialExperiment object.

Examples

if (requireNamespace("SpatialExperiment", quietly = TRUE)) {
  counts <- matrix(c(5, 0, 3, 1, 2, 7, 0, 4, 6, 1, 2, 3), nrow = 4,
                   dimnames = list(NULL, c("CD3", "CD8", "CD20")))
  obj <- CreateSpatialObject(counts, data.frame(x = c(1, 5, 9, 4), y = c(2, 8, 3, 6)))
  spe <- as_SpatialExperiment(obj)
}

Description

Aligns already computed scalar summaries to an explicit expected group registry. Computes the first side or first minus second side without pooling observations or changing the supplied estimator. Choose the value and count columns appropriate to the estimator, for example weighted_mean and n_weighted_available from SummarizeGroupedValues(). This is descriptive assembly, not an independence assessment or inferential test.

Usage

AssemblePairedSummaries(
  data,
  registry,
  groups,
  side,
  value,
  count,
  weight_sum = NULL,
  sides = c("A", "B"),
  contrast = c("difference", "first"),
  min_count = 1L
)

Arguments

Details

Absent sides retain NA values, zero counts and a false presence flag. Observed NA counts remain unknown. Optional weight totals are provenance only and never used to reconstruct counts or recompute supplied values. The registry defines output order; extra registry columns are ignored.

Value

Data frame in registry order with keys, first/second presence, values, counts and weight totals, value, status, contrast, side labels and minimum. Status precedence is MISSING_SIDE, UNKNOWN_COUNT, INSUFFICIENT_COUNT, UNAVAILABLE_VALUE, COMPLETE, considering required sides only. An empty registry with empty data returns a typed empty table. Unknown group/side keys, duplicates, malformed numbers and arithmetic overflow fail.

Examples

d <- data.frame(sample = c("one", "one"), arm = c("A", "B"),
                average = c(4, 1), n = c(3, 2))
AssemblePairedSummaries(d, data.frame(sample = c("one", "two")),
                        "sample", "arm", "average", "n")

Description

Assigns every supplied cell independently in each setting. Bins are half-open intervals: an exact boundary belongs to the bin on its positive side. Negative coordinates use floor division. No rounding or tolerance is applied. Samples remain separate even when coordinates overlap. Select eligible cells explicitly before calling; this function does not filter, classify, or infer review status.

Usage

AssignFixedGrid(cells, settings, frames)

Arguments

Details

The result describes detection locations, not tissue regions. Square bin area is not observed tissue area and must not be used as an inferred tissue-density denominator. Frame identifiers bind already calibrated coordinates; no unit, origin, axis, crop or registration conversion is performed.

Value

Data frame ordered by setting, sample and cell ID (radix order), with those keys, frame ID, integer grid indices, physical bounds and grid size. Bins are keyed by ⁠(setting_id, sample_id, grid_x, grid_y)⁠, never coordinates alone. Unrepresentable bounds and indices outside the R integer range fail. When the rounded division puts a coordinate outside its bin, the index is corrected against the computed bounds; bounds that still exclude an assigned cell fail. No tolerance or coordinate correction is introduced. Extra input columns are ignored; inputs are not modified.

Examples

cells <- data.frame(cell_id = c("a", "b"), sample_id = "s",
  frame_id = "physical", x = c(-1, 10), y = c(0, 0))
settings <- data.frame(setting_id = "g", size_um = 10,
  offset_x_um = 0, offset_y_um = 0)
frames <- data.frame(sample_id = "s", frame_id = "physical", unit = "um")
AssignFixedGrid(cells, settings, frames)

Description

Scans square sub-windows of width sub on a grid of spacing step inside a field and returns the one holding the most cells that match filter (first maximum in row-major grid order, x varying fastest).

Usage

BestSubWindow(
  cells,
  centre,
  size,
  sub,
  filter = list(),
  ranges = list(),
  step = 10,
  x = "x",
  y = "y"
)

Arguments

Value

One-row data frame with x, y, n, dx, dy (offset from the field centre).

Examples

set.seed(1)
d <- data.frame(x = c(runif(40, 0, 100), runif(20, 60, 80)),
                y = c(runif(40, 0, 100), runif(20, 20, 40)),
                label = rep(c("a", "b"), c(40, 20)))
BestSubWindow(d, centre = c(50, 50), size = 100, sub = 20, filter = list(label = "b"))

Description

Resamples the finite values of each group with replacement and reports the percentile interval of the resampled medians (quantile type 7, which is NumPy's default linear percentile). Draws come from R's Mersenne-Twister generator with a declared seed, or from supplied resampling indices (for example indices archived from another implementation), so that the interval can be reproduced exactly.

Usage

BootstrapMedianInterval(
  data,
  value,
  groups = NULL,
  n_boot = 10000L,
  conf_level = 0.95,
  seed = NULL,
  reseed = TRUE,
  indices = NULL,
  index_base = 1L
)

Arguments

Value

A data frame with the group columns, n, median, lower, upper, conf_level, n_boot, seed and draws ("R_MERSENNE_TWISTER" or "SUPPLIED").

Examples

d <- data.frame(g = rep(c("a", "b"), each = 8), v = c(1:8, (1:8)^2))
BootstrapMedianInterval(d, "v", "g", n_boot = 2000, seed = 42)

Description

Box plot showing the distribution of marker expression across phenotypes or other grouping variables.

Usage

BoxPlot(
  object,
  features,
  group_by = "phenotype",
  slot = "data",
  colours = NULL,
  ncol = NULL
)

Arguments

Value

A ggplot object.

Examples

counts <- matrix(c(rnorm(30, 5), rnorm(30, 1)), ncol = 2,
                 dimnames = list(NULL, c("CD3", "CD8")))
coords <- data.frame(x = runif(30), y = runif(30))
meta <- data.frame(cell_id = 1:30, sample_id = "s1",
                   phenotype = rep(c("T cell", "Other"), each = 15))
obj <- CreateSpatialObject(counts, coords, meta)
BoxPlot(obj, features = c("CD3", "CD8"))

Description

Constructs each complete declared geometry before selecting edges whose two endpoints are eligible. Uses deldir::deldir() with no fallback, coordinate rounding, jitter or population inference.

Usage

BuildExactDelaunayEdges(
  nodes,
  frames,
  groups,
  frame,
  id,
  x,
  y,
  point_order,
  orientation_rank,
  geometry,
  eligible,
  unit_column,
  coordinate_unit,
  edge_order,
  window_policy,
  cap_policy,
  backend_contract = NULL,
  eps,
  mode,
  caps = numeric(),
  initial_madj = 64L,
  max_retries = 32L
)

Arguments

Details

Supported columns are dimensionless, unclassed base character, integer/double or logical vectors as appropriate. Names are allowed. Factors, integer64 and arbitrary classed columns are rejected without coercion. Data frames and data.tables are supported containers. Keys must be nonmissing and nonblank. Selected roles are distinct within each table. Node roles cannot be named source_row or geometry_index; group/frame keys cannot collide with output edge or frame-summary fields. Duplicate IDs across different frames are valid.

Every frame is preflighted before construction begins. A declared frame needs at least three distinct noncollinear geometry points; a declared empty frame fails. A completely empty registry and empty node table return typed empty outputs without loading or executing the backend. Integer workspace and conservative combined edge/cap bounds are checked before allocation; they do not certify available memory. A finite direct-determinant guard is deliberately conservative for extreme or nearly collinear coordinates. Unsupported geometry fails rather than being perturbed. Distances must be finite and positive.

Complete edges are checked for whole in-range nonself indices, exact endpoint coordinate reconciliation, duplicate unordered pairs, connectedness and planar cardinality bounds before eligibility induction. These necessary invariants alone are not an independent proof of Delaunay geometry. Co-circular choices depend on the deldir version and explicit point order. Numeric orientation ranks and UTF-8 output ordering do not infer a historical locale or ordering policy.

deldir is optional: a missing installation fails clearly for nonempty construction. Each frame calls deldir::deldir(x, y, rw, eps, sort = TRUE, round = FALSE) on the geometry points in point_order. Warnings and unexpected messages fail closed; messages announcing that deldir enlarged its workspace are counted in the frame provenance (workspace_growth). No incomplete tessellation is returned. The frame provenance records the deldir version.

Value

A list with schema_version = "0.1.0", nodes (including input source_row and ordered geometry_index), full_edges, analysis_edge_rows, cap_flags, caps, frames and provenance. full_edges contains keys, endpoint IDs/geometry indices/orientation ranks, coordinates, distance, analysis_edge and edge_row. Frame counts distinguish all nodes, geometry, eligible nodes, full edges and induced edges. frame_construction contains keyed per-frame engine/workspace receipts in input registry order; output tables sort independently. No input is modified.

Examples

PlanExactDelaunayWorkspace(100, mode = "stock")$native_buffer_bytes
if (requireNamespace("deldir", quietly = TRUE)) {
  nodes <- data.frame(
    sample = "one", frame = "image", id = c("a", "b", "c", "d"),
    x = c(0, 4, 0, 3), y = c(0, 0, 3, 4), input = 1:4, orientation = 1:4,
    geometry = TRUE, eligible = c(TRUE, TRUE, TRUE, FALSE)
  )
  frames <- data.frame(sample = "one", frame = "image", unit = "um")
  graph <- BuildExactDelaunayEdges(nodes, frames, "sample", "frame", "id",
    "x", "y", "input", "orientation", "geometry", "eligible", "unit", "um",
    "orientation_rank", "span_padding_v1", "distance_leq",
    eps = 1e-9, mode = "stock", caps = c(short = 3, long = 5)
  )
  graph$full_edges
}

Description

Estimates the local cell density around each cell using a circular neighbourhood of a given radius.

Usage

cell_density(dt, radius, target_phenotype = NULL)

Arguments

Value

The input data.table with an added density column representing the number of neighbours within the specified radius.

Examples

dt <- data.table::data.table(
  sample_id = "s1", cell_id = 1:50,
  x = runif(50, 0, 100), y = runif(50, 0, 100)
)
result <- cell_density(dt, radius = 20)
head(result[, .(cell_id, density)])

Description

Estimates local cell density by counting neighbours within a radius.

Usage

CellDensity(object, radius, target = NULL)

Arguments

Value

An SpatialCellData-class with density added to meta_data.

Examples

counts <- matrix(rnorm(100), nrow = 50,
                 dimnames = list(NULL, c("CD3", "CD8")))
coords <- data.frame(x = runif(50, 0, 100), y = runif(50, 0, 100))
obj <- CreateSpatialObject(counts, coords)
obj <- CellDensity(obj, radius = 20)

Description

Scatter plot of cell positions coloured by phenotype, cluster, or any metadata column. Analogous to Seurat's DimPlot but in tissue space.

Usage

CellMap(
  object,
  colour_by = "phenotype",
  colours = NULL,
  pt_size = 0.5,
  title = NULL,
  dark_theme = FALSE
)

Arguments

Value

A ggplot object.

Examples

counts <- matrix(rnorm(100), nrow = 50,
                 dimnames = list(NULL, c("CD3", "CD8")))
coords <- data.frame(x = runif(50, 0, 500), y = runif(50, 0, 500))
obj <- CreateSpatialObject(counts, coords)
obj <- PhenotypeCells(obj, thresholds = list(CD3 = 0, CD8 = 0))
CellMap(obj)

Description

Prepares the input of PlotCellMap(): the cells inside a square field (or all cells for a whole-section map), the field geometry and, when requested, the interface zone, i.e. the points of a regular grid that lie within radius of a reference cell type (for example the tumour-stroma interface within 20 micrometres of a tumour cell).

Usage

CellMapData(
  cells,
  centre = NULL,
  size = NULL,
  centre_cell = NULL,
  id = "row",
  grid = NULL,
  offset = NULL,
  interface = NULL,
  classes = NULL,
  margin = 0,
  x = "x",
  y = "y",
  label = "label"
)

Arguments

Details

The field centre is given directly, taken from a cell (centre_cell, the value of column id), taken from the first row of a data frame with columns x and y, snapped to a regular grid anchored at the minimum cell coordinates (grid), and finally shifted by offset.

Value

A list of class phenoscapR_cellmap with cells, interface (data frame of grid points in the zone, or NULL), centre, size, step and extent (c(xmin, xmax, ymin, ymax)).

Examples

set.seed(1)
d <- data.frame(x = runif(200, 0, 100), y = runif(200, 0, 100),
                label = sample(c("t", "a"), 200, TRUE))
m <- CellMapData(d, centre = c(50, 50), size = 40,
                 interface = list(labels = "t", radius = 5, step = 2))
nrow(m$cells)

Description

Looks up cells referenced by image and row (as in review ledgers and example lists) in per-image cell tables and adds their positions and further columns.

Usage

CellPositionsFor(
  table,
  cells,
  labels = NULL,
  source = "sample_id",
  row = "row",
  columns = c("x", "y", "label")
)

Arguments

Value

table with the added columns.

Examples

cells <- list(s1 = data.frame(row = 0:2, x = c(1, 5, 9), y = c(2, 4, 6), label = "a"),
              s2 = data.frame(row = 0:1, x = c(3, 7), y = c(1, 1), label = "b"))
refs <- data.frame(sample_id = c("s2", "s1"), row = c(1, 2))
CellPositionsFor(refs, cells)

Description

Assigns each cell to a cellular neighbourhood ("niche") by clustering cells on the phenotype composition of their local spatial neighbourhood. This is the windowed-neighbourhood approach popularised for multiplexed imaging: for every cell the phenotype frequencies among its k nearest neighbours form a composition vector, and those vectors are clustered.

Usage

CellularNeighbourhoods(
  object,
  n_neighbourhoods = 8L,
  k = 20L,
  phenotype_col = "phenotype",
  seed = NULL
)

Arguments

Value

The object with a neighbourhood column in meta_data; the neighbourhood-by-phenotype composition matrix is stored in object@spatial$neighbourhood_composition.

Examples

data(phenoscapR_example)
obj <- phenoscapR_example
obj@meta_data$phenotype <- obj@meta_data$phenotype_true
obj <- CellularNeighbourhoods(obj, n_neighbourhoods = 5, k = 15, seed = 1)
table(obj$neighbourhood)

Description

The median position of the points of each cluster with at least min_points points, for numbering clusters on the embedding.

Usage

ClusterLabelPositions(
  data,
  x = "x",
  y = "y",
  cluster = "cluster",
  filter = NULL,
  min_points = 150
)

Arguments

Value

A data frame with label, x, y and n, ordered by cluster.

Examples

d <- data.frame(x = c(1, 2, 3, 10), y = c(1, 1, 2, 5), cl = c(1, 1, 1, 2))
ClusterLabelPositions(d, cluster = "cl", min_points = 2)

Description

Compares observed vectors or matrices (taken from columns of a table or elements of a list) with reference arrays, read from an .npz archive with cellspecR::cs_read_npz() or given as a list. Shapes must agree; values are compared exactly or within an absolute tolerance.

Usage

CompareArrays(observed, reference, arrays, tolerance = 0, check = "arrays")

Arguments

Value

A data frame with one row per array: check, row_key (array name), array, observed_dim, reference_dim, reference_type, n_values, n_different, max_difference, tolerance, matches and status (MATCH, MISMATCH, SHAPE_MISMATCH).

Examples

obs <- data.frame(a = 1:3, b = c(0, 1, 0), z = c(0.5, 1.5, 2.5))
ref <- list(counts = cbind(1:3, c(0, 1, 0)), z = c(0.5, 1.5, 2.5))
CompareArrays(obs, ref, list(counts = c("a", "b"), z = "z"))

Description

Joins two tables on declared key columns (which must be unique in both) and compares declared value columns: numbers within an absolute tolerance, everything else (text, logical) exactly. Missing values match only missing values. Keys present in one table only are reported.

Usage

CompareTables(
  observed,
  reference,
  keys,
  columns,
  tolerance = 0,
  observed_element = NULL,
  reference_element = NULL,
  observed_filter = NULL,
  reference_filter = NULL,
  reference_fill = NULL,
  check = "comparison"
)

Arguments

Value

A data frame with one row per key and column: check, the key columns (observed names), row_key, column, reference_column, observed_value, reference_value (text, 17 significant digits for numbers), difference (absolute, numeric pairs), tolerance, reference_filled, matches and status (MATCH, MISMATCH, MISSING_OBSERVED, MISSING_REFERENCE).

See Also

SummarizeComparisons()

Examples

a <- data.frame(id = c("x", "y"), p = c(0.1, 0.2), s = c("ok", "ok"))
b <- data.frame(key = c("y", "x"), pv = c(0.2 + 1e-12, 0.1), s = c("ok", "no"))
CompareTables(a, b, keys = c(id = "key"), columns = c(p = "pv", s = "s"),
              tolerance = 1e-10)

Description

Matches one numeric observation to each caller-supplied composite registry key. The registry defines the entire row universe and its order. No Cartesian product, observed group, eligibility rule or biological absence is inferred. The required absent_value applies only to absent rows, never to observed NA.

Usage

CompleteRegisteredValues(data, registry, keys, value, absent_value)

Arguments

Details

Both tables require unique composite keys. Unknown data keys fail rather than being discarded. Registry metadata is authoritative and carried unchanged; extra data columns are ignored. Inputs are not mutated. Values are normalized to double; no arithmetic or aggregation is performed.

Value

A data frame with registry columns, the selected value (double), observed (logical), status (character), and absent_value (double policy). Status is OBSERVED for known matched values, OBSERVED_MISSING for matched NA, ABSENT_FILLED for absent rows with finite fill, or ABSENT_UNAVAILABLE for absent rows with NA fill. Row count and order equal the registry. Empty registry requires empty data and returns a typed empty result. Provenance distinguishes observed zero, filled zero, observed NA and absent NA.

Examples

d <- data.frame(bin = c("a", "b"), fraction = c(0.5, NA_real_))
expected <- data.frame(bin = c("a", "b", "c"), sample = "one")
CompleteRegisteredValues(d, expected, "bin", "fraction", absent_value = 0)

Description

Lays out panels, page-level texts and legend keys on a page of fixed size in millimetres, with bold panel letters and headings in the manuscript style. The result can be drawn on any device or written with SaveFigure().

Usage

ComposeFigure(
  panels,
  height_mm,
  width_mm = NULL,
  texts = list(),
  style = ManuscriptStyle()
)

Arguments

Value

An object of class phenoscapR_figure; print() draws it on the current device.

Examples

library(ggplot2)
p <- ggplot(data.frame(x = 1:3, y = 1:3), aes(x, y)) + geom_point() +
  ThemeManuscript()
fig <- ComposeFigure(list(FigurePanel(p, c(12, 10, 50, 30), letter = "a",
                                      heading = "Example")), height_mm = 50)

Description

Turns image fields (lists with a channels element of named matrices, as returned by segmantR::sg_read_field()) into RGB images for galleries: every view is an additive mixture of display-scaled channels, clip((value - lo) / (hi - lo), 0, 1) ^ gamma * weight * colour.

Usage

CompositeFields(
  fields,
  views,
  slide = NULL,
  levels = NULL,
  source = "source",
  gamma = 0.8,
  min_span = 1,
  style = ManuscriptStyle()
)

Arguments

Details

A layer is a list with channel (a channel name) or column (a column of the field's row table that holds the channel name), colour (hex or style colour), optional weight (default 1), overlay (paint over the mixture instead of adding) and display levels: lo and hi. lo is the name of a range table ("slide", "levels") or "q0.01" (a quantile of the field's own values); hi is one or several terms, each a table name, a table name with a factor ("slide*0.9") or a quantile ("q0.995"); the largest term is used, and never less than lo + min_span.

Value

A list of class phenoscapR_images with images (list of RGB arrays) and info (data frame: image, field, view and the columns of each field's row).

Examples

set.seed(1)
field <- list(channels = list(dna = matrix(runif(100, 0, 50), 10),
                              cd3 = matrix(runif(100, 0, 20), 10)))
views <- list(merge = list(list(channel = "dna", colour = "#3366FF", lo = "q0", hi = "q0.99"),
                           list(channel = "cd3", colour = "#FF3300", lo = "q0.5", hi = "q1")))
imgs <- CompositeFields(field, views)
dim(imgs$images[[1]])
imgs$info

Description

Stacked bar plot showing the proportion or count of each phenotype within each sample (or other grouping variable). Matches the stacked bar composition plots from the images.

Usage

CompositionPlot(
  object,
  group_by = "sample_id",
  proportion = TRUE,
  colours = NULL
)

Arguments

Value

A ggplot object.

Examples

counts <- matrix(rnorm(100), nrow = 50,
                 dimnames = list(NULL, c("CD3", "CD8")))
coords <- data.frame(x = runif(50), y = runif(50))
meta <- data.frame(cell_id = 1:50,
                   sample_id = rep(c("S1", "S2"), each = 25),
                   phenotype = sample(c("T cell", "B cell", "Mac"), 50, TRUE))
obj <- CreateSpatialObject(counts, coords, meta)
CompositionPlot(obj)

Description

Compares positive and control observations only within strata containing both labels with finite metric values. The caller supplies the policy-selected population, independent group keys, stratum assignments and binary labels. This function does not select a population, construct strata, establish independence, or infer a causal estimand or scientific eligibility policy.

Usage

ContrastGroupedOverlap(
  data,
  registry,
  groups,
  strata,
  id,
  positive,
  value,
  quality = NULL
)

Arguments

Details

Group, stratum and observation keys must be nonblank, nonmissing character vectors without dimensions. Factors and numeric IDs are not coerced. All selected column roles must be distinct, and keys must not collide with output column names. Unknown groups and duplicate registry or observation keys are rejected. Row order does not define identity.

Overlap is determined separately within each group and stratum after filtering for finite metric values. In an overlap stratum, positives receive weight one and controls receive the finite positive count divided by the finite control count. Observations with unavailable values or outside overlap retain NA weights and explicit statuses. They are not discarded from the returned observation and stratum audit tables.

The contrast is the overlap-positive mean minus the weighted overlap-control mean. Both policy-positive and metric-evaluable-positive coverage denominators are reported. Effective control count is the squared sum of control weights divided by their sum of squares, computed after scaling weights to avoid avoidable overflow. Means similarly scale values and weights. Unrepresentable results or scaling/product underflow raise an error rather than silently dropping a nonzero contribution. Exact cancellation to zero is valid. Ordinary floating-point rounding still applies; this is not arbitrary-precision arithmetic.

All optional quality criteria are assessed separately. A failed criterion never suppresses an otherwise finite contrast. A PASS means only that the requested criteria passed, not that the contrast is defined or scientifically eligible; inspect status and the explicit denominators as well. Criteria using an unavailable denominator fail. No count population or threshold is selected implicitly. Policy, evaluable and overlap positive counts are distinct.

Value

List with schema_version ("1.0.0"), summary, strata, observations, and the canonical requested quality list. All tables are sorted by explicit keys; empty registries return typed empty tables. The summary contains policy/evaluable/overlap counts, stratum counts, both positive coverage fractions, positive/control evaluable fractions, positive_mean, control_weighted_mean, contrast, control_weight_sum and control_effective_n. A zero weight total denotes an empty matched control set; missing means and ESS remain NA, never zero-imputed. Summary status is EMPTY_GROUP, NO_EVALUABLE_VALUES, NO_OVERLAP or DEFINED; availability is UNAVAILABLE, PARTIAL or COMPLETE. Quality is NOT_REQUESTED, PASS or FAIL with semicolon-separated failed criterion names. The stratum table retains policy/evaluable counts and overlap status. The observation table retains keys, is_positive, metric_value, metric_evaluable, overlap, weight, and OVERLAP, NONFINITE_VALUE or NO_OVERLAP_STRATUM status. Extra input columns are not returned.

Examples

d <- data.frame(sample = "one", block = c("a", "a", "a", "b"),
  cell = letters[1:4], positive = c(TRUE, FALSE, FALSE, TRUE),
  score = c(4, 1, 3, NA))
registry <- data.frame(sample = c("one", "empty"))
result <- ContrastGroupedOverlap(d, registry, groups = "sample", strata = "block",
  id = "cell", positive = "positive", value = "score")
result$summary

Description

Computes descriptive Cliff's delta as the number of A-greater-than-B pairs minus A-less-than-B pairs, divided by all available cross-arm pairs. Ties contribute zero. No inferential p value or independence claim is supplied. Pair counts use sorted value frequencies without a cross-product matrix or value subtraction. Every registered group is retained, including empty arms.

Usage

ContrastGroupedRanks(
  data,
  registry,
  groups,
  id,
  arm,
  value,
  missing = c("propagate", "available")
)

Arguments

Details

Group keys and observation IDs must be dimensionless, nonmissing, nonblank character vectors. Factors and numeric IDs are not coerced. The reserved ASCII 28 separator (intToUtf8(28)) is rejected in keys. Column selections must be distinct, and group columns must not collide with output names. Registry keys must be unique. Every observation must belong to a registered group and have a unique ID within that complete group, including across arms. The same ID may occur in different groups. Arm values must be exactly "A" or "B"; no labels or population policy are inferred.

Delta is positive when A tends to exceed B and negative when B tends to exceed A. It equals the proportion of available cross-arm pairs with A greater than B minus the proportion with A less than B. Equal values, including signed zeros, are ties. Comparisons use represented numeric values without a tolerance. No value subtraction, cross-pair matrix, rank test or resampling is performed. Pair counts above 2^53 - 1 are rejected before multiplication rather than rounded. Sorting distinct values and counting frequencies avoids allocating a Cartesian product, but input and distinct values must still fit in memory.

Available-case analysis filters missing values separately within each arm; it is not paired-observation deletion. Propagation suppresses delta when either supplied arm contains missing values, while still reporting the available pair counts. If an available arm is empty, status is UNAVAILABLE under either policy. A declared group without observations is retained. Group membership and missingness policies do not establish independence or exchangeability. This function computes a descriptive effect only.

Value

Data frame sorted by group keys, preserving original key values. Supplied, available and unavailable counts are returned for each arm, together with available cross-pair, greater, less and tied counts, delta, missingness policy and status. Empty available arms yield UNAVAILABLE; otherwise propagation with missing values yields MISSING_VALUES, followed by PARTIAL or COMPLETE. Pair counts always describe available values even when delta is suppressed. Counts exceeding exact binary64 integer capacity are rejected before multiplication. An empty registry returns typed output.

Examples

d <- data.frame(
  g = "one", id = letters[1:4],
  arm = c("A", "A", "B", "B"), value = c(2, 4, 1, 2)
)
ContrastGroupedRanks(d, data.frame(g = "one"), "g", "id", "arm", "value")

Description

Runs ExactPatientTests() for every row of a hypothesis registry (endpoint, contrast, family) on a wide patient table (one row per patient, one column per endpoint). Contrast arms are declared as sets of patient groups. Two missingness policies are offered:

Usage

ContrastPatientEndpoints(
  data,
  registry,
  contrasts,
  id,
  group,
  endpoint = "endpoint",
  contrast = "contrast",
  family = "family",
  missingness = c("complete_case", "require_complete"),
  hypothesis_prefix = "h",
  max_allocations = 1000000L
)

Arguments

Details

• "complete_case": each hypothesis uses only patients with a finite value; a hypothesis whose arm has no such patient is unavailable. This reproduces tables that silently drop missing patients.

• "require_complete": every patient of both arms must have a finite value, otherwise the hypothesis is unavailable (no patient is dropped).

Each hypothesis receives its own design, so a registry may repeat an endpoint-contrast pair in different families. The effect is the mean of arm A minus the mean of arm B.

Value

A data frame with the registry columns, hypothesis_id, family_id (family :: contrast), expected and evaluable arm sizes, mean_difference, p_value, allocations, status and missingness, in registry order. Pass it to AdjustPatientFamilies().

Examples

d <- data.frame(patient = paste0("p", 1:6), arm = rep(c("x", "y"), each = 3),
                e1 = c(1, 2, 3, 6, 7, NA), e2 = c(5, 4, 6, 1, 2, 3))
reg <- data.frame(endpoint = c("e1", "e2"), contrast = "x vs y", family = "f")
ctr <- list("x vs y" = list(A = "x", B = "y"))
ContrastPatientEndpoints(d, reg, ctr, "patient", "arm")
ContrastPatientEndpoints(d, reg, ctr, "patient", "arm",
                         missingness = "require_complete")

Description

Get Spatial Coordinates

Usage

Coords(object)

## S4 method for signature 'SpatialCellData'
Coords(object)

Arguments

Value

Data frame with columns x and y.

Examples

data(phenoscapR_example)
head(Coords(phenoscapR_example))

Description

Computes descriptive Spearman correlations over paired observations, using average ranks for ties. Each observation must occur once per complete group key. Include the independent sampling unit in groups; no independence, eligibility, causal interpretation or inferential p value is established. Missingness is paired: a row is available only when both values are known. The default suppresses correlation when any pair is unavailable. Explicit available-case analysis retains the supplied and unavailable pair counts.

Usage

CorrelateGroupedRanks(
  data,
  groups,
  id,
  x,
  y,
  min_pairs = 3L,
  missing = c("propagate", "available")
)

Arguments

Value

Data frame sorted by group keys with n_supplied, n_available, n_unavailable, available-pair n_unique_x and n_unique_y, rho, status, and missing_policy. Status precedence is UNAVAILABLE, INSUFFICIENT, MISSING_PAIRS (propagation), CONSTANT_BOTH, CONSTANT_X, CONSTANT_Y, then COMPLETE or PARTIAL. Suppressed correlations are NA. Empty input returns a typed empty table; absent groups are not invented.

Examples

d <- data.frame(sample = "one", cell = letters[1:4],
                a = c(1, 1, 3, 4), b = c(4, 3, 2, 1))
CorrelateGroupedRanks(d, "sample", "cell", "a", "b")

Description

Counts an explicitly supplied edge set using stable node IDs within complete group and frame keys. Isolated nodes and nodes in neither set remain in the supplied graph totals. No graph is constructed, no distance cap is applied, and no scientific population, radius or eligibility policy is inferred.

Usage

CountDisjointEdges(
  nodes,
  edges,
  registry,
  groups,
  frame,
  id,
  from,
  to,
  source,
  target
)

Arguments

Details

Keys and IDs must be dimensionless, nonmissing, nonblank character vectors. IDs may repeat across different groups or frames, but must be unique within the complete group/frame key. Factors and numeric IDs are not coerced. Duplicate registry keys, unknown endpoints, self edges, and duplicate undirected pairs (including reversed duplicates) raise errors. Each edge declares one shared frame, so a cross-frame relationship cannot be represented; an endpoint absent from the declared frame raises an error. The function cannot detect incorrectly declared frames or establish physical coordinate validity.

Each source-target edge contributes once regardless of orientation. Conditional neighbour means divide cross-edge count by the number of distinct interacting source or target nodes. Contact fractions divide interacting nodes by the corresponding complete source or target population. Thus isolated nodes enter contact-fraction denominators but not conditional-neighbour denominators.

A population with no contacts has contact fraction zero (DEFINED) and conditional mean NA (NO_INTERACTING_SOURCE or NO_INTERACTING_TARGET). An absent population has contact fraction NA (NO_SOURCE or NO_TARGET). Missing membership never becomes an observed zero. Empty registries return the same typed zero-row schema.

Provenance is copied from the registry, not authenticated. In particular, frozen_import does not mean geometry was regenerated or its hashes verified. The result declares geometry_recomputed = FALSE and geometry_authentication = "CALLER_DECLARED_NOT_VERIFIED". This API does not invoke or certify any triangulation, distance, review or geometry backend.

Value

Data frame sorted by group/frame keys. Schema version "1.0.0" has integer-valued numeric counts n_nodes, n_edges, n_source, n_target, n_cross_edges, n_interacting_source, and n_interacting_target; source_neighbor_mean, target_neighbor_mean, source_contact_fraction, and target_contact_fraction; and their corresponding ⁠_status⁠ columns. Supplied graph totals include all nodes and edges, even those contributing no source-target contact. Geometry provenance columns and schema_version are retained explicitly. Extra input columns are not returned.

Examples

nodes <- data.frame(sample = rep("one", 3), frame = rep("image", 3),
  cell = c("a", "b", "isolated"), is_source = c(TRUE, FALSE, TRUE),
  is_target = c(FALSE, TRUE, FALSE))
edges <- data.frame(sample = "one", frame = "image", from = "b", to = "a")
registry <- data.frame(sample = c("one", "empty"), frame = "image",
  geometry_source = "supplied_edges", geometry_reference = "example-v1")
CountDisjointEdges(nodes, edges, registry, groups = "sample", frame = "frame",
  id = "cell", from = "from", to = "to", source = "is_source", target = "is_target")

Description

Counts reference neighbours and overlapping reference sets for each query ID within an explicitly declared coordinate frame. Query batching always searches the complete reference population of that frame. No population, coordinate transformation, graph, tissue area or scientific threshold is inferred.

Usage

CountRadiusSets(
  nodes,
  frames,
  groups,
  frame,
  id,
  x,
  y,
  query,
  reference,
  sets,
  unit_column,
  radius_unit,
  radii,
  search_radius,
  chunk_size = 1000L
)

Arguments

Details

Keys and IDs must be dimensionless, nonmissing, nonblank character vectors. IDs must be unique within the complete group/frame key, but may repeat across independent frames. Factors and numeric IDs are not coerced. Selected roles within each input table must be distinct. Unknown frames, duplicate keys, missing memberships and malformed inputs raise errors. Extra node columns are ignored; a tile column does not partition a frame unless selected as a key.

Searches use dbscan::frNN() with explicit query mode, search = "kdtree", approx = 0 and sort = FALSE, without a fallback. Returned distances are filtered inclusively using distance <= radius. Self exclusion compares IDs within the complete frame key. Distinct coincident IDs remain neighbours.

Exact search mode does not imply arbitrary-precision real-number geometry. Binary64 boundary decisions can depend on search_radius: the distance from ⁠(0, 0)⁠ to ⁠(3 + 2 * .Machine$double.eps, 4)⁠ is excluded by a native search at 5, but a search at 6 returns a distance rounded to 5, which passes the output-radius filter at 5. Keep the search envelope fixed when requesting different subsets of radii or comparing runs. No padding, recentring, coordinate rounding or squared-distance replacement is applied.

Squared output and search radii must be finite and at least .Machine$double.xmin. Absolute coordinates must not exceed sqrt(.Machine$double.xmax) / 4; frame spans must support finite squared arithmetic. Unsupported extreme inputs and integer indexing/output sizes raise errors. These conservative guards do not remove ordinary rounding. Chunking bounds each native query batch, not dense-neighbourhood memory within a batch or total output size. This function does not authenticate input coordinates or historical geometry and does not infer fractions or weights.

Value

A list with schema_version = "1.0.0" and:

• frame_summary: one row per declared frame, coordinate units, n_nodes, n_queries, n_references, and status (NO_QUERIES, EMPTY_REFERENCE, or DEFINED).

• query_counts: every query by requested radius, including zero neighbours, with n_reference_neighbors and status (EMPTY_REFERENCE or DEFINED). A nonempty reference universe containing only the query itself has status DEFINED and zero eligible neighbours.

• set_counts: every query by radius by set, with integer-valued double count and matching status. Overlapping sets need not partition neighbours.

• backend: installed version, search settings and radius/unit, DESCRIPTION, R-wrapper and native-library SHA-256 fingerprints. These identify the current runtime and do not authenticate a historical backend.

Keys and IDs are retained. Tables are sorted by keys, IDs, radii and set names as applicable. Empty inputs return typed empty tables; inputs are not modified.

Examples

nodes <- data.frame(
  sample = "sample-1", frame = "image-1", id = c("a", "b", "c"),
  x = c(0, 0, 3), y = c(0, 0, 4),
  query = c(TRUE, FALSE, FALSE), reference = TRUE,
  set_a = c(FALSE, TRUE, TRUE), set_b = c(FALSE, TRUE, FALSE)
)
frames <- data.frame(sample = "sample-1", frame = "image-1", unit = "um")
CountRadiusSets(nodes, frames, "sample", "frame", "id", "x", "y",
  "query", "reference", c("set_a", "set_b"), "unit", "um",
  radii = c(1, 5), search_radius = 5
)

Description

Constructs a SpatialCellData-class object from a counts matrix, coordinate data frame, and optional metadata.

Usage

CreateSpatialObject(
  counts,
  coords,
  meta_data = NULL,
  sample_id = "sample1",
  project = "SpatialProject"
)

Arguments

Value

A SpatialCellData-class object.

Examples

counts <- matrix(rnorm(50), nrow = 10,
                 dimnames = list(NULL, c("CD3", "CD8", "CD20", "DAPI", "PanCK")))
coords <- data.frame(x = runif(10, 0, 500), y = runif(10, 0, 500))
obj <- CreateSpatialObject(counts, coords, sample_id = "mysample")
obj

Description

Computes the nearest neighbour distance from each cell of one phenotype to cells of another phenotype. With from equal to to, the distance is to the nearest other cell of that phenotype.

Usage

CrossNNDistance(object, from, to, by_sample = FALSE)

Arguments

Value

A numeric vector of distances (one per cell of the from phenotype).

Examples

counts <- matrix(rnorm(60), nrow = 30,
                 dimnames = list(NULL, c("CD3", "CD8")))
coords <- data.frame(x = runif(30, 0, 100), y = runif(30, 0, 100))
meta <- data.frame(cell_id = 1:30, sample_id = "s1",
  phenotype = rep(c("A", "B", "C"), each = 10))
obj <- CreateSpatialObject(counts, coords, meta)
CrossNNDistance(obj, from = "A", to = "B")

Description

Creates a gradient palette function from 2 or 3 anchor colours. The returned function takes an integer n and returns n colours.

Usage

CustomGradient(colours)

Arguments

Value

A function that takes integer n and returns n hex colour codes.

Examples

pal <- CustomGradient(c("navy", "white", "firebrick"))
cols <- pal(100)
image(matrix(1:100, ncol = 1), col = cols)

Description

Computes a Delaunay triangulation of cell positions and stores edges in the spatial slot. Each sample_id is triangulated separately; it must identify one independent spatial coordinate frame. Every sample must contain at least three cells. Edge endpoints refer to cell rows in the complete object, never rows local to a sample. Of cells with identical coordinates, only the first is a vertex; the others get no edges.

Usage

DelaunayNetwork(object, max_edge = NULL)

Arguments

Value

An SpatialCellData-class with delaunay_edges stored in the spatial slot.

Examples

counts <- matrix(rnorm(40), nrow = 20,
                 dimnames = list(NULL, c("CD3", "CD8")))
coords <- data.frame(x = runif(20, 0, 100), y = runif(20, 0, 100))
obj <- CreateSpatialObject(counts, coords)
obj <- DelaunayNetwork(obj, max_edge = 30)

Description

Bins cells into square windows of a regular grid with origin 0 and returns the centre of the window holding the most cells (ties: the window with the smallest x index, then y index).

Usage

DensestGridWindow(cells, size, filter = list(), x = "x", y = "y")

Arguments

Value

A one-row data frame with x, y (window centre), x0, y0 (window corner) and n.

Examples

d <- data.frame(x = c(1, 2, 15, 16, 17), y = c(1, 2, 5, 6, 7))
DensestGridWindow(d, 10)

Description

For each group (for example each patient), counts the points in a bins x bins histogram over the display limits, smooths the counts with a Gaussian kernel of sigma bins (mirror boundaries, kernel truncated at truncate sigma), and finds the density level whose superlevel region holds the fraction level of the smoothed mass: the smallest bin value that is still needed when bins are added from the highest down until their sum reaches level times the total. The region above that level is returned as filled bands and outline paths on the bin centres.

Usage

DensityLevelContour(
  data,
  x = "x",
  y = "y",
  group = "group",
  limits,
  filter = NULL,
  bins = 90,
  sigma = 2,
  level = 0.9,
  truncate = 4,
  groups = NULL,
  carry = NULL,
  slot_within = NULL,
  label_from = NULL,
  label_sub = NULL
)

Arguments

Value

A data frame with the group column (named as in data), slot, label, carried columns, kind ("band", "line"), piece, x, y, level (the density level) and n (points of the group).

Examples

set.seed(3)
d <- data.frame(x = rnorm(400), y = rnorm(400), g = rep(c("a", "b"), 200))
head(DensityLevelContour(d, group = "g", limits = c(-4, 4, -4, 4), bins = 30))

Description

Scatter plot with colour scaled by local cell density. Requires CellDensity to have been run.

Usage

DensityPlot(object, pt_size = 1, title = NULL, palette = NULL)

Arguments

Value

A ggplot object.

Examples

counts <- matrix(rnorm(100), nrow = 50,
                 dimnames = list(NULL, c("CD3", "CD8")))
coords <- data.frame(x = runif(50, 0, 100), y = runif(50, 0, 100))
obj <- CreateSpatialObject(counts, coords)
obj <- CellDensity(obj, radius = 20)
DensityPlot(obj)

Description

Tests whether the proportion of each phenotype differs between experimental conditions. Proportions are computed per sample (the unit of replication), then compared across the condition groups, so the test respects the sample-level design rather than treating individual cells as independent.

Usage

DifferentialAbundance(
  object,
  condition,
  phenotype_col = "phenotype",
  test = c("wilcox", "t", "kruskal")
)

Arguments

Value

A classed data frame (phenoscapR_diffabund) with one row per phenotype: per-condition mean proportions, the test statistic, p_value, and BH-adjusted p_adj.

Examples

data(phenoscapR_example)
obj <- phenoscapR_example
obj@meta_data$phenotype <- obj@meta_data$phenotype_true
# Toy condition: label the two sections as different arms.
obj@meta_data$arm <- ifelse(obj$sample_id == "tonsil_A", "ctrl", "treat")
DifferentialAbundance(obj, condition = "arm")

Description

Get Dimensions of a SpatialCellData Object

Usage

## S4 method for signature 'SpatialCellData'
dim(x)

Arguments

Value

Integer vector: number of cells, number of markers.

Description

Dot plot where dot size represents the percentage of cells expressing a marker (above a threshold) and colour represents the mean expression. Analogous to Seurat's DotPlot.

Usage

DotPlot(
  object,
  features,
  group_by = "phenotype",
  slot = "data",
  threshold = 0,
  palette = NULL
)

Arguments

Value

A ggplot object.

Examples

counts <- matrix(c(rnorm(60, 5), rnorm(60, 0)), ncol = 4,
                 dimnames = list(NULL, c("CD3", "CD8", "CD20", "PanCK")))
coords <- data.frame(x = runif(30), y = runif(30))
meta <- data.frame(cell_id = 1:30, sample_id = "s1",
                   phenotype = rep(c("T cell", "B cell", "Other"), each = 10))
obj <- CreateSpatialObject(counts, coords, meta)
DotPlot(obj, features = c("CD3", "CD8", "CD20", "PanCK"))

Description

Stacks the points of several layers in drawing order: each layer selects rows by column values, takes its key either as a fixed name or from a column, and may be put in random order (for example so that no cell type is systematically drawn on top). The random order is a permutation from R's default generator after set.seed(seed); the caller's random state is left unchanged.

Usage

EmbeddingLayers(data, x = "x", y = "y", layers, carry = NULL, seed = NULL)

Arguments

Value

A data frame with x, y, key, layer and the carried columns, in drawing order.

Examples

d <- data.frame(u = 1:6, v = 6:1, type = c("a", "b", "a", "c", "b", "a"), kept = TRUE)
EmbeddingLayers(d, "u", "v", layers = list(
  list(filter = list(kept = TRUE), key = "background"),
  list(filter = list(type = "a"), key_from = "type", shuffle = TRUE)), seed = 1)

Description

Limits enclosing the central part of the points plus a margin: the probs quantiles of each coordinate (type 7, linear interpolation) widened by pad times their span on both sides.

Usage

EmbeddingLimits(
  data,
  x = "x",
  y = "y",
  filter = NULL,
  probs = c(5e-04, 0.9995),
  pad = 0.04
)

Arguments

Value

A one-row data frame with xmin, xmax, ymin, ymax.

Examples

EmbeddingLimits(data.frame(x = 1:100, y = (1:100)^2))

Description

Scatter plot of cells in an embedding (PCA, UMAP, t-SNE, or SONG), coloured by a metadata column. Analogous to Seurat's DimPlot.

Usage

EmbeddingPlot(
  object,
  reduction = "umap",
  colour_by = "phenotype",
  colours = NULL,
  pt_size = 1,
  title = NULL,
  dark_theme = FALSE
)

DimPlot(
  object,
  reduction = "umap",
  colour_by = "phenotype",
  colours = NULL,
  pt_size = 1,
  title = NULL,
  dark_theme = FALSE
)

Arguments

Value

A ggplot object.

Examples

counts <- matrix(rnorm(500), nrow = 50,
                 dimnames = list(NULL, paste0("M", 1:10)))
coords <- data.frame(x = runif(50), y = runif(50))
obj <- CreateSpatialObject(counts, coords)
obj <- RunPCA(obj, n_pcs = 5)
obj <- PhenotypeCells(obj, thresholds = list(M1 = 0))
EmbeddingPlot(obj, reduction = "pca")

Description

Get a Dimensionality-Reduction Embedding

Usage

Embeddings(object, reduction = "pca")

## S4 method for signature 'SpatialCellData'
Embeddings(object, reduction = "pca")

Arguments

Value

A numeric matrix (cells x dimensions).

Examples

data(phenoscapR_example)
Embeddings(RunPCA(phenoscapR_example, n_pcs = 5), "pca")[1:3, ]

Description

For each declared group of rows, tests whether paired differences are symmetric about zero with the exact Wilcoxon signed-rank test over all $2^n$ sign assignments, together with the exact two-sided sign test and, optionally, a Clopper-Pearson interval for the fraction of subjects whose difference lies in an expected direction. Leave-one-subject-out results can be requested instead of the full tests.

Usage

ExactPairedTests(
  data,
  value,
  groups = NULL,
  id = NULL,
  expected = NULL,
  family = NULL,
  omit = c("none", "each"),
  conf_level = 0.95,
  max_n = 500L
)

Arguments

Details

Non-finite differences are unavailable; zero differences are excluded from the signed-rank and sign tests (they still count as available subjects and as not being in the expected direction). Ranks of absolute differences use midranks for ties. The two-sided p value is the fraction of sign assignments whose absolute signed-rank sum is at least the observed one. It is computed by dynamic programming over twice the midranks (integers), so it equals full enumeration exactly for up to 52 nonzero differences without enumerating them.

Value

A data frame with the group columns, n_available, n_nonzero, n_zero, positive, negative, median_difference and mean_difference (of the nonzero differences), signed_rank_sum, p_value (signed-rank), sign_p_value, status, optionally expected, expected_direction, direction_ci_low, direction_ci_high, conf_level, and hypothesis_id (plus family_id).

See Also

PairedDifferences(), AdjustPatientFamilies()

Examples

d <- data.frame(test = rep(c("a", "b"), each = 6), subject = rep(1:6, 2),
                difference = c(-3, -1, -2, -5, 1, -4, 2, -1, 3, 0, 1, 2))
ExactPairedTests(d, "difference", groups = "test", id = "subject",
                 expected = "less")
ExactPairedTests(d, "difference", groups = "test", id = "subject",
                 omit = "each")

Description

Enumerates every allocation with the declared group sizes. The statistic is the mean in A minus the mean in B; the two-sided p value is the fraction with absolute statistic at least the observed absolute statistic. Observed and allocated statistics are computed alike from values centred on their mean. Two statistics count as tied when they differ by no more than the rounding of this arithmetic (relative to the largest centred value) plus the rounding of the stored values (half a unit in the last place of the largest absolute value), so p values do not depend on the scale of the values. A shift leaves them unchanged while the rounding of the shifted values stays below the spacing of distinct statistics; for example, whole numbers from 0 to 20 for up to 12 patients keep their exact p values up to a shift of 1e13, while larger shifts can merge distinct statistics into ties. If an intermediate tolerance bound overflows, the same bound is evaluated with machine precision multiplied first; finite ordinary bounds are unchanged. This requires exchangeability under the null. Observational confounding, paired designs and stratified randomisation are not addressed by this test. Repeated images must be aggregated to one endpoint per patient beforehand.

Usage

ExactPatientTests(
  endpoints,
  design,
  hypotheses,
  missingness = "require_complete",
  max_allocations = 1000000L
)

Arguments

Value

A data frame with the registry, expected/evaluable group sizes, mean_difference, p_value, allocation count, probability grid step, and status. Grid step is a resolution bound, not a guaranteed attainable minimum two-sided p value. Unavailable effects and p values remain NA.

Examples

endpoints <- data.frame(endpoint_id = "e", patient_id = letters[1:4],
                        value = 1:4, eligible = TRUE)
design <- data.frame(contrast_id = "c", patient_id = letters[1:4],
                     group = c("A", "A", "B", "B"))
hypotheses <- data.frame(hypothesis_id = "h", endpoint_id = "e",
                         contrast_id = "c", family_id = "f")
ExactPatientTests(endpoints, design, hypotheses)

Description

For an exact permutation test of two groups of sizes n_a and n_b (all allocations of the pooled values), the observed allocation always reaches its own statistic; with equal group sizes its mirror allocation reaches the same absolute difference. The smallest attainable two-sided P is therefore at least 2 / choose(n_a + n_b, n_a) for equal and 1 / choose(n_a + n_b, n_a) for unequal sizes.

Usage

ExactPermutationBound(n_a, n_b)

Arguments

Value

Numeric lower bound.

Examples

ExactPermutationBound(6, 6)
ExactPermutationBound(4, 2)

Description

Clusters cells based on marker expression profiles.

Usage

ExpressionClusters(
  object,
  k,
  method = c("kmeans", "hierarchical", "gmm"),
  slot = "data",
  markers = NULL
)

Arguments

Value

An SpatialCellData-class with an expr_cluster column in meta_data.

Examples

counts <- matrix(c(rnorm(50, 10), rnorm(50, 0)), nrow = 50,
                 dimnames = list(NULL, c("CD3", "CD8")))
coords <- data.frame(x = runif(50), y = runif(50))
obj <- CreateSpatialObject(counts, coords)
obj <- ExpressionClusters(obj, k = 2)
table(Meta(obj)$expr_cluster)

Description

Plots marker expression intensity on spatial coordinates. Each marker gets its own panel. Similar to Seurat's FeaturePlot but in tissue space.

Usage

FeaturePlot(
  object,
  features,
  slot = "data",
  pt_size = 0.3,
  ncol = NULL,
  palette = NULL,
  dark_theme = FALSE
)

Arguments

Value

A ggplot object.

Examples

counts <- matrix(rnorm(150), nrow = 50,
                 dimnames = list(NULL, c("CD3", "CD8", "PanCK")))
coords <- data.frame(x = runif(50, 0, 500), y = runif(50, 0, 500))
obj <- CreateSpatialObject(counts, coords)
FeaturePlot(obj, features = c("CD3", "CD8"))

Description

Selects cells with given labels inside a square of half-width half around a centre, ordered by a column (for example the distance to the nearest tumour cell), and keeps the first n; used to place arrows on a fluorescence field.

Usage

FieldCellsRanked(
  cells,
  centre,
  half,
  labels,
  order_by = NULL,
  n = Inf,
  x = "x",
  y = "y",
  label = "label"
)

Arguments

Value

The selected rows of cells.

Examples

d <- data.frame(x = c(1, 2, 3, 9), y = c(1, 1, 2, 9), label = c("a", "a", "b", "a"),
                dist = c(4, 2, 1, 3))
FieldCellsRanked(d, centre = c(2, 2), half = 3, labels = "a", order_by = "dist")

Description

Resolves a field centre as in CellMapData() (given point, cell, grid snapping, offset) and returns it as a one-row data frame, the form taken by image readers, maps and boxes.

Usage

FieldCentre(
  cells,
  centre = NULL,
  centre_cell = NULL,
  id = "row",
  grid = NULL,
  offset = NULL,
  size = NULL,
  x = "x",
  y = "y"
)

Arguments

Value

A data frame with x, y and, when given, size.

Examples

d <- data.frame(row = 0:2, x = c(1, 5, 9), y = c(2, 6, 10), label = "a")
FieldCentre(d, centre_cell = 1, offset = c(10, 0), size = 20)

Description

Names usable in the grammar field of a figure specification and the exported function each one calls.

Usage

FigureGrammars()

Value

Named character vector: grammar name to function name.

See Also

RenderFigure()

Examples

head(FigureGrammars())

Description

Place a Grob on a Figure Page

Usage

FigureGrob(grob, at, hjust = 0, vjust = 1)

Arguments

Value

A list of class phenoscapR_grob.

Examples

key <- FigureGrob(grid::textGrob("Legend text", just = c(0, 1)), at = c(5, 5))
fig <- ComposeFigure(list(FigurePanel(NULL, c(5, 10, 40, 20), letter = "a")),
                     height_mm = 35, width_mm = 60, texts = list(key))
grid::grid.newpage(); print(fig)