Package {bioIOT}

Collapse a probe-level expression matrix to gene level

Description

For each gene symbol keep the probe with the highest cross-sample mean expression. This is the paper's probe-annotation folding rule.

Usage

collapse_probes(expr, probe_id = rownames(expr), gene_id)

Arguments

Value

Gene x sample numeric matrix (rownames = gene symbols).

Examples

expr <- matrix(rnorm(40), nrow = 4)
colnames(expr) <- paste0("S", 1:10)
collapse_probes(expr, c("P1", "P2", "P3", "P4"),
                c("VIM", "VIM", "CDH2", "MYC"))

Bundled bioIOT demo dataset

Description

Pre-computed synthetic demo data for quick experimentation with fit_iot, transition_matrix and runIOT. Regenerate with bioIOT::simulate_iot_states(seed = 1).

Format

A list as returned by simulate_iot_states(seed = 1) with default arguments: u, phi, a, b, P_true, T_true, theta_true, embedding, K, F_emb, cell_embedding, cell_state, cell_time.

Examples

data(demo_iot_states)
names(demo_iot_states)
demo_iot_states$K

Fit inverse optimal transport feature weights

Description

Fits feature weights \theta so that the soft-marginal OT plan induced by C = -einsum(\phi, \theta) reproduces the observed row-conditional transitions T. Two-stage fitting (l1 selection then Buehlmann-style debias refit) with multi-restart; gradients are exact implicit differentiations of the fixed point (implicit function theorem), which stays numerically stable where unrolled backpropagation diverges.

Usage

fit_iot(phi, a, b, T_obs, mu = 0.5, lam = 0.05, eps = 1, epochs = 300,
  lr = 0.01, n_restart = 4, seed = 1, two_stage = TRUE,
  iters = 1000L, damp = 0.5, standardize = TRUE, verbose = FALSE)
## S3 method for class 'bioIOT_fit'
print(x, ...)
## S3 method for class 'bioIOT_fit'
summary(object, ...)

Arguments

Value

Object of class bioIOT_fit with components theta (debiased weights), theta1 (stage-1 weights), support (logical mask), loss (final row-CE), restart_losses, scenarios (stored standardized scenarios), meta (standardization transforms), hyper and dimensions K, n_feat.

Examples

set.seed(1)
sim <- simulate_iot_states(K = 5, seed = 1)
fit <- fit_iot(sim$phi, sim$a, sim$b, sim$T_true, n_restart = 1, epochs = 100)
fit$theta
summary(fit)

Extract GSM ids from CEL filenames

Description

Extract GSM sample ids from CEL filenames, vectorized.

Usage

gsm_id(filenames)

Arguments

Value

Character vector of GSM ids; NA where no match.

Examples

gsm_id(c("GSM1523727_INT_A.CEL.gz", "sample_no_id.CEL", NA))

Cost construction, likelihood and feature standardization

Description

make_cost: linear feature cost C_{ij} = -\sum_k \phi_{ijk} \theta_k. row_ce_loss: cross-entropy between observed row-conditional transitions and the model Q = P/a; zero-mass source states are masked out. zscore_phi: z-scores each feature across all (i, j) entries and returns the transform for re-application.

Usage

make_cost(phi, theta)
row_ce_loss(T_obs, P, a, eps_t = 1e-12)
zscore_phi(phi)

Arguments

Value

make_cost: (K, K) cost matrix. row_ce_loss: numeric loss (lower is better). zscore_phi: list with phi_z ((K, K, F) standardized array) and meta (2 x F matrix with rows "mean" and "sd").

Examples

phi <- array(rnorm(3 * 3 * 2), c(3, 3, 2))
C <- make_cost(phi, c(1, -1))
out <- zscore_phi(phi)
row_ce_loss(matrix(0.5, 3, 3), matrix(0.25, 3, 3), rep(1, 3) / 3)

IOT pathway marker genes (8 pathways)

Description

The pathway marker gene library used by the paper's 8-dimensional IOT cost features: EMT, Angiogenesis, Hypoxia, Stemness, Immune_Cytotoxic, CellCycle, TGFb and Chemokine. Genes are HGNC symbols.

Usage

pathway_markers

Value

A named list of 8 character vectors of HGNC gene symbols.

Examples

names(pathway_markers)
length(pathway_markers$EMT)

bioIOT visualisation

Description

plot_transition_heatmap: transition-matrix heatmap with annotated weights. plot_transition_flow: transition arrows on a 2-D state embedding, width proportional to transition mass (CellRank-style). plot_theta: barplot of fitted feature weights, selected support highlighted. plot_pathway_trend: pathway score trajectories over time (loess).

Usage

plot_transition_heatmap(Q, labels = NULL)
plot_transition_flow(Q, embedding, labels = NULL, threshold = 0.05)
plot_theta(fit, labels = NULL)
plot_pathway_trend(pw_scores, time, se = TRUE)

Arguments

Value

A ggplot object.

Examples

Q <- matrix(c(0.7, 0.3, 0, 0.2, 0.6, 0.2, 0.1, 0.1, 0.8), 3, 3, byrow = TRUE)
plot_transition_heatmap(Q)
emb <- matrix(c(0, 0, 1, 1, 2, 0), 3, 2, byrow = TRUE)
plot_transition_flow(Q, emb)

set.seed(1)
sim <- simulate_iot_states(K = 5, seed = 1)
fit <- fit_iot(sim$phi, sim$a, sim$b, sim$T_true, n_restart = 1, epochs = 100)
plot_theta(fit)

expr <- matrix(rnorm(200 * 12), nrow = 200)
rownames(expr) <- paste0("G", 1:200)
colnames(expr) <- paste0("S", 1:12)
rownames(expr)[1] <- "VIM"; rownames(expr)[2] <- "CDH2"; rownames(expr)[3] <- "MKI67"
plot_pathway_trend(score_pathways(expr), time = sort(runif(12)))

Run IOT on a single-cell object

Description

Aggregates cells into states (clusters), builds state-transition features from the cell embedding, optionally fits IOT weights against observed transitions T_obs, and returns the state transition matrix with optional random-walk pseudotime.

Usage

runIOT(object, ...)

## S3 method for class 'matrix'
runIOT(object, state, from, to, root = NULL,
  n_dim = NULL, T_obs = NULL, mu = 0.5, eps = 1, lam = 0.05,
  epochs = 300, lr = 0.01, n_restart = 4, seed = 1,
  two_stage = TRUE, ...)

## S3 method for class 'SingleCellExperiment'
runIOT(object, state_col, time_col,
  from, to, dimred = "PCA", root = NULL, ...)

## S3 method for class 'Seurat'
runIOT(object, group.by = NULL, split.by = NULL,
  from = NULL, to = NULL, reduction = "pca", root = NULL, ...)

Arguments

Value

List with fit (bioIOT_fit or NULL), Q (transition matrix), u (state centroids), a, b, phi, theta and pseudotime (if root given).

Examples

set.seed(1)
sim <- simulate_iot_states(K = 5, n_cells = 40, seed = 1)
res <- runIOT(sim$cell_embedding, sim$cell_state,
              from = sim$cell_time == "t0", to = sim$cell_time == "t1",
              root = "S1", n_restart = 1, epochs = 100)
res$Q[1:3, 1:3]
res$pseudotime

Score bulk-cohort samples on the 8 IOT pathways

Description

Per-gene z-scores across samples, then the mean of the pathway marker genes per sample. Exactly the scoring used to build the paper's bulk pathway scores from gene x sample expression matrices.

Usage

score_pathways(expr_gene, markers = pathway_markers)

Arguments

Value

Sample x pathway numeric matrix (rownames = sample ids, colnames = pathway names). Pathways without any marker present in expr_gene yield NA columns.

Examples

set.seed(1)
expr <- matrix(rnorm(200 * 6), nrow = 200)
rownames(expr) <- paste0("G", 1:200)
colnames(expr) <- paste0("S", 1:6)
rownames(expr)[1] <- "VIM"; rownames(expr)[2] <- "CDH2"
pw <- score_pathways(expr)
dim(pw)

Simulate single-cell state-transition data for bioIOT

Description

Generates a reproducible synthetic single-cell-like dataset: states with feature centroids, source/target timepoint masses, a true IOT plan and transition matrix, plus cell-level metadata for runIOT. The bundled demo_iot_states dataset is produced by this function with its default seed.

Usage

simulate_iot_states(K = 6, F_emb = 2, n_cells = 50, seed = 1,
  theta_true = c(0.9, -0.7, 1.1), mu = 0.5, eps = 1)

Arguments

Value

List with u (K x F_emb state centroids), phi ((K, K, F_emb + 1) features), a, b (normalized state masses), P_true, T_true (row-conditional), theta_true, embedding (K x 2 state coordinates), K, F_emb, cell_embedding (cells x F_emb), cell_state and cell_time (cell-level factors).

Examples

sim <- simulate_iot_states(K = 5, seed = 1)
names(sim)
round(sim$T_true, 2)

Semi-relaxed OT solver and row-conditional transitions

Description

soft_sinkhorn solves the row-marginal-hard / column-marginal-KL-soft problem \min_P \langle C, P \rangle - \epsilon H(P) + \mu\, KL(col(P) \| b) subject to P 1 = a, via Anderson-accelerated damped fixed-point iteration. row_conditional returns Q(i,\cdot) = P(i,\cdot) / a_i.

Usage

soft_sinkhorn(C, a, b, mu = 0.5, eps = 1, iters = 1000L, damp = 0.5,
  tol = 1e-12)
row_conditional(P, a, eps_t = 1e-300)

Arguments

Value

soft_sinkhorn: (K, K) transport plan with row sums equal to the normalized a. row_conditional: (K, K) matrix; rows with a_i = 0 are all-zero.

Examples

K <- 5
set.seed(1)
P <- soft_sinkhorn(matrix(rnorm(25), 5), rep(1, 5), rep(1, 5))
rowSums(P)
row_conditional(P, rep(1, 5) / 5)

Inspect a GEO RAW tar without extracting

Description

Check whether a GEO *_RAW.tar contains CEL data files or only platform (bgx.gz) files, without extracting the archive.

Usage

has_cel_file(tar_path)
find_platform_file(tar_path)

Arguments

Value

has_cel_file: TRUE if the tar contains *.CEL (optionally .gz) members. find_platform_file: the first *.bgx.gz platform filename, or NA_character_.

Examples

d <- file.path(tempdir(), "bioIOT-tar-example")
dir.create(d, showWarnings = FALSE)
cel <- file.path(d, "sample.CEL.gz")
bgx <- file.path(d, "platform.bgx.gz")
writeLines("demo", cel)
writeLines("demo", bgx)
tmp_tar <- tempfile(fileext = ".tar")
utils::tar(tmp_tar, c(cel, bgx), tar = "internal")
has_cel_file(tmp_tar)
find_platform_file(tmp_tar)
unlink(c(tmp_tar, d), recursive = TRUE)

Transition matrix, pseudotime and state features

Description

transition_matrix: re-solves the plan at the fitted \theta and returns Q = P/a. pseudotime_from_transition: expected number of random-walk steps to reach the root state (root absorbing), turning an IOT transition matrix into per-state pseudotime. build_state_features: builds the paper's feature library: per-dimension pure-column target-state features plus the state-similarity interaction block \phi_{ij,F+1} = u_i \cdot u_j.

Usage

transition_matrix(fit, which = 1, phi = NULL, a = NULL, b = NULL)
pseudotime_from_transition(Q, root)
build_state_features(u)

Arguments

Value

transition_matrix: (K, K) row-stochastic transition matrix. pseudotime_from_transition: named numeric vector of expected random-walk hitting times (root = 0). build_state_features: (K, K, D + 1) feature array with dimnames list(NULL, NULL, c(colnames(u), "sim")).

Examples

set.seed(1)
sim <- simulate_iot_states(K = 5, seed = 1)
fit <- fit_iot(sim$phi, sim$a, sim$b, sim$T_true, n_restart = 1, epochs = 100)
Q <- transition_matrix(fit)
rowSums(Q)
pseudotime_from_transition(Q, root = 1)
u <- matrix(rnorm(6 * 2), 6, 2, dimnames = list(NULL, c("PC1", "PC2")))
dim(build_state_features(u))