Package 'ISPAT3D'

Title: Spatial Conditional Association Networks in Registered Tumor Volumes
Description: Fits tumor-zone-specific conditional cell-density networks from registered three-dimensional multiplex imaging. An anisotropic Matern-3/2 Gaussian process is estimated per variable and zone using a Vecchia likelihood on spatially balanced anchors; predictions at all selected cells yield residual covariance sufficient statistics. Gaussian maximum likelihood then fits a shared-plus-zone factor covariance model. A matched section-wise planar fit uses the same selected cells and covariance estimator. This extends the spatially informed cell-density analysis of Bhadury et al. (2026) <doi:10.1038/s41598-026-35341-8>.
Authors: Sagnik Bhadury [aut, cre]
Maintainer: Sagnik Bhadury <[email protected]>
License: MIT + file LICENSE
Version: 0.3.1
Built: 2026-09-27 18:39:10 UTC
Source: https://github.com/cran/ISPAT3D

Help Index

Extract signed conditional-association edges

Description

Uses partial correlations from a full fitted zone covariance. A low-rank shared factor covariance alone is not invertible and is not a network input.

Usage

ispat3d_edge_table(x, zone = NULL, threshold = 0)

Arguments

x

An ISPAT3D fit returned by ispat3d_fit() or a partial-correlation matrix.
zone

Zone name when x is a fit.
threshold

Minimum absolute partial correlation to retain.

Value

A data frame with source, target, effect, sign, and magnitude, sorted by decreasing absolute effect.

Simulate a small registered cell map with section-wise KDE inputs

Description

Generates a didactic cell map with three annotated cell types, section-wise Gaussian kernel-density estimates evaluated at every cell, and two relative tumor-density zones per section. It is designed for package examples and checks, not for biological simulation studies.

Usage

ispat3d_example_image(
  n_per_section = 24L,
  n_sections = 3L,
  bandwidth = 0.12,
  seed = 2026L
)

Arguments

n_per_section

Cells per section; an even multiple of six, at least 24.
n_sections

Number of serial sections, at least two.
bandwidth

Gaussian KDE bandwidth in the simulated coordinate units.
seed

Reproducible simulation seed.

Value

A list containing coordinates, sections, source cell types, KDE values, transformed model matrix Y, zones, and tumor-density score.

Fit current ISPAT-3D on selected cells

Description

Fits a Matérn-3/2 anisotropic GP per variable and zone using a 15-neighbor Vecchia likelihood on spatially balanced anchors; predicts at all selected cells; then fits shared-plus-zone covariance from complete residual covariance summaries by Gaussian maximum likelihood.

Usage

ispat3d_fit(
  Y,
  coords,
  zones,
  sections = rep(1L, nrow(Y)),
  rank = 5L,
  anchor_fraction = 0.1,
  anchor_min = 300L,
  anchor_max = 5000L,
  neighbors = 15L,
  gp_maxit = 30L,
  factor_maxit = 350L,
  seed = 2026L,
  threads = 2L,
  return_residuals = FALSE
)

Arguments

Y

Numeric cells-by-variables matrix, usually log1p(1e9 * KDE).
coords

Numeric cells-by-3 matrix in registered x,y,z coordinates.
zones

Zone label for each row.
sections

Section identifier for balanced anchor selection.
rank

Shared and zone-specific factor rank (default 5).
anchor_fraction

Fraction of cells selected as GP anchors.
anchor_min, anchor_max

Minimum and maximum number of anchors per fit.
neighbors

Number of Vecchia neighbors.
gp_maxit

Maximum GP likelihood iterations.
factor_maxit

Maximum covariance likelihood iterations.
seed

Random seed for anchor selection and GP fits.
threads

GPBoost threads per GP fit.
return_residuals

Whether to return full adjusted residual matrices.

Value

List containing shared covariance, full zone covariances, zone partial correlations, diagnostics, and optionally residuals.

Fit the matched section-wise ISPAT-2D comparator

Description

Uses the same selected rows and covariance estimator as ispat3d_fit(), but fits independent planar GPs within each zone-section group. Groups with fewer than 10 cells are mean-centered; failed planar GP fits are recorded and mean-centered. This changes both spatial dimension and section pooling.

Usage

ispat3d_fit_2d(
  Y,
  coords,
  zones,
  sections,
  rank = 5L,
  anchor_fraction = 0.1,
  anchor_min = 300L,
  anchor_max = 5000L,
  neighbors = 15L,
  gp_maxit = 30L,
  factor_maxit = 350L,
  seed = 2026L,
  threads = 2L,
  return_residuals = FALSE
)

Arguments

Y

Numeric cells-by-variables matrix, usually log1p(1e9 * KDE).
coords

Numeric cells-by-3 matrix in registered x,y,z coordinates.
zones

Zone label for each row.
sections

Required section identifier for every selected cell.
rank

Shared and zone-specific factor rank (default 5).
anchor_fraction

Fraction of cells selected as GP anchors.
anchor_min, anchor_max

Minimum and maximum number of anchors per fit.
neighbors

Number of Vecchia neighbors.
gp_maxit

Maximum GP likelihood iterations.
factor_maxit

Maximum covariance likelihood iterations.
seed

Random seed for anchor selection and GP fits.
threads

GPBoost threads per GP fit.
return_residuals

Whether to return full adjusted residual matrices.

Value

Same structure as ispat3d_fit().

Fit shared and zone-specific factor covariance from sufficient statistics

Description

Fits Sigma_q = Phi Phi' + Lambda_q Lambda_q' + diag(psi_q) by a weighted Gaussian covariance likelihood. This is the current estimator used after Vecchia GP adjustment, not a variational factor posterior.

Usage

ispat3d_fit_covariance(covariances, counts, rank = 5L, maxit = 350L)

Arguments

covariances

Named list of complete sample covariance matrices.
counts

Number of adjusted cells in each zone, in list order.
rank

Shared and zone-specific loading rank (default 5).
maxit

Maximum L-BFGS-B iterations.

Value

Shared covariance, full zone covariances, partial correlations, loadings, uniquenesses, and optimization diagnostics.

Convert a full covariance matrix to partial correlations

Description

Convert a full covariance matrix to partial correlations

Usage

ispat3d_partial_correlation(covariance, ridge = 1e-06)

Arguments

covariance

Symmetric positive-definite covariance matrix.
ridge

Small numerical diagonal ridge (default 1e-6).

Value

A signed partial-correlation matrix.

Plot a circular partial-correlation network using base graphics

Description

The fitted zone covariance is transformed to partial correlations using the full shared, zone-specific, and uniqueness terms. Red and blue edges show positive and negative conditional density associations.

Usage

ispat3d_plot_network(
  x,
  zone = NULL,
  threshold = 0.05,
  main = zone,
  positive = "#B2182B",
  negative = "#2166AC",
  vertex_cex = 1.1,
  label_cex = 0.75,
  edge_scale = 4
)

Arguments

x

An ISPAT3D fit or partial-correlation matrix.
zone

Zone name when x is a fit.
threshold

Minimum absolute partial correlation to display.
main

Plot title.
positive, negative

Edge colors for positive and negative associations.
vertex_cex

Node size multiplier.
label_cex

Label size multiplier.
edge_scale

Controls edge widths.

Value

Invisibly returns the displayed edge table.

Facet all fitted zone networks in one base-R figure

Description

Facet all fitted zone networks in one base-R figure

Usage

ispat3d_plot_zones(fit, zones = names(fit$full), columns = 2L, ...)

Arguments

fit

An ISPAT3D fit from ispat3d_fit() or ispat3d_fit_2d().
zones

Zone names to plot, in order.
columns

Number of panel columns.
...

Further arguments passed to ispat3d_plot_network().

Value

Invisibly returns a named list of displayed edge tables.

Select spatially balanced cells by zone and section

Description

Select spatially balanced cells by zone and section

Usage

ispat3d_sample(
  coords,
  zones,
  sections,
  budget,
  budget_kind = c("per_zone", "total"),
  seed = 2026L
)

Arguments

coords

N-by-3 registered coordinate matrix.
zones

Zone label per row.
sections

Section identifier per row.
budget

Number per zone when budget_kind="per_zone"; total otherwise.
budget_kind

One of "per_zone" or "total".
seed

Sampling seed.

Value

Named list of source row indices for each zone.