ecotyper.nmf

Port of the parts of the R package NMF (v0.28) that EcoTyper uses.

  • nmf(x, rank, method="brunet", seed=<int>, .opt="P1") → nmf_brunet()

  • NMFpredict (EcoTyper lib/ecotyper.R) → nmf_predict()

  • NMFfitX(list, .merge=TRUE), cophcor, dispersion, silhouette → merge_runs() and friends.

The multiplicative updates replicate NMF’s C++ kernels (src/divergence.cpp) operation by operation — same accumulation order and the fused multiply-adds clang emits for them — so that, given the same initial matrices, W and H agree with R bit for bit.

Functions

cophcor(consensus)

cophcor(consensus) with average linkage.

dispersion(consensus)

factor_codes(values)

Codes of as.factor(values) for positive integers (levels sorted numerically).

fitted(W, H)

W %*% H via BLAS dgemm called as R does (column-major, no transposes).

kl_divergence(V, W, H[, exact])

merge_runs(fits)

NMFfitX(list_of_fits, .merge=TRUE).

nmf_brunet(V, rank, seed, *[, max_iter, exact])

nmf(V, rank, method="brunet", seed=seed, .opt="P1") (single run).

nmf_cd(V, rank, seed, *[, max_iter, tol])

Alternative solver (nmf_method="cd", not EcoTyper/R-equivalent): Frobenius-loss NMF by coordinate descent (scikit-learn NMF(solver="cd")), started from the same rnmf initialisation as nmf_brunet() and stopped by scikit-learn's tolerance rule instead of the connectivity rule.

nmf_predict(W, new_data, rng, *[, max_iter, ...])

EcoTyper's NMFpredict(W, new_data).

posneg(x)

NMF::posneg: rbind(pmax(x, 0), pmax(-x, 0)) if any entry < 0.

predict_columns(H)

.predict.nmf(t(H)): which.max(abs(h)) per column (1-based).

reorder_dendrogram_order(merge, wts)

order.dendrogram(reorder(as.dendrogram(hc), wts)) (1-based leaves).

rnmf(rank, target, rng)

rnmf(rank, target): W (n×r) then H (r×p) ~ U(0, max(max(target), 1)), clamped with pmin(., max(abs(target))).

run_brunet(V, W0, H0, *[, update_w, ...])

Run Brunet multiplicative updates from (W0, H0) with the connectivity stop.

silhouettes(merged)

Average silhouette widths as in state_discovery_combine_NMF_restarts.R: samples, features, chc, consensus.

Classes

NMFFit(W, H, niter, converged[, deviance, seed])

Result of a single NMF run (NMFfit).

NMFMerged(fit, consensus, nrun[, runs_used])

NMFfitX1: best fit + consensus matrix over restarts.
ecotyper.nmf.posneg(x)[source]

NMF::posneg: rbind(pmax(x, 0), pmax(-x, 0)) if any entry < 0.

Parameters:

x (ndarray)

Return type:

ndarray

ecotyper.nmf.rnmf(rank, target, rng)[source]

rnmf(rank, target): W (n×r) then H (r×p) ~ U(0, max(max(target), 1)), clamped with pmin(., max(abs(target))).

Parameters:
Return type:

tuple[ndarray, ndarray]

class ecotyper.nmf.NMFFit(W, H, niter, converged, deviance=nan, seed=None)[source]

Bases: object

Result of a single NMF run (NMFfit).

Parameters:
W: ndarray
H: ndarray
niter: int
converged: bool
deviance: float = nan
seed: int | None = None
predict()[source]

predict(fit): 1-based index of the dominant row of H per column.

Return type:

ndarray

connectivity()[source]
Return type:

ndarray

ecotyper.nmf.run_brunet(V, W0, H0, *, update_w=True, max_iter=2000, exact=True, threads=1)[source]

Run Brunet multiplicative updates from (W0, H0) with the connectivity stop.

exact=False uses BLAS products (_brunet_loop_fast()) instead of the R-exact kernels. threads: OpenMP threads for the C kernel (same result for any value).

Parameters:
Return type:

tuple[ndarray, ndarray, int, bool]

ecotyper.nmf.fitted(W, H)[source]

W %*% H via BLAS dgemm called as R does (column-major, no transposes).

Parameters:
Return type:

ndarray

ecotyper.nmf.kl_divergence(V, W, H, exact=True)[source]
Parameters:
Return type:

float

ecotyper.nmf.nmf_brunet(V, rank, seed, *, max_iter=2000, exact=True)[source]

nmf(V, rank, method="brunet", seed=seed, .opt="P1") (single run).

exact=False: same initialisation and stopping rule, BLAS updates (not bit-identical to R).

Parameters:
Return type:

NMFFit

ecotyper.nmf.nmf_cd(V, rank, seed, *, max_iter=2000, tol=0.0001)[source]

Alternative solver (nmf_method="cd", not EcoTyper/R-equivalent): Frobenius-loss NMF by coordinate descent (scikit-learn NMF(solver="cd")), started from the same rnmf initialisation as nmf_brunet() and stopped by scikit-learn’s tolerance rule instead of the connectivity rule. deviance is the Frobenius reconstruction error (used to pick the best restart).

Parameters:
Return type:

NMFFit

ecotyper.nmf.nmf_predict(W, new_data, rng, *, max_iter=2000, exact=True, threads=1)[source]

EcoTyper’s NMFpredict(W, new_data).

W has 2g rows (<gene>__pos then <gene>__neg) and new_data is the (scaled) g × p matrix already aligned to the training genes. Rows of the posneg-transformed data with zero variance are dropped from both, an initial H is drawn with rnmf (after an unused W draw, as in R), and only H is updated. Returns (H, niter, keep_rows).

Parameters:
ecotyper.nmf.predict_columns(H)[source]

.predict.nmf(t(H)): which.max(abs(h)) per column (1-based).

Parameters:

H (ndarray)

Return type:

ndarray

ecotyper.nmf.factor_codes(values)[source]

Codes of as.factor(values) for positive integers (levels sorted numerically).

Parameters:

values (ndarray)

Return type:

ndarray

class ecotyper.nmf.NMFMerged(fit, consensus, nrun, runs_used=<factory>)[source]

Bases: object

NMFfitX1: best fit + consensus matrix over restarts.

Parameters:
fit: NMFFit
consensus: ndarray
nrun: int
runs_used: list
ecotyper.nmf.merge_runs(fits)[source]

NMFfitX(list_of_fits, .merge=TRUE).

Parameters:

fits (list[NMFFit])

Return type:

NMFMerged

ecotyper.nmf.cophcor(consensus)[source]

cophcor(consensus) with average linkage.

Parameters:

consensus (ndarray)

Return type:

float

ecotyper.nmf.dispersion(consensus)[source]
Parameters:

consensus (ndarray)

Return type:

float

ecotyper.nmf.silhouettes(merged)[source]

Average silhouette widths as in state_discovery_combine_NMF_restarts.R: samples, features, chc, consensus.

Parameters:

merged (NMFMerged)

Return type:

dict

ecotyper.nmf.reorder_dendrogram_order(merge, wts)[source]

order.dendrogram(reorder(as.dendrogram(hc), wts)) (1-based leaves).

Parameters:
Return type:

ndarray