Package {ISPAT3D}

Type: Package
Title: Spatial Conditional Association Networks in Registered Tumor Volumes
Version: 0.3.1
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>.
License: MIT + file LICENSE
Encoding: UTF-8
Imports: gpboost, graphics, stats, utils
Suggests: data.table, knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder: knitr
URL: https://github.com/sagnikbhadury/ISPAT-3D
BugReports: https://github.com/sagnikbhadury/ISPAT-3D/issues
Config/testthat/edition: 3
Config/roxygen2/version: 8.0.0
NeedsCompilation: no
Packaged: 2026-09-16 15:43:50 UTC; bhadury
Author: Sagnik Bhadury [aut, cre]
Maintainer: Sagnik Bhadury <bhadury@umich.edu>
Repository: CRAN
Date/Publication: 2026-09-27 16:40:37 UTC

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.