Principal Convex Hull Analysis via Rust PCHA

Fit archetypes to your data using the fast Rust implementation of Principal Convex Hull Analysis (PCHA). Optionally you can warm‐start the solver by providing initial C and S matrices.

Usage

pcha(
  input_mat,
  noc,
  c_init = NULL,
  s_init = NULL,
  max_iter = 750L,
  conv_crit = 1e-06
)

Arguments

input_mat

A numeric matrix of size \(p\times n\), where p is the number of features (rows) and n the number of samples.

c_init

Optional numeric matrix of size n x k giving an initial guess for the archetype coefficients C. Pass NULL (the default) to let PCHA pick its own seed.

s_init

Optional numeric matrix of size k x n giving an initial guess for the cell‐to‐archetype weights S. Pass NULL (the default) to let PCHA pick its own seed.

max_iter

maximum number of PCHA updates (default 750)

conv_crit

convergence threshold on relative ΔSSE (default 1e-6)

k

Integer; the number of archetypes \(k\) to fit (1 <= k <= n).

Value

A named list with components

C

An n x k matrix of archetype coefficients.

S

A k x n matrix of sample weights.

XC

A p x k matrix of fitted archetype profiles.

sse

The final residual sum‐of‐squares.

varExpl

The fraction of variance explained, \((SST - SSE)/SST\).

Examples

if (FALSE) { # \dontrun{
# simulate toy data
set.seed(1)
X <- matrix(rexp(60*300), nrow = 60, ncol = 300)

# fit 5 archetypes
res <- pcha_rust(X, k = 5)

# warm‐start with C0 and S0
C0 <- matrix(0, ncol(X), 5)
C0[sample(ncol(X),5) + 5*seq_len(5) - 5] <- 1
S0 <- matrix(runif(5*ncol(X)), 5, ncol(X))
res2 <- pcha_rust(X, k = 5, c_init = C0, s_init = S0)
} # }