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