| Title: | Non-Negative Matrix Factorization with Kernel Covariates |
|---|---|
| Description: | Performs Non-negative Matrix Factorization (NMF) with Kernel Covariates. Given an observation matrix and kernel covariates, it optimizes both a basis matrix and a parameter matrix. Notably, if the kernel matrix is an identity matrix, the method simplifies to standard NMF. Also provides NMF with Random Effects (NMF-RE) via nmfre(), which estimates a mixed-effects model combining covariate-driven scores with unit-specific random effects together with wild bootstrap inference, and NMF-based Structural Equation Modeling (NMF-SEM) via nmf.sem(), which fits a two-block input-output model for blind source separation and path analysis. References: Satoh (2025) <doi:10.48550/arXiv.2403.05359>; Satoh (2025) <doi:10.48550/arXiv.2510.10375>; Satoh (2025) <doi:10.48550/arXiv.2512.18250>; Satoh (2026) <doi:10.48550/arXiv.2603.01468>; Satoh (2026) <doi:10.1007/s42081-025-00314-0>. |
| Authors: | Kenichi Satoh [aut, cre] (ORCID: <https://orcid.org/0000-0003-4436-9347>) |
| Maintainer: | Kenichi Satoh <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.7.3 |
| Built: | 2026-05-13 23:16:01 UTC |
| Source: | https://github.com/ksatohds/nmfkc |
Returns the coefficients data frame from a fitted NMF model
that has been passed through an inference function
(nmfkc.inference, nmfae.inference,
nmfre.inference).
If inference has not been run, returns the parameter matrix
() directly.
For nmf.sem objects, returns (exogenous block) as fallback.
## S3 method for class 'nmf' coef(object, ...) ## S3 method for class 'nmf.sem' coef(object, ...)## S3 method for class 'nmf' coef(object, ...) ## S3 method for class 'nmf.sem' coef(object, ...)
object |
A fitted model object of class |
... |
Not used. |
A data frame of coefficients (if inference was performed),
or the parameter matrix .
nmfkc.inference, nmfae.inference,
nmfre.inference, nmf.sem.inference
Y <- matrix(cars$dist, nrow = 1) A <- rbind(1, cars$speed) result <- nmfkc(Y, A, rank = 1) coef(result) # returns C matrix result2 <- nmfkc.inference(result, Y, A) coef(result2) # returns coefficients data frameY <- matrix(cars$dist, nrow = 1) A <- rbind(1, cars$speed) result <- nmfkc(Y, A, rank = 1) coef(result) # returns C matrix result2 <- nmfkc.inference(result, Y, A) coef(result2) # returns coefficients data frame
Returns the reconstructed matrix from a fitted
NMF model.
For nmf.sem objects, returns the equilibrium prediction
if available. Supply Y1 and
Y2 to get the direct reconstruction
instead.
## S3 method for class 'nmf' fitted(object, ...) ## S3 method for class 'nmfae' fitted(object, ...) ## S3 method for class 'nmf.sem' fitted(object, ...)## S3 method for class 'nmf' fitted(object, ...) ## S3 method for class 'nmfae' fitted(object, ...) ## S3 method for class 'nmf.sem' fitted(object, ...)
object |
A fitted model object of class |
... |
For |
The fitted matrix .
nmfkc, nmfae, nmfre,
nmf.sem, residuals.nmf
result <- nmfkc(matrix(runif(50), 5, 10), rank = 2) fitted(result)result <- nmfkc(matrix(runif(50), 5, 10), rank = 2) fitted(result)
Fits the NMF-FFB model
under non-negativity constraints with orthogonality and sparsity regularization. The function returns the estimated latent factors, structural coefficient matrices, and the implied equilibrium (input–output) mapping.
At equilibrium, the model can be written as
where is a
Leontief-type cumulative-effect operator in latent space.
Internally, the latent feedback and exogenous loading matrices are stored as
C1 and C2, corresponding to and ,
respectively.
nmf.ffb( Y1, Y2, rank = NULL, X.init = "nndsvd", X.L2.ortho = 100, C1.L1 = 1, C2.L1 = 0.1, epsilon = 1e-06, maxit = 5000, seed = 123, ... ) nmf.sem( Y1, Y2, rank = NULL, X.init = "nndsvd", X.L2.ortho = 100, C1.L1 = 1, C2.L1 = 0.1, epsilon = 1e-06, maxit = 5000, seed = 123, ... )nmf.ffb( Y1, Y2, rank = NULL, X.init = "nndsvd", X.L2.ortho = 100, C1.L1 = 1, C2.L1 = 0.1, epsilon = 1e-06, maxit = 5000, seed = 123, ... ) nmf.sem( Y1, Y2, rank = NULL, X.init = "nndsvd", X.L2.ortho = 100, C1.L1 = 1, C2.L1 = 0.1, epsilon = 1e-06, maxit = 5000, seed = 123, ... )
Y1 |
A non-negative numeric matrix of endogenous variables with rows = variables (P1), columns = samples (N). |
Y2 |
A non-negative numeric matrix of exogenous variables with
rows = variables (P2), columns = samples (N).
Must satisfy |
rank |
Integer; number of latent factors |
X.init |
Initialization strategy for the basis matrix
In all cases the result is column-normalized to |
X.L2.ortho |
L2 orthogonality penalty for |
C1.L1 |
L1 sparsity penalty for |
C2.L1 |
L1 sparsity penalty for |
epsilon |
Relative convergence threshold for the objective function.
Iterations stop when the relative change in reconstruction loss falls
below this value. Default: |
maxit |
Maximum number of iterations for the multiplicative updates.
Default: |
seed |
Random seed used to initialize |
... |
Additional hidden arguments controlling the optional
feedforward baseline (used both as an
|
A list with components:
X |
Estimated basis matrix ( |
C1 |
Estimated latent feedback matrix ( |
C2 |
Estimated exogenous loading matrix ( |
XC1 |
Feedback matrix |
XC2 |
Direct-effect matrix |
XC1.radius |
Spectral radius |
XC1.norm1 |
Induced 1-norm |
Leontief.inv |
Leontief-type inverse |
M.model |
Equilibrium mapping
|
amplification |
Latent amplification factor
|
amplification.bound |
Geometric-series upper bound
|
Q |
Effective latent dimension used in the fit. |
SC.cov |
Correlation between sample and model-implied covariance
(flattened) of |
SC.map |
Correlation between the equilibrium operator
|
MAE |
Mean absolute error between |
objfunc |
Vector of reconstruction losses per iteration. |
objfunc.full |
Vector of penalized objective values per iteration. |
iter |
Number of iterations actually performed. |
Satoh, K. (2025). Applying non-negative matrix factorization with covariates to structural equation modeling for blind input-output analysis. arXiv:2512.18250. https://arxiv.org/abs/2512.18250
nmf.sem.inference, nmf.sem.cv,
nmf.sem.split, nmf.sem.DOT,
summary.nmf.sem
# Simple NMF-FFB with iris data (non-negative) Y <- t(iris[, -5]) Y1 <- Y[1:2, ] # Sepal Y2 <- Y[3:4, ] # Petal result <- nmf.sem(Y1, Y2, rank = 2, maxit = 500) result$MAE# Simple NMF-FFB with iris data (non-negative) Y <- t(iris[, -5]) Y1 <- Y[1:2, ] # Sepal Y2 <- Y[3:4, ] # Petal result <- nmf.sem(Y1, Y2, rank = 2, maxit = 500) result$MAE
Performs K-fold cross-validation to evaluate the equilibrium mapping of the NMF-FFB model.
For each fold, nmf.sem is fitted on the training samples,
yielding an equilibrium mapping .
The held-out endogenous variables are then predicted from
using this mapping, and the mean absolute error (MAE) over all entries in the
test block is computed. The returned value is the average MAE across folds.
This implements the hyperparameter selection strategy described in the paper: hyperparameters are chosen by predictive cross-validation rather than direct inspection of the internal structural matrices.
nmf.ffb.cv(...) nmf.sem.cv( Y1, Y2, rank = NULL, X.init = "nndsvd", X.L2.ortho = 100, C1.L1 = 1, C2.L1 = 0.1, epsilon = 1e-06, maxit = 5000, ... )nmf.ffb.cv(...) nmf.sem.cv( Y1, Y2, rank = NULL, X.init = "nndsvd", X.L2.ortho = 100, C1.L1 = 1, C2.L1 = 0.1, epsilon = 1e-06, maxit = 5000, ... )
... |
Additional arguments passed to |
Y1 |
A non-negative numeric matrix of endogenous variables with rows = variables (P1), columns = samples (N). |
Y2 |
A non-negative numeric matrix of exogenous variables with
rows = variables (P2), columns = samples (N).
Must satisfy |
rank |
Integer; rank (number of latent factors) passed to |
X.init |
Initialization strategy for |
X.L2.ortho |
L2 orthogonality penalty for |
C1.L1 |
L1 sparsity penalty for |
C2.L1 |
L1 sparsity penalty for |
epsilon |
Convergence threshold for |
maxit |
Maximum number of iterations for |
A numeric scalar: mean MAE across CV folds.
Y <- t(iris[, -5]) Y1 <- Y[1:2, ] Y2 <- Y[3:4, ] mae <- nmf.sem.cv(Y1, Y2, rank = 2, maxit = 500, nfolds = 3) maeY <- t(iris[, -5]) Y1 <- Y[1:2, ] Y2 <- Y[3:4, ] mae <- nmf.sem.cv(Y1, Y2, rank = 2, maxit = 500, nfolds = 3) mae
Creates a Graphviz DOT script that visualizes the structural network
estimated by nmf.sem.
The resulting diagram displays:
endogenous observed variables (),
exogenous observed variables (),
latent factors (, ..., ),
together with the non-negative path coefficients whose magnitudes exceed a user-specified threshold.
Directed edges represent estimated relationships:
: entries of C2 (exogenous loadings),
: rows of X (factor-to-endogenous mappings),
: entries of C1 (feedback paths).
Edge widths are scaled by coefficient magnitude, and nodes are placed in optional visual clusters. Only variables participating in edges above the threshold are displayed, while latent factors are always shown.
nmf.ffb.DOT(result, ...) nmf.sem.DOT( result, weight_scale = 5, weight_scale_c2 = weight_scale, weight_scale_x1 = weight_scale, weight_scale_feedback = weight_scale, threshold = 0.01, sig.level = 0.1, rankdir = "LR", fill = TRUE, cluster.box = c("normal", "faint", "invisible", "none"), cluster.labels = NULL, hide.isolated = TRUE, ... )nmf.ffb.DOT(result, ...) nmf.sem.DOT( result, weight_scale = 5, weight_scale_c2 = weight_scale, weight_scale_x1 = weight_scale, weight_scale_feedback = weight_scale, threshold = 0.01, sig.level = 0.1, rankdir = "LR", fill = TRUE, cluster.box = c("normal", "faint", "invisible", "none"), cluster.labels = NULL, hide.isolated = TRUE, ... )
result |
A list returned by |
... |
For backward compatibility: accepts deprecated names
|
weight_scale |
Base scaling factor for edge widths. |
weight_scale_c2 |
Scaling factor for edges
|
weight_scale_x1 |
Scaling factor for edges
|
weight_scale_feedback |
Scaling factor for feedback edges
|
threshold |
Minimum coefficient value needed for an edge to be drawn. |
sig.level |
Significance level for filtering structural edges
( |
rankdir |
Graphviz rank direction (e.g., |
fill |
Logical; whether to use filled node shapes. |
cluster.box |
Character string controlling the visibility and style
of cluster frames around Y2, factors, and Y1 blocks.
One of |
cluster.labels |
Optional character vector of length 3 giving custom labels for the Y2, factor, and Y1 clusters. |
hide.isolated |
Logical. If |
A character string representing a valid Graphviz DOT script.
nmf.sem, nmf.sem.inference,
plot.nmfkc.DOT
Y <- t(iris[, -5]) Y1 <- Y[1:2, ] Y2 <- Y[3:4, ] result <- nmf.sem(Y1, Y2, rank = 2, maxit = 500) dot <- nmf.sem.DOT(result) cat(dot)Y <- t(iris[, -5]) Y1 <- Y[1:2, ] Y2 <- Y[3:4, ] result <- nmf.sem(Y1, Y2, rank = 2, maxit = 500) dot <- nmf.sem.DOT(result) cat(dot)
nmf.sem.inference performs statistical inference on the structural
coefficient matrices (latent feedback, ) and
(exogenous loading, ) from a fitted
nmf.sem model.
The procedure is a full pair bootstrap that holds the basis
matrix from the original fit fixed across all replicates
(which avoids label switching and gives a clean conditional
interpretation: “uncertainty of the structural coefficients given the
measurement model”):
For each replicate , resample column indices
with replacement from
and form , .
Re-estimate by running the
nmf.sem multiplicative updates with
held fixed (no update; no centroid sort), using the same
C1.L1, C2.L1 as the original fit.
Discard replicates that violate stationarity
() or have an amplification ratio
exceeding the geometric-series bound by more than 1\
Because are non-negative by construction, exact
zeros are essentially never observed in the bootstrap distribution.
Significance is assessed via a support rate at a small display
threshold (default 0.01):
This is a one-sided counterpart of the classical -value:
large support_rate indicates strong evidence that the entry is
meaningfully positive. Significance markers follow the lavaan
convention with the natural correspondence :
* (sup > 0.95), ** (sup > 0.99), ***
(sup > 0.999). Cutoffs use strict greater-than so the rule
mirrors the standard R convention for p-values (p < 0.05 / 0.01 /
0.001 → //), translated to support_rate via
.
nmf.ffb.inference( object, Y1, Y2, B = 1000L, threshold = 0.01, ci.level = 0.95, C1.L1 = 1, C2.L1 = 0.1, seed = 123L, ... ) nmf.sem.inference( object, Y1, Y2, B = 1000L, threshold = 0.01, ci.level = 0.95, C1.L1 = 1, C2.L1 = 0.1, seed = 123L, ... )nmf.ffb.inference( object, Y1, Y2, B = 1000L, threshold = 0.01, ci.level = 0.95, C1.L1 = 1, C2.L1 = 0.1, seed = 123L, ... ) nmf.sem.inference( object, Y1, Y2, B = 1000L, threshold = 0.01, ci.level = 0.95, C1.L1 = 1, C2.L1 = 0.1, seed = 123L, ... )
object |
A fitted object returned by |
Y1 |
Endogenous variable matrix (P1 x N). Must match the data
used in |
Y2 |
Exogenous variable matrix (P2 x N). Same. |
B |
Number of bootstrap replicates. Default |
threshold |
Display threshold |
ci.level |
Confidence level for the percentile bootstrap CI.
Default |
C1.L1, C2.L1
|
L1 sparsity penalties used by the original
|
seed |
Base RNG seed for the bootstrap. Each replicate uses
|
... |
Hidden options:
|
The input object with additional bootstrap inference
components:
coefficients |
Data frame with rows for every entry of |
C1.support.rate, C2.support.rate
|
Per-element support rates (Q x P1 and Q x P2 matrices). |
C1.ci.lower, C1.ci.upper, C2.ci.lower, C2.ci.upper
|
Per-element percentile CI bounds. |
C1.array, C2.array
|
Bootstrap distributions: 3D arrays of shape
B x Q x P1 (and B x Q x P2). Invalid replicates contain |
rho.boot, AR.boot, iter.boot
|
Per-replicate spectral radius, amplification ratio, and inner-loop iteration count. |
bootstrap.B, bootstrap.threshold, bootstrap.ci.level
|
Inputs recorded for reproducibility. |
bootstrap.n.valid, bootstrap.n.invalid
|
Validity counts. |
This function's interface changed at v0.6.8: the legacy 1-step Newton
wild bootstrap (with sandwich SE) has been replaced by the full pair
bootstrap described above, following the paper revision. The fields
sigma2.used, C2.se, C2.se.boot, C2.p.side
that the previous implementation produced are no longer present.
Satoh, K. (2025). Applying non-negative matrix factorization with covariates to structural equation modeling for blind input-output analysis. arXiv:2512.18250. https://arxiv.org/abs/2512.18250
Y <- t(iris[, -5]) Y1 <- Y[1:2, ]; Y2 <- Y[3:4, ] res <- nmf.sem(Y1, Y2, rank = 2) res2 <- nmf.sem.inference(res, Y1, Y2, B = 200) # quick demo head(res2$coefficients)Y <- t(iris[, -5]) Y1 <- Y[1:2, ]; Y2 <- Y[3:4, ] res <- nmf.sem(Y1, Y2, rank = 2) res2 <- nmf.sem.inference(res, Y1, Y2, B = 200) # quick demo head(res2$coefficients)
Infers a heuristic partition of observed variables into exogenous ()
and endogenous () blocks for use in NMF-FFB.
The method is based on positive-SEM logic, causal ordering, and optional
sign alignment using the first principal component (PC1).
The procedure:
internally standardizes variables (mean 0, sd 1),
optionally flips signs so that most variables align positively with PC1,
infers a causal ordering by repeatedly regressing each variable on the remaining ones and selecting the variable with the largest minimum standardized coefficient,
determines an exogenous block by scanning the ordering from upstream
and stopping at the first variable whose strongest parent coefficient
exceeds threshold.
If n.exogenous is supplied, it overrides the automatic threshold rule.
nmf.ffb.split(x, ...) nmf.sem.split( x, n.exogenous = NULL, threshold = 0.1, auto.flipped = TRUE, verbose = FALSE )nmf.ffb.split(x, ...) nmf.sem.split( x, n.exogenous = NULL, threshold = 0.1, auto.flipped = TRUE, verbose = FALSE )
x |
A numeric matrix or data frame with rows = samples and columns = observed variables. |
... |
Reserved for future use; currently unused (also accepted
by the |
n.exogenous |
Optional integer specifying the number of exogenous variables
( |
threshold |
Standardized regression-coefficient threshold used in the
automatic exogenous–endogenous split. A variable is treated as endogenous
once its maximum standardized parent coefficient exceeds this value.
(Default: |
auto.flipped |
Logical; if |
verbose |
Logical; if |
A list with:
endogenous.variables |
Character vector of variables selected as endogenous ( |
exogenous.variables |
Character vector of variables selected as exogenous ( |
ordered.variables |
Variables in inferred causal order (from exogenous to endogenous). |
is.flipped |
Logical vector indicating which variables were sign-flipped during processing. |
n.exogenous |
Integer giving the number of exogenous variables. |
# Infer exogenous/endogenous split from iris sp <- nmf.sem.split(iris[, -5], n.exogenous = 2) sp$endogenous.variables sp$exogenous.variables# Infer exogenous/endogenous split from iris sp <- nmf.sem.split(iris[, -5], n.exogenous = 2) sp$endogenous.variables sp$exogenous.variables
nmfae fits a three-layer nonnegative matrix factorization model
, where is a decoder basis
(column sum 1), is a bottleneck parameter matrix,
is an encoder basis (row sum 1), and is the input matrix.
When Y2 = Y1, the model acts as a non-negative autoencoder.
When Y1 != Y2, it acts as a heteroencoder.
Initialization uses a three-step NMF procedure via nmfkc:
(1) nmfkc(Y1, rank=Q) to obtain ,
(2) nmfkc(Y1, A=Y2, rank=Q) with fixed to obtain ,
(3) nmfkc(Y2, rank=R) to factor into and .
nmfae( Y1, Y2 = Y1, rank = 2, rank.encoder = rank, epsilon = 1e-04, maxit = 5000, verbose = FALSE, ... )nmfae( Y1, Y2 = Y1, rank = 2, rank.encoder = rank, epsilon = 1e-04, maxit = 5000, verbose = FALSE, ... )
Y1 |
Output matrix |
Y2 |
Input matrix |
rank |
Integer. Rank of the decoder basis |
rank.encoder |
Integer. Rank of the encoder basis |
epsilon |
Positive convergence tolerance. Default is |
maxit |
Maximum number of multiplicative update iterations. Default is 5000. |
verbose |
Logical. If |
... |
Additional arguments:
|
An object of class "nmfae", a list with components:
X1 |
Decoder basis matrix (P1 x Q), column sum 1. |
C |
Parameter matrix (Q x R). |
X2 |
Encoder basis matrix (R x P2), row sum 1. |
Y1hat |
Fitted values |
rank |
Named integer vector |
objfunc |
Final objective value. |
objfunc.iter |
Objective values by iteration. |
r.squared |
Coefficient of determination |
niter |
Number of iterations performed. |
runtime |
Elapsed time as a |
n.missing |
Number of missing (or zero-weighted) elements in |
n.total |
Total number of elements in |
This function is experimental. The interface may change in future versions.
Satoh, K. (2025). Applying Non-negative Matrix Factorization with Covariates to Multivariate Time Series. Japanese Journal of Statistics and Data Science.
Lee, D. D. and Seung, H. S. (2001). Algorithms for Non-negative Matrix Factorization. Advances in Neural Information Processing Systems, 13.
Saha, S. et al. (2022). Hierarchical Deep Learning Neural Network (HiDeNN): An Artificial Intelligence (AI) Framework for Computational Science and Engineering. Computer Methods in Applied Mechanics and Engineering, 399.
nmfae.inference, predict.nmfae, nmfae.ecv, nmfae.DOT, nmfkc
# Autoencoder example Y <- matrix(c(1,0,1,0, 0,1,0,1, 1,1,0,0), nrow=3, byrow=TRUE) res <- nmfae(Y, rank=2, rank.encoder=2) res$r.squared # Heteroencoder example Y1 <- matrix(c(1,0,0,1), nrow=2) Y2 <- matrix(runif(8), nrow=4) res2 <- nmfae(Y1, Y2, rank=2, rank.encoder=2)# Autoencoder example Y <- matrix(c(1,0,1,0, 0,1,0,1, 1,1,0,0), nrow=3, byrow=TRUE) res <- nmfae(Y, rank=2, rank.encoder=2) res$r.squared # Heteroencoder example Y1 <- matrix(c(1,0,0,1), nrow=2) Y2 <- matrix(runif(8), nrow=4) res2 <- nmfae(Y1, Y2, rank=2, rank.encoder=2)
nmfae.cv performs k-fold cross-validation by splitting columns (samples)
of and into div folds. For each fold, the model
is fitted on the training samples and
predictive performance is evaluated on the held-out samples.
When Y2 is a kernel matrix created by nmfkc.kernel
(detected via attributes), the symmetric kernel splitting convention is used:
Y2[train, train] for training and Y2[train, test] for prediction.
nmfae.cv(Y1, Y2 = Y1, rank = 2, rank.encoder = rank, ...)nmfae.cv(Y1, Y2 = Y1, rank = 2, rank.encoder = rank, ...)
Y1 |
Output matrix |
Y2 |
Input matrix |
rank |
Integer. Rank of the decoder basis. Default is 2. |
rank.encoder |
Integer. Rank of the encoder basis. Default is |
... |
Additional arguments passed to |
A list with components:
objfunc |
Mean squared error per valid element over all folds. |
sigma |
Residual standard error (RMSE), same scale as |
objfunc.block |
Per-fold squared error totals. |
block |
Integer vector of fold assignments (1, ..., |
This function is experimental. The interface may change in future versions; details are to be described in an upcoming paper.
nmfae, nmfae.ecv, nmfae.kernel.beta.cv,
nmfkc.cv
Y <- t(iris[1:30, 1:4]) res <- nmfae.cv(Y, rank = 2, rank.encoder = 2, nfolds = 5, maxit = 500) res$sigmaY <- t(iris[1:30, 1:4]) res <- nmfae.cv(Y, rank = 2, rank.encoder = 2, nfolds = 5, maxit = 500) res$sigma
nmfae.DOT generates a DOT language string for visualizing the structure
of a three-layer NMF model. Two graph types are supported:
"XCX" shows encoder factors, , and decoder factors;
"YXCXY" shows the full structure from through , ,
to .
Edge widths are proportional to matrix element values, and edges below
threshold are omitted for clarity.
nmfae.DOT( result, type = c("XCX", "YXCXY"), threshold = 0.01, sig.level = 0.1, rankdir = "LR", fill = TRUE, weight_scale = 5, weight_scale_x1 = weight_scale, weight_scale_theta = weight_scale, weight_scale_x2 = weight_scale, Y1.label = NULL, X1.label = NULL, X2.label = NULL, Y2.label = NULL, Y1.title = "Output (Y1)", X1.title = "Decoder (X1)", X2.title = "Encoder (X2)", Y2.title = "Input (Y2)", hide.isolated = TRUE )nmfae.DOT( result, type = c("XCX", "YXCXY"), threshold = 0.01, sig.level = 0.1, rankdir = "LR", fill = TRUE, weight_scale = 5, weight_scale_x1 = weight_scale, weight_scale_theta = weight_scale, weight_scale_x2 = weight_scale, Y1.label = NULL, X1.label = NULL, X2.label = NULL, Y2.label = NULL, Y1.title = "Output (Y1)", X1.title = "Decoder (X1)", X2.title = "Encoder (X2)", Y2.title = "Input (Y2)", hide.isolated = TRUE )
result |
An object of class |
type |
Character. Graph type: |
threshold |
Numeric. Edges with values below this are omitted. Default is 0.01. |
sig.level |
Numeric or |
rankdir |
Character. Graph direction for DOT layout. Default is |
fill |
Logical. If |
weight_scale |
Numeric. Base scale factor for edge widths. Default is 5. |
weight_scale_x1 |
Numeric. Scale factor for |
weight_scale_theta |
Numeric. Scale factor for |
weight_scale_x2 |
Numeric. Scale factor for |
Y1.label |
Character vector of output variable labels. |
X1.label |
Character vector of decoder basis labels. |
X2.label |
Character vector of encoder basis labels. |
Y2.label |
Character vector of input variable labels. |
Y1.title |
Character. Title for output node group. Default is |
X1.title |
Character. Title for decoder node group. Default is |
X2.title |
Character. Title for encoder node group. Default is |
Y2.title |
Character. Title for input node group. Default is |
hide.isolated |
Logical. If |
A character string containing the DOT graph specification.
This function is experimental. The interface may change in future versions; details are to be described in an upcoming paper.
set.seed(1) Y <- matrix(runif(20), nrow = 4) res <- nmfae(Y, rank = 2) dot <- nmfae.DOT(res)set.seed(1) Y <- matrix(runif(20), nrow = 4) res <- nmfae(Y, rank = 2) dot <- nmfae.DOT(res)
nmfae.ecv performs k-fold element-wise cross-validation by randomly
holding out individual elements of , assigning them a weight of 0
via Y1.weights, and evaluating the reconstruction error on those
held-out elements.
This method (also known as Wold's CV) is suitable for determining the optimal
rank pair in three-layer NMF. Both rank and rank.encoder accept
vector inputs. When rank.encoder = NULL (default), rank.encoder is set equal to rank
and pairs are evaluated element-wise (i.e., ).
When rank.encoder is explicitly specified, all combinations of rank and rank.encoder
are evaluated via expand.grid.
nmfae.ecv(Y1, Y2 = Y1, rank = 1:2, rank.encoder = NULL, ...)nmfae.ecv(Y1, Y2 = Y1, rank = 1:2, rank.encoder = NULL, ...)
Y1 |
Output matrix |
Y2 |
Input matrix |
rank |
Integer vector of decoder ranks to evaluate. Default is |
rank.encoder |
Integer vector of encoder ranks to evaluate. Default is |
... |
Additional arguments passed to |
A list with components:
objfunc |
Named numeric vector of mean MSE for each (Q, R) pair. |
sigma |
Named numeric vector of RMSE (square root of MSE) for each pair. |
objfunc.fold |
Named list of per-fold MSE vectors for each pair. |
folds |
List of length |
QR |
Data frame with columns |
This function is experimental. The interface may change in future versions; details are to be described in an upcoming paper.
Y <- t(iris[1:30, 1:4]) # Default: rank.encoder=NULL -> paired rank=rank.encoder res <- nmfae.ecv(Y, rank = 1:3, nfolds = 3, maxit = 500) res$sigma # Explicit rank.encoder: full grid res2 <- nmfae.ecv(Y, rank = 1:3, rank.encoder = 1:3, nfolds = 3, maxit = 500) res2$sigmaY <- t(iris[1:30, 1:4]) # Default: rank.encoder=NULL -> paired rank=rank.encoder res <- nmfae.ecv(Y, rank = 1:3, nfolds = 3, maxit = 500) res$sigma # Explicit rank.encoder: full grid res2 <- nmfae.ecv(Y, rank = 1:3, rank.encoder = 1:3, nfolds = 3, maxit = 500) res2$sigma
nmfae.heatmap displays the three factor matrices , ,
and as side-by-side heatmaps. This provides an alternative to DOT graph
visualization, especially when has many variables (e.g., kernel matrix).
nmfae.heatmap( x, Y1.label = NULL, X1.label = NULL, X2.label = NULL, Y2.label = NULL, palette = NULL, ... )nmfae.heatmap( x, Y1.label = NULL, X1.label = NULL, X2.label = NULL, Y2.label = NULL, palette = NULL, ... )
x |
An object of class |
Y1.label |
Character vector of output variable names (rows of |
X1.label |
Character vector of decoder basis labels (columns of |
X2.label |
Character vector of encoder basis labels (rows of |
Y2.label |
Character vector of input variable names (columns of |
palette |
Color palette vector. Default is white-orange-red (64 colors). |
... |
Not used. |
Invisible NULL. Called for its side effect (plot).
This function is experimental. The interface may change in future versions; details are to be described in an upcoming paper.
set.seed(1) Y <- matrix(runif(20), nrow = 4) res <- nmfae(Y, rank = 2) nmfae.heatmap(res)set.seed(1) Y <- matrix(runif(20), nrow = 4) res <- nmfae(Y, rank = 2) nmfae.heatmap(res)
Performs post-estimation inference for in the three-layer NMF model
, conditional on .
Uses sandwich covariance estimation and one-step wild bootstrap with
non-negative projection.
nmfae.inference(object, Y1, Y2 = Y1, wild.bootstrap = TRUE, ...)nmfae.inference(object, Y1, Y2 = Y1, wild.bootstrap = TRUE, ...)
object |
An object of class |
Y1 |
Output matrix |
Y2 |
Input matrix |
wild.bootstrap |
Logical. If |
... |
Additional arguments:
|
An object of class c("nmfae.inference", "nmfae"), inheriting all
components from the input object, with additional inference components:
sigma2.used |
Estimated |
C.se |
Sandwich standard errors for |
C.se.boot |
Bootstrap standard errors for |
C.ci.lower |
Lower CI bounds for |
C.ci.upper |
Upper CI bounds for |
coefficients |
Data frame with Estimate, SE, BSE, z, p-value for each element of |
C.p.side |
P-value type used. |
This function is experimental. The interface may change in future versions; details are to be described in an upcoming paper.
nmfae, summary.nmfae.inference
Y <- matrix(c(1,0,1,0, 0,1,0,1, 1,1,0,0), nrow=3, byrow=TRUE) res <- nmfae(Y, rank=2, rank.encoder=2) res2 <- nmfae.inference(res, Y) summary(res2)Y <- matrix(c(1,0,1,0, 0,1,0,1, 1,1,0,0), nrow=3, byrow=TRUE) res <- nmfae(Y, rank=2, rank.encoder=2) res2 <- nmfae.inference(res, Y) summary(res2)
nmfae.kernel.beta.cv selects the optimal beta parameter of the
kernel function by evaluating nmfae.cv for each candidate value.
The kernel matrix replaces in the three-layer
NMF model.
When beta = NULL, candidate values are automatically generated via
nmfkc.kernel.beta.nearest.med.
nmfae.kernel.beta.cv( Y1, rank = 2, rank.encoder = rank, U, V = NULL, beta = NULL, plot = TRUE, ... )nmfae.kernel.beta.cv( Y1, rank = 2, rank.encoder = rank, U, V = NULL, beta = NULL, plot = TRUE, ... )
Y1 |
Output matrix |
rank |
Integer. Rank of the decoder basis. Default is 2. |
rank.encoder |
Integer. Rank of the encoder basis. Default is |
U |
Covariate matrix |
V |
Covariate matrix |
beta |
Numeric vector of candidate beta values. If |
plot |
Logical. If |
... |
Additional arguments. Kernel-specific args ( |
A list with components:
beta |
The beta value that minimizes the cross-validation objective. |
objfunc |
Named numeric vector of objective function values for each candidate beta. |
nmfae.cv, nmfkc.kernel,
nmfkc.kernel.beta.cv
Y <- matrix(cars$dist, nrow = 1) U <- matrix(cars$speed, nrow = 1) res <- nmfae.kernel.beta.cv(Y, rank = 1, rank.encoder = 1, U = U, beta = c(0.01, 0.02, 0.05), nfolds = 5) res$betaY <- matrix(cars$dist, nrow = 1) U <- matrix(cars$speed, nrow = 1) res <- nmfae.kernel.beta.cv(Y, rank = 1, rank.encoder = 1, U = U, beta = c(0.01, 0.02, 0.05), nfolds = 5) res$beta
Assigns user-specified names to the decoder (X1 columns) and encoder
(X2 rows) bases of an nmfae object. The names propagate to
, the coefficients table, and all downstream displays
such as summary, nmfae.DOT, and nmfae.heatmap.
nmfae.rename(x, X1.colnames = NULL, X2.rownames = NULL)nmfae.rename(x, X1.colnames = NULL, X2.rownames = NULL)
x |
An object of class |
X1.colnames |
Character vector of length |
X2.rownames |
Character vector of length |
A modified copy of x with updated names.
set.seed(1) Y <- matrix(runif(15), nrow = 3) res <- nmfae(Y, rank = 2, rank.encoder = 2) res <- nmfae.rename(res, X1.colnames = c("Basis1", "Basis2"), X2.rownames = c("Enc1", "Enc2")) summary(res)set.seed(1) Y <- matrix(runif(15), nrow = 3) res <- nmfae(Y, rank = 2, rank.encoder = 2) res <- nmfae.rename(res, X1.colnames = c("Basis1", "Basis2"), X2.rownames = c("Enc1", "Enc2")) summary(res)
nmfae.signed fits a three-layer non-negative matrix factorization
autoencoder with a signed bottleneck, solving
where is the signed bottleneck. The basis
matrices (columns sum to 1) and (rows sum to 1) retain
their non-negative "parts-based" interpretability, while can
express anti-correlations (e.g., refractive index up vs. Abbe number down).
The algorithm uses Direct Multiplicative Updates derived from
Ding et al. (2010) sign-splitting technique, applied block-wise to the
four non-negative blocks . Each block update
monotonically decreases the true objective
(Lee-Seung auxiliary
function method).
Relation to nmfae: When suffices
(the nmfae case), nmfae.signed reduces to nmfae up to
the parameterization. Use nmfae.signed when the
data exhibit negative cross-property correlations that tri-NMF-AE cannot
express (e.g., high refractive index <-> low Abbe number trade-off).
nmfae.signed( Y1, Y2 = Y1, rank = 2, rank.encoder = rank, epsilon = 1e-04, maxit = 5000, verbose = FALSE, ... )nmfae.signed( Y1, Y2 = Y1, rank = 2, rank.encoder = rank, epsilon = 1e-04, maxit = 5000, verbose = FALSE, ... )
Y1 |
Output matrix |
Y2 |
Input matrix |
rank |
Integer. Decoder rank Q. Default 2.
Alias |
rank.encoder |
Integer. Encoder rank R. Default |
epsilon |
Relative convergence tolerance on the objective.
Default |
maxit |
Maximum iterations. Default 5000. |
verbose |
Logical. Print progress. Default |
... |
Additional arguments:
|
An object of class c("nmfae.signed", "nmfae", "nmf") with:
X1 |
Decoder basis (P1 x Q), column sum 1. |
Cp, Cn
|
Non-negative parts of |
C |
Signed bottleneck |
X2 |
Encoder basis (R x P2), row sum 1. |
Y1hat |
Fitted values |
H |
Encoding |
rank |
|
dims |
|
objfunc, objfunc.iter
|
Final and per-iteration objective values. |
r.squared, sigma, mae
|
Goodness of fit statistics. |
niter, runtime
|
Iterations and elapsed seconds. |
Y.signed |
Logical; whether |
call |
Matched call. |
This function is experimental; interface may change.
Ding, C.H.Q., Li, T., and Jordan, M.I. (2010). Convex and Semi-Nonnegative Matrix Factorizations. IEEE TPAMI, 32(1), 45-55.
Satoh, K. (2026). Signed-Bottleneck NMF-AE: Signed-Bottleneck 3-Layer NMF (research memo, 2026-04-18).
Ding, C. H. Q., Li, T., & Jordan, M. I. (2010). Convex and semi-nonnegative matrix factorizations. IEEE Transactions on Pattern Analysis and Machine Intelligence, 32(1), 45–55.
nmfae, predict.nmfae.signed,
summary.nmfae.signed, nmfae.signed.rename
set.seed(1) Y1 <- matrix(abs(rnorm(12)), 3, 4) Y2 <- matrix(abs(rnorm(20)), 5, 4) res <- nmfae.signed(Y1, Y2, rank = 2, rank.encoder = 2, maxit = 500) summary(res)set.seed(1) Y1 <- matrix(abs(rnorm(12)), 3, 4) Y2 <- matrix(abs(rnorm(20)), 5, 4) res <- nmfae.signed(Y1, Y2, rank = 2, rank.encoder = 2, maxit = 500) summary(res)
Element-wise k-fold cross-validation for nmfae.signed to
select the decoder / encoder ranks . Mirrors
nmfae.ecv but uses the weighted Signed-Bottleneck NMF-AE fit
path (Y1.weights): test-fold elements are zero-weighted during
fitting, and held-out MSE is computed on those elements.
nmfae.signed.ecv(Y1, Y2 = Y1, rank = 1:2, rank.encoder = NULL, ...)nmfae.signed.ecv(Y1, Y2 = Y1, rank = 1:2, rank.encoder = NULL, ...)
Y1 |
Output matrix (P1 x N). |
Y2 |
Input matrix (P2 x N). Default |
rank |
Integer vector of candidate Q values. Default |
rank.encoder |
Integer vector of candidate R values, or |
... |
Additional arguments:
|
An object of class c("nmfae.signed.ecv", "nmfae.ecv") with
objfunc (MSE per pair), sigma (RMSE), objfunc.fold
(per-fold MSE), folds, QR, paired.
This function is experimental. The interface may change in future versions.
Ding, C. H. Q., Li, T., & Jordan, M. I. (2010). Convex and semi-nonnegative matrix factorizations. IEEE Transactions on Pattern Analysis and Machine Intelligence, 32(1), 45–55.
Displays the factor blocks of a nmfae.signed fit as
side-by-side heatmaps. Non-negative blocks () use the white-orange-red palette; the signed combined
bottleneck is rendered with a diverging
blue-white-red palette so positive and negative weights are visually
distinguishable.
nmfae.signed.heatmap( x, Y1.label = NULL, X1.label = NULL, X2.label = NULL, Y2.label = NULL, palette.pos = NULL, palette.signed = NULL, show.C = TRUE, ... )nmfae.signed.heatmap( x, Y1.label = NULL, X1.label = NULL, X2.label = NULL, Y2.label = NULL, palette.pos = NULL, palette.signed = NULL, show.C = TRUE, ... )
x |
An object of class |
Y1.label |
Character vector for rows of |
X1.label |
Decoder basis labels. |
X2.label |
Encoder basis labels. |
Y2.label |
Input variable labels. |
palette.pos |
Palette for non-negative blocks. Default white-orange-red. |
palette.signed |
Palette for signed |
show.C |
Logical. If |
... |
Not used. |
Invisible NULL. Called for its side effect (plot).
This function is experimental. The interface may change in future versions.
Ding, C. H. Q., Li, T., & Jordan, M. I. (2010). Convex and semi-nonnegative matrix factorizations. IEEE Transactions on Pattern Analysis and Machine Intelligence, 32(1), 45–55.
set.seed(1) Y1 <- matrix(abs(rnorm(12)), 3, 4) Y2 <- matrix(abs(rnorm(20)), 5, 4) res <- nmfae.signed(Y1, Y2, rank = 2, rank.encoder = 2, maxit = 200) nmfae.signed.heatmap(res)set.seed(1) Y1 <- matrix(abs(rnorm(12)), 3, 4) Y2 <- matrix(abs(rnorm(20)), 5, 4) res <- nmfae.signed(Y1, Y2, rank = 2, rank.encoder = 2, maxit = 200) nmfae.signed.heatmap(res)
Post-estimation inference for the signed bottleneck
in the Signed-Bottleneck NMF-AE model
, conditional on
. Uses sandwich covariance and wild bootstrap
without the non-negativity projection that nmfae.inference
applies (because is unconstrained in sign here).
nmfae.signed.inference(object, Y1, Y2 = Y1, wild.bootstrap = TRUE, ...)nmfae.signed.inference(object, Y1, Y2 = Y1, wild.bootstrap = TRUE, ...)
object |
A fitted |
Y1 |
Output matrix used during fitting. |
Y2 |
Input matrix used during fitting. Default |
wild.bootstrap |
Logical. Default |
... |
Additional arguments:
|
An object of class c("nmfae.signed.inference",
"nmfae.inference", "nmfae.signed", "nmfae", "nmf") with added fields:
sigma2.used |
Estimated |
C.se, C.se.boot
|
Sandwich / bootstrap SEs for |
C.ci.lower, C.ci.upper
|
Bootstrap CIs. |
coefficients |
Data frame with Estimate, SE, BSE, z, p-value, CI. |
C.p.side |
P-value side used. |
This function is experimental. The interface may change in future versions.
Ding, C. H. Q., Li, T., & Jordan, M. I. (2010). Convex and semi-nonnegative matrix factorizations. IEEE Transactions on Pattern Analysis and Machine Intelligence, 32(1), 45–55.
Replaces the default "Dec1", "Dec2", ... (decoder / X1 columns
and Cp/Cn/C rows) and "Enc1", "Enc2", ... (encoder / X2 rows and
Cp/Cn/C columns) with user-supplied labels. Propagates to coefficients
tables if present (e.g., from nmfae.inference).
nmfae.signed.rename(x, X1.colnames = NULL, X2.rownames = NULL)nmfae.signed.rename(x, X1.colnames = NULL, X2.rownames = NULL)
x |
An |
X1.colnames |
Character vector of length Q for decoder labels. |
X2.rownames |
Character vector of length R for encoder labels. |
The renamed object (same class).
This function is experimental. The interface may change in future versions.
Ding, C. H. Q., Li, T., & Jordan, M. I. (2010). Convex and semi-nonnegative matrix factorizations. IEEE Transactions on Pattern Analysis and Machine Intelligence, 32(1), 45–55.
nmfkc fits a nonnegative matrix factorization with kernel covariates
under the tri-factorization model .
This function supports two major input modes:
Matrix Mode (Existing): nmfkc(Y=matrix, A=matrix, ...)
Formula Mode (New): nmfkc(formula=Y_vars ~ A_vars, data=df, rank=Q, ...)
The rank of the basis matrix can be specified using either the rank argument
(preferred for formula mode) or the hidden Q argument (for backward compatibility).
nmfkc( Y, A = NULL, rank = NULL, data, epsilon = 1e-04, maxit = 5000, verbose = TRUE, ... )nmfkc( Y, A = NULL, rank = NULL, data, epsilon = 1e-04, maxit = 5000, verbose = TRUE, ... )
Y |
Observation matrix (P x N), OR a formula object for Formula Mode.
In Formula Mode, use |
A |
Covariate matrix. Default is |
rank |
Integer. The rank of the basis matrix |
data |
Optional. A data frame from which variables in the formula should be taken. |
epsilon |
Positive convergence tolerance. |
maxit |
Maximum number of iterations. |
verbose |
Logical. If |
... |
Additional arguments passed for fine-tuning regularization, initialization, constraints,
and output control. This includes the backward-compatible arguments
|
A list with components:
call |
The matched call, as captured by |
dims |
A character string summarizing the matrix dimensions of the model. |
runtime |
A character string summarizing the computation time. |
X |
Basis matrix. Column normalization depends on |
B |
Coefficient matrix |
XB |
Fitted values for |
C |
Parameter matrix. |
B.prob |
Soft-clustering probabilities derived from columns of |
B.cluster |
Hard-clustering labels (argmax over |
X.prob |
Row-wise soft-clustering probabilities derived from |
X.cluster |
Hard-clustering labels (argmax over |
A.attr |
List of attributes of the input covariate matrix |
formula.meta |
If fitted via Formula Mode, a list with |
objfunc |
Final objective value. |
objfunc.iter |
Objective values by iteration. |
r.squared |
Coefficient of determination |
method |
Character string indicating the optimization method used ( |
n.missing |
Number of missing (or zero-weighted) elements in |
n.total |
Total number of elements in |
rank |
The rank |
sigma |
The residual standard error, representing the typical deviation of the observed values |
mae |
Mean Absolute Error between |
criterion |
A list of selection criteria, including |
Satoh, K. (2024). Applying Non-negative Matrix Factorization with Covariates to the Longitudinal Data as Growth Curve Model. arXiv:2403.05359. https://arxiv.org/abs/2403.05359
Satoh, K. (2025). Applying non-negative matrix factorization with covariates to multivariate time series data as a vector autoregression model. Japanese Journal of Statistics and Data Science. arXiv:2501.17446. doi:10.1007/s42081-025-00314-0
Satoh, K. (2025). Applying non-negative matrix factorization with covariates to label matrix for classification. arXiv:2510.10375. https://arxiv.org/abs/2510.10375
Ding, C., Li, T., Peng, W., & Park, H. (2006). Orthogonal Nonnegative Matrix Tri-Factorizations for Clustering. In Proc. 12th ACM SIGKDD (pp. 126–135). doi:10.1145/1150402.1150420
nmfkc.cv, nmfkc.rank, nmfkc.kernel, nmfkc.ar, predict.nmfkc
# Example 1. Matrix Mode (Existing) X <- cbind(c(1,0,1),c(0,1,0)) B <- cbind(c(1,0),c(0,1),c(1,1)) Y <- X %*% B rownames(Y) <- paste0("P",1:nrow(Y)) colnames(Y) <- paste0("N",1:ncol(Y)) print(X); print(B); print(Y) res <- nmfkc(Y,rank=2,epsilon=1e-6) res$X res$B # Example 2. Formula Mode set.seed(1) dummy_data <- data.frame(Y1=rpois(10,5), Y2=rpois(10,10), A1=abs(rnorm(10,5)), A2=abs(rnorm(10,3))) res_f <- nmfkc(Y1 + Y2 ~ A1 + A2, data=dummy_data, rank=2) # Example 3. Symmetric NMF (bi: Y ~ X X^T) S <- matrix(c(3,0,2, 0,3,1, 2,1,2), nrow=3) res_bi <- nmfkc(S, rank=2, Y.symmetric="bi") res_bi$X # basis matrix (no column normalization) res_bi$XB # reconstruction X %*% t(X) # Example 4. Symmetric NMF (tri: Y ~ X C X^T) res_tri <- nmfkc(S, rank=2, Y.symmetric="tri") res_tri$C # Q x Q cluster interaction matrix res_tri$XB # reconstruction X %*% C %*% t(X)# Example 1. Matrix Mode (Existing) X <- cbind(c(1,0,1),c(0,1,0)) B <- cbind(c(1,0),c(0,1),c(1,1)) Y <- X %*% B rownames(Y) <- paste0("P",1:nrow(Y)) colnames(Y) <- paste0("N",1:ncol(Y)) print(X); print(B); print(Y) res <- nmfkc(Y,rank=2,epsilon=1e-6) res$X res$B # Example 2. Formula Mode set.seed(1) dummy_data <- data.frame(Y1=rpois(10,5), Y2=rpois(10,10), A1=abs(rnorm(10,5)), A2=abs(rnorm(10,3))) res_f <- nmfkc(Y1 + Y2 ~ A1 + A2, data=dummy_data, rank=2) # Example 3. Symmetric NMF (bi: Y ~ X X^T) S <- matrix(c(3,0,2, 0,3,1, 2,1,2), nrow=3) res_bi <- nmfkc(S, rank=2, Y.symmetric="bi") res_bi$X # basis matrix (no column normalization) res_bi$XB # reconstruction X %*% t(X) # Example 4. Symmetric NMF (tri: Y ~ X C X^T) res_tri <- nmfkc(S, rank=2, Y.symmetric="tri") res_tri$C # Q x Q cluster interaction matrix res_tri$XB # reconstruction X %*% C %*% t(X)
nmfkc.ar generates the observation matrix and covariate matrix
corresponding to a specified autoregressive lag order.
If the input Y is a ts object, its time properties are preserved
in the "tsp_info" attribute, adjusted for the lag.
Additionally, the column names of Y and A are set to the corresponding time points.
nmfkc.ar(Y, degree = 1, intercept = TRUE)nmfkc.ar(Y, degree = 1, intercept = TRUE)
Y |
An observation matrix (P x N) or a |
degree |
The lag order of the autoregressive model. The default is 1. |
intercept |
Logical. If TRUE (default), an intercept term is added to the covariate matrix. |
A list containing:
Y |
Observation matrix (P x N_A) used for NMF. Includes adjusted |
A |
Covariate matrix (R x N_A) constructed according to the specified lag order. Includes adjusted |
A.columns |
Index matrix used to generate |
degree.max |
Maximum lag order. |
Satoh, K. (2025). Applying non-negative matrix factorization with covariates to multivariate time series data as a vector autoregression model. Japanese Journal of Statistics and Data Science. arXiv:2501.17446. doi:10.1007/s42081-025-00314-0
nmfkc, nmfkc.ar.degree.cv, nmfkc.ar.stationarity, nmfkc.ar.DOT
# Example using AirPassengers (ts object) d <- AirPassengers ar_data <- nmfkc.ar(d, degree = 2) dim(ar_data$Y) dim(ar_data$A) # Example using matrix input Y <- matrix(1:20, nrow = 2) ar_data <- nmfkc.ar(Y, degree = 1) ar_data$degree.max# Example using AirPassengers (ts object) d <- AirPassengers ar_data <- nmfkc.ar(d, degree = 2) dim(ar_data$Y) dim(ar_data$A) # Example using matrix input Y <- matrix(1:20, nrow = 2) ar_data <- nmfkc.ar(Y, degree = 1) ar_data$degree.max
nmfkc.ar.degree.cv selects the optimal lag order for an autoregressive model
by applying cross-validation over candidate degrees.
This function accepts both standard matrices (Variables x Time) and ts objects
(Time x Variables). ts objects are automatically transposed internally.
nmfkc.ar.degree.cv( Y, rank = 1, degree = 1:2, intercept = TRUE, plot = TRUE, ... )nmfkc.ar.degree.cv( Y, rank = 1, degree = 1:2, intercept = TRUE, plot = TRUE, ... )
Y |
Observation matrix |
rank |
Rank of the basis matrix. For backward compatibility,
|
degree |
A vector of candidate lag orders to be evaluated. |
intercept |
Logical. If TRUE (default), an intercept is added to the covariate matrix. |
plot |
Logical. If TRUE (default), a plot of the objective function values is drawn. |
... |
Additional arguments passed to |
A list with components:
degree |
The lag order that minimizes the cross-validation objective function. |
degree.max |
Maximum recommended lag order, computed as |
objfunc |
Objective function values for each candidate lag order. |
# Example using ts object directly d <- AirPassengers # Selection of degree (using ts object) # Note: Y is automatically transposed if it is a ts object nmfkc.ar.degree.cv(Y=d, rank=1, degree=11:14)# Example using ts object directly d <- AirPassengers # Selection of degree (using ts object) # Note: Y is automatically transposed if it is a ts object nmfkc.ar.degree.cv(Y=d, rank=1, degree=11:14)
Produces a Graphviz DOT script for visualizing autoregressive
NMF-with-covariates models constructed via nmfkc.ar + nmfkc.
The diagram displays three types of directed relationships:
Lagged predictors: ,
Current latent factors: ,
Optional intercept effects: Const -> X.
Importantly, no direct edges from lagged variables to current outputs
() are drawn, in accordance with the NMF-AR
formulation.
Each block of lagged variables is displayed in its own DOT subgraph (e.g., “T-1”, “T-2”, ...), while latent factor nodes and current-time outputs are arranged in separate clusters.
nmfkc.ar.DOT( result, degree = 1, intercept = any(colnames(result$C) == "(Intercept)"), threshold = 0.1, rankdir = "RL", fill = TRUE, weight_scale_xy = 5, weight_scale_lag = 5, weight_scale_int = 3, hide.isolated = TRUE )nmfkc.ar.DOT( result, degree = 1, intercept = any(colnames(result$C) == "(Intercept)"), threshold = 0.1, rankdir = "RL", fill = TRUE, weight_scale_xy = 5, weight_scale_lag = 5, weight_scale_int = 3, hide.isolated = TRUE )
result |
A fitted |
degree |
Maximum AR lag to visualize. |
intercept |
Logical; if |
threshold |
Minimum coefficient magnitude required to draw an edge. |
rankdir |
Graphviz rank direction (e.g., |
fill |
Logical; whether nodes are filled with color. |
weight_scale_xy |
Scaling factor for edges |
weight_scale_lag |
Scaling factor for lagged edges |
weight_scale_int |
Scaling factor for intercept edges. |
hide.isolated |
Logical. If |
A character string representing a Graphviz DOT file.
nmfkc.ar, nmfkc, plot.nmfkc.DOT
d <- AirPassengers ar_data <- nmfkc.ar(d, degree = 2) result <- nmfkc(ar_data$Y, ar_data$A, rank = 1) dot <- nmfkc.ar.DOT(result, degree = 2) cat(dot)d <- AirPassengers ar_data <- nmfkc.ar(d, degree = 2) result <- nmfkc(ar_data$Y, ar_data$A, rank = 1) dot <- nmfkc.ar.DOT(result, degree = 2) cat(dot)
nmfkc.ar.predict computes multi-step-ahead forecasts for a fitted NMF-VAR model
using recursive forecasting.
If the fitted model contains time series property information (from nmfkc.ar),
the forecasted values will have appropriate time-based column names.
nmfkc.ar.predict(x, Y, degree = NULL, n.ahead = 1)nmfkc.ar.predict(x, Y, degree = NULL, n.ahead = 1)
x |
An object of class |
Y |
The historical observation matrix used for fitting (or at least the last |
degree |
Optional integer. Lag order (D). If |
n.ahead |
Integer (>=1). Number of steps ahead to forecast. |
A list with components:
pred |
A |
time |
A numeric vector of future time points corresponding to the columns of |
# Forecast AirPassengers d <- AirPassengers ar_data <- nmfkc.ar(d, degree = 2) result <- nmfkc(ar_data$Y, ar_data$A, rank = 1) pred <- nmfkc.ar.predict(result, Y = matrix(d, nrow = 1), degree = 2, n.ahead = 3) pred$pred# Forecast AirPassengers d <- AirPassengers ar_data <- nmfkc.ar(d, degree = 2) result <- nmfkc(ar_data$Y, ar_data$A, rank = 1) pred <- nmfkc.ar.predict(result, Y = matrix(d, nrow = 1), degree = 2, n.ahead = 3) pred$pred
nmfkc.ar.stationarity assesses the dynamic stability of a VAR model
by computing the spectral radius of its companion matrix.
It returns both the spectral radius and a logical indicator of stationarity.
nmfkc.ar.stationarity(x)nmfkc.ar.stationarity(x)
x |
The return value of |
A list with components:
spectral.radius |
Numeric. The spectral radius of the companion matrix. A value less than 1 indicates stationarity. |
stationary |
Logical. |
# Check stationarity of fitted AR model d <- AirPassengers ar_data <- nmfkc.ar(d, degree = 2) result <- nmfkc(ar_data$Y, ar_data$A, rank = 1) nmfkc.ar.stationarity(result)# Check stationarity of fitted AR model d <- AirPassengers ar_data <- nmfkc.ar(d, degree = 2) result <- nmfkc(ar_data$Y, ar_data$A, rank = 1) nmfkc.ar.stationarity(result)
nmfkc.class converts a categorical or factor vector into a class matrix
(one-hot encoded representation), where each row corresponds to a category
and each column corresponds to an observation.
nmfkc.class(x)nmfkc.class(x)
x |
A categorical vector or a factor. |
A binary matrix with one row per unique category and one column per observation. Each column has exactly one entry equal to 1, indicating the category of the observation.
# Example. Y <- nmfkc.class(iris$Species) Y[,1:6]# Example. Y <- nmfkc.class(iris$Species) Y[,1:6]
nmfkc.criterion computes information criteria (ICp, AIC, BIC),
clustering quality measures (silhouette, CPCC, dist.cor), and
soft-clustering statistics (B.prob entropy, max, sd) from a fitted
nmfkc model.
This function can be called on a model that was fitted with
detail = "fast" or detail = "minimal" to compute the
full set of criteria afterwards.
nmfkc.criterion(object, Y, detail = c("full", "fast", "minimal"), ...)nmfkc.criterion(object, Y, detail = c("full", "fast", "minimal"), ...)
object |
An object of class |
Y |
The original observation matrix (P x N) used for fitting. |
detail |
Character string controlling the level of computation:
|
... |
Additional arguments: |
A list with components:
R-squared between Y and XB.
Residual standard deviation.
Mean absolute error.
Column-normalized coefficient matrix (soft-clustering probabilities).
Hard clustering labels (argmax of B.prob per column).
Row-normalized basis matrix.
Hard clustering labels per row of X.
Named list: ICp, ICp1, ICp2, ICp3, AIC, BIC, B.prob.sd.min, B.prob.max.mean, B.prob.entropy.mean, silhouette, CPCC, dist.cor.
Y <- t(iris[, -5]) res <- nmfkc(Y, rank = 3, detail = "fast") crit <- nmfkc.criterion(res, Y) crit$criterion$silhouetteY <- t(iris[, -5]) res <- nmfkc(Y, rank = 3, detail = "fast") crit <- nmfkc.criterion(res, Y) crit$criterion$silhouette
nmfkc.cv performs k-fold cross-validation for the tri-factorization model
, where
is the observation matrix,
is the covariate (or kernel) matrix,
is the basis matrix,
is the parameter matrix, and
is the coefficient matrix ().
Given (and optionally ), and are fitted on each
training split and predictive performance is evaluated on the held-out split.
nmfkc.cv(Y, A = NULL, rank = 2, data, ...)nmfkc.cv(Y, A = NULL, rank = 2, data, ...)
Y |
Observation matrix, or a formula (see |
A |
Covariate matrix. If |
rank |
Rank of the basis matrix |
data |
A data frame (required when |
... |
Additional arguments controlling CV and the internal
|
A list with components:
objfuncMean loss per valid entry over all folds (MSE for method="EU").
sigmaResidual standard error (RMSE). Available only if method="EU"; on the same scale as Y.
objfunc.blockLoss for each fold.
blockVector of fold indices (1, …, div) assigned to each column of .
nmfkc, nmfkc.kernel.beta.cv, nmfkc.ar.degree.cv
# Example 1 (with explicit covariates): Y <- matrix(cars$dist, nrow = 1) A <- rbind(1, cars$speed) res <- nmfkc.cv(Y, A, rank = 1) res$objfunc # Example 2 (kernel A and beta sweep): Y <- matrix(cars$dist, nrow = 1) U <- matrix(c(5, 10, 15, 20, 25), nrow = 1) V <- matrix(cars$speed, nrow = 1) betas <- 25:35/1000 obj <- numeric(length(betas)) for (i in seq_along(betas)) { A <- nmfkc.kernel(U, V, beta = betas[i]) obj[i] <- nmfkc.cv(Y, A, rank = 1, nfolds = 10)$objfunc } betas[which.min(obj)]# Example 1 (with explicit covariates): Y <- matrix(cars$dist, nrow = 1) A <- rbind(1, cars$speed) res <- nmfkc.cv(Y, A, rank = 1) res$objfunc # Example 2 (kernel A and beta sweep): Y <- matrix(cars$dist, nrow = 1) U <- matrix(c(5, 10, 15, 20, 25), nrow = 1) V <- matrix(cars$speed, nrow = 1) betas <- 25:35/1000 obj <- numeric(length(betas)) for (i in seq_along(betas)) { A <- nmfkc.kernel(U, V, beta = betas[i]) obj[i] <- nmfkc.cv(Y, A, rank = 1, nfolds = 10)$objfunc } betas[which.min(obj)]
nmfkc.denormalize rescales a matrix with values in back to its
original scale using the column-wise minima and maxima of a reference matrix.
nmfkc.denormalize(x, ref = x)nmfkc.denormalize(x, ref = x)
x |
A numeric matrix (or vector) with values in |
ref |
A reference matrix used to obtain the original column-wise minima
and maxima. Must have the same number of columns as |
A numeric matrix with values transformed back to the original scale.
x <- nmfkc.normalize(iris[, -5]) x_recovered <- nmfkc.denormalize(x, iris[, -5]) apply(x_recovered - iris[, -5], 2, max)x <- nmfkc.normalize(iris[, -5]) x_recovered <- nmfkc.denormalize(x, iris[, -5]) apply(x_recovered - iris[, -5], 2, max)
Produces a Graphviz DOT script visualizing the structure of an NMF model
() or its simplified forms.
Supported visualization types:
"YX" — Standard NMF view: latent factors map to observations .
"YA" — Direct regression view: covariates map directly to
using the combined coefficient matrix .
"YXA" — Full tri-factorization: .
Edge widths are scaled by coefficient magnitude, and nodes with no edges above the threshold are omitted from the visualization.
nmfkc.DOT( result, type = c("YX", "YA", "YXA"), threshold = 0.01, sig.level = 0.1, rankdir = "LR", fill = TRUE, weight_scale = 5, weight_scale_ax = weight_scale, weight_scale_xy = weight_scale, weight_scale_ay = weight_scale, Y.label = NULL, X.label = NULL, A.label = NULL, Y.title = "Observation (Y)", X.title = "Basis (X)", A.title = "Covariates (A)", hide.isolated = TRUE )nmfkc.DOT( result, type = c("YX", "YA", "YXA"), threshold = 0.01, sig.level = 0.1, rankdir = "LR", fill = TRUE, weight_scale = 5, weight_scale_ax = weight_scale, weight_scale_xy = weight_scale, weight_scale_ay = weight_scale, Y.label = NULL, X.label = NULL, A.label = NULL, Y.title = "Observation (Y)", X.title = "Basis (X)", A.title = "Covariates (A)", hide.isolated = TRUE )
result |
The return value from |
type |
Character string specifying the visualization style:
one of |
threshold |
Minimum coefficient magnitude to display an edge. |
sig.level |
Significance level for filtering C edges when inference
results are available (i.e., |
rankdir |
Graphviz rank direction (e.g., |
fill |
Logical; whether nodes should be drawn with filled shapes. |
weight_scale |
Base scaling factor for edge widths. |
weight_scale_ax |
Scaling factor for edges |
weight_scale_xy |
Scaling factor for edges |
weight_scale_ay |
Scaling factor for edges |
Y.label |
Optional character vector for labels of Y nodes. |
X.label |
Optional character vector for labels of X (latent factor) nodes. |
A.label |
Optional character vector for labels of A (covariate) nodes. |
Y.title |
Cluster title for Y nodes. |
X.title |
Cluster title for X nodes. |
A.title |
Cluster title for A nodes. |
hide.isolated |
Logical. If |
A character string representing a Graphviz DOT script.
nmfkc, nmfae.DOT, nmf.sem.DOT,
nmfkc.ar.DOT, plot.nmfkc.DOT
Y <- matrix(cars$dist, nrow = 1) A <- rbind(1, cars$speed) result <- nmfkc(Y, A, rank = 1) dot <- nmfkc.DOT(result) cat(dot)Y <- matrix(cars$dist, nrow = 1) A <- rbind(1, cars$speed) result <- nmfkc(Y, A, rank = 1) dot <- nmfkc.DOT(result) cat(dot)
nmfkc.ecv performs k-fold cross-validation by randomly holding out
individual elements of the data matrix (element-wise), assigning them a
weight of 0 via Y.weights, and evaluating the reconstruction error on
those held-out elements.
This method (also known as Wold's CV) is theoretically robust for determining
the optimal rank (Q) in NMF. This function supports vector input for Q,
allowing simultaneous evaluation of multiple ranks on the same folds.
When Y.symmetric = "bi" or "tri" is passed via ...,
fold creation uses only the upper triangle (including the diagonal) to
prevent information leakage through the symmetric entries .
nmfkc.ecv(Y, A = NULL, rank = 1:3, data, ...)nmfkc.ecv(Y, A = NULL, rank = 1:3, data, ...)
Y |
Observation matrix, or a formula (see |
A |
Covariate matrix. Ignored when |
rank |
Vector of ranks to evaluate (e.g., 1:5). For backward compatibility,
|
data |
A data frame (required when |
... |
Additional arguments passed to |
A list with components:
objfunc |
Numeric vector containing the Mean Squared Error (MSE) for each Q. |
sigma |
Numeric vector containing the Residual Standard Error (RMSE) for each Q. Only available if method="EU". |
objfunc.fold |
List of length equal to Q vector. Each element contains the MSE values for the k folds. |
folds |
A list of length |
# Element-wise CV to select rank Y <- t(iris[1:30, 1:4]) res <- nmfkc.ecv(Y, rank = 1:2, nfolds = 3) res$objfunc# Element-wise CV to select rank Y <- t(iris[1:30, 1:4]) res <- nmfkc.ecv(Y, rank = 1:2, nfolds = 3) res$objfunc
nmfkc.inference performs statistical inference on the parameter matrix
() from a fitted nmfkc model, conditional on
the estimated basis matrix .
Under the working model where
,
inference is conducted via sandwich covariance estimation and
one-step wild bootstrap with non-negative projection.
nmfkc.inference(object, Y, A = NULL, wild.bootstrap = TRUE, ...)nmfkc.inference(object, Y, A = NULL, wild.bootstrap = TRUE, ...)
object |
An object of class |
Y |
Observation matrix (P x N). Must match the data used in |
A |
Covariate matrix (K x N). Default is |
wild.bootstrap |
Logical. If |
... |
Additional arguments:
|
An object of class c("nmfkc.inference", "nmfkc"), inheriting all
components from the input object, with additional inference components:
sigma2.used |
Estimated |
C.se |
Sandwich standard errors for |
C.se.boot |
Bootstrap standard errors for |
C.ci.lower |
Lower CI bounds for |
C.ci.upper |
Upper CI bounds for |
coefficients |
Data frame with Estimate, SE, BSE, z, p-value for each element of |
C.p.side |
P-value type used. |
Satoh, K. (2026). Wild Bootstrap Inference for Non-Negative Matrix Factorization with Random Effects. arXiv:2603.01468. https://arxiv.org/abs/2603.01468
nmfkc, summary.nmfkc.inference
Y <- matrix(cars$dist, nrow = 1) A <- rbind(intercept = 1, speed = cars$speed) result <- nmfkc(Y, A, rank = 1) result2 <- nmfkc.inference(result, Y, A) summary(result2)Y <- matrix(cars$dist, nrow = 1) A <- rbind(intercept = 1, speed = cars$speed) result <- nmfkc(Y, A, rank = 1) result2 <- nmfkc.inference(result, Y, A) summary(result2)
nmfkc.kernel constructs a kernel matrix from covariate matrices.
It supports Gaussian, Exponential, Periodic, Linear, Normalized Linear, and Polynomial kernels.
nmfkc.kernel( U, V = NULL, kernel = c("Gaussian", "Exponential", "Periodic", "Linear", "NormalizedLinear", "Polynomial"), ... )nmfkc.kernel( U, V = NULL, kernel = c("Gaussian", "Exponential", "Periodic", "Linear", "NormalizedLinear", "Polynomial"), ... )
U |
Covariate matrix |
V |
Covariate matrix |
kernel |
Kernel function to use. Default is |
... |
Additional arguments passed to the specific kernel function (e.g., |
Kernel matrix .
Satoh, K. (2024). Applying Non-negative Matrix Factorization with Covariates to the Longitudinal Data as Growth Curve Model. arXiv preprint arXiv:2403.05359. https://arxiv.org/abs/2403.05359
nmfkc.kernel.gaussian, nmfkc.cv
# Example. Y <- matrix(cars$dist,nrow=1) U <- matrix(c(5,10,15,20,25),nrow=1) V <- matrix(cars$speed,nrow=1) A <- nmfkc.kernel(U,V,beta=28/1000) dim(A) result <- nmfkc(Y,A,rank=1) plot(as.vector(V),as.vector(Y)) lines(as.vector(V),as.vector(result$XB),col=2,lwd=2)# Example. Y <- matrix(cars$dist,nrow=1) U <- matrix(c(5,10,15,20,25),nrow=1) V <- matrix(cars$speed,nrow=1) A <- nmfkc.kernel(U,V,beta=28/1000) dim(A) result <- nmfkc(Y,A,rank=1) plot(as.vector(V),as.vector(Y)) lines(as.vector(V),as.vector(result$XB),col=2,lwd=2)
nmfkc.kernel.beta.cv selects the optimal beta parameter of the kernel function by applying cross-validation over a set of candidate values.
nmfkc.kernel.beta.cv(Y, rank = 2, U, V = NULL, beta = NULL, plot = TRUE, ...)nmfkc.kernel.beta.cv(Y, rank = 2, U, V = NULL, beta = NULL, plot = TRUE, ...)
Y |
Observation matrix |
rank |
Rank of the basis matrix. |
U |
Covariate matrix |
V |
Covariate matrix |
beta |
A numeric vector of candidate kernel parameters to evaluate via cross-validation. |
plot |
Logical. If TRUE (default), plots the objective function values for each candidate |
... |
Additional arguments passed to |
A list with components:
beta |
The beta value that minimizes the cross-validation objective function. |
objfunc |
Objective function values for each candidate |
nmfkc.kernel.gaussian, nmfkc.kernel.beta.nearest.med,
nmfkc.kernel
# Example. Y <- matrix(cars$dist,nrow=1) U <- matrix(c(5,10,15,20,25),nrow=1) V <- matrix(cars$speed,nrow=1) nmfkc.kernel.beta.cv(Y,rank=1,U,V,beta=25:30/1000) A <- nmfkc.kernel(U,V,beta=28/1000) result <- nmfkc(Y,A,rank=1) plot(as.vector(V),as.vector(Y)) lines(as.vector(V),as.vector(result$XB),col=2,lwd=2)# Example. Y <- matrix(cars$dist,nrow=1) U <- matrix(c(5,10,15,20,25),nrow=1) V <- matrix(cars$speed,nrow=1) nmfkc.kernel.beta.cv(Y,rank=1,U,V,beta=25:30/1000) A <- nmfkc.kernel(U,V,beta=28/1000) result <- nmfkc(Y,A,rank=1) plot(as.vector(V),as.vector(Y)) lines(as.vector(V),as.vector(result$XB),col=2,lwd=2)
Computes a data-driven reference scale for the Gaussian/RBF kernel from covariates
using a robust "median nearest-neighbor (or nearest-landmark) distance" heuristic,
and returns the corresponding kernel parameter .
The Gaussian/RBF kernel is assumed to be written in the form
hence . This function first estimates a typical distance
scale by the median of distances, then sets .
If Uk is NULL, is estimated as the median of
nearest-neighbor distances within U (excluding self-distance).
If Uk is provided, is estimated as the median of
nearest-landmark distances from each sample in U to its closest landmark in Uk.
To control memory usage for large N (and M), distances are computed in blocks.
Optionally, columns of U can be randomly subsampled via sample.size to reduce cost.
nmfkc.kernel.beta.nearest.med( U, Uk = NULL, block.size = 1000, block.size.Uk = 2000, sample.size = NULL, ... )nmfkc.kernel.beta.nearest.med( U, Uk = NULL, block.size = 1000, block.size.Uk = 2000, sample.size = NULL, ... )
U |
A numeric matrix of covariates ( |
Uk |
An optional numeric matrix of landmarks ( |
block.size |
Integer. Number of columns of |
block.size.Uk |
Integer. Number of columns of |
sample.size |
Integer or |
... |
Additional arguments. Hidden option |
Candidate grid:
Along with beta, the function returns beta_candidates, a
logarithmic grid suitable for cross-validation. The grid is symmetric on
the bandwidth scale around :
and since , this corresponds to
.
The grid of values can be customized through the hidden argument
candidates (passed via ...):
"7points" (default):
(7 candidates spanning one decade, matches the grid used in the
RFF-NMF research memo).
"4points": yielding
(the legacy short grid).
A numeric vector: user-specified values. The grid returned
is .
Prior to version 0.6.8, the grid depended on whether Uk was
supplied (4 candidates for Uk = NULL, 7 for supplied Uk).
The current implementation unifies both branches via candidates.
Notes:
When Uk is identical to U, the function detects this case and excludes
self-distances (distance 0) to avoid .
sample.size performs random subsampling without setting a seed. For reproducible
results, set set.seed() before calling this function.
A list with elements:
beta: Estimated kernel parameter .
beta_candidates: Numeric vector of candidate values (logarithmic grid)
intended for cross-validation.
dist_median: The estimated distance scale (median of nearest-neighbor
or nearest-landmark distances).
block.size.used: The effective block size(s) used. Either a scalar (no Uk) or
a named vector c(U=..., Uk=...) when Uk is provided.
sample.size.used: The number of columns of U actually used (after subsampling).
uk_is_u: Logical flag indicating whether Uk was detected as identical to U
(only returned when Uk is provided).
nmfkc.kernel.gaussian, nmfkc.kernel.beta.cv
# Basic (nearest-neighbor within U) U <- matrix(runif(20), nrow = 2) beta_info <- nmfkc.kernel.beta.nearest.med(U) beta0 <- beta_info$beta betas <- beta_info$beta_candidates # With landmarks (nearest-landmark distances) Uk <- matrix(runif(10), nrow = 2) beta_info2 <- nmfkc.kernel.beta.nearest.med(U, Uk)# Basic (nearest-neighbor within U) U <- matrix(runif(20), nrow = 2) beta_info <- nmfkc.kernel.beta.nearest.med(U) beta0 <- beta_info$beta betas <- beta_info$beta_candidates # With landmarks (nearest-landmark distances) Uk <- matrix(runif(10), nrow = 2) beta_info2 <- nmfkc.kernel.beta.nearest.med(U, Uk)
nmfkc.kernel.gaussian constructs a Gaussian (RBF) kernel matrix from covariate matrices.
The kernel is defined as .
When V contains NA values, two methods are available via na.method:
"pds"Partial Distance Strategy. Computes the kernel using only observed (non-NA) rows,
with beta adjusted by where is the total number of rows
and is the number of observed rows.
"egk"Expected Gaussian Kernel (Mesquita et al., 2019). Uses a Gaussian Mixture Model (GMM)
to estimate the conditional distribution of missing values given observed values,
then computes the expected kernel value via a Gamma approximation.
Requires gmm.means, gmm.sigmas, and gmm.weights passed through ....
nmfkc.kernel.gaussian( U, V = NULL, beta = 0.5, na.method = c("pds", "egk"), ... )nmfkc.kernel.gaussian( U, V = NULL, beta = 0.5, na.method = c("pds", "egk"), ... )
U |
Covariate matrix |
V |
Covariate matrix |
beta |
Bandwidth parameter for the Gaussian kernel. Default is |
na.method |
Method for handling |
... |
Additional arguments for EGK method:
|
Kernel matrix .
Mesquita, D., Gomes, J. P., & Rodrigues, L. R. (2019). Gaussian kernels for incomplete data. Applied Soft Computing, 77, 356–365.
nmfkc.kernel, nmfkc.kernel.beta.cv, nmfkc.kernel.beta.nearest.med
U <- matrix(c(5,10,15,20,25),nrow=1) V <- matrix(1:25,nrow=1) A <- nmfkc.kernel.gaussian(U,V,beta=28/1000) dim(A) # PDS example: V with NA in first row U2 <- matrix(rnorm(20), nrow=2) V2 <- matrix(rnorm(10), nrow=2) V2[1, c(2,4)] <- NA A2 <- nmfkc.kernel.gaussian(U2, V2, beta=0.5, na.method="pds")U <- matrix(c(5,10,15,20,25),nrow=1) V <- matrix(1:25,nrow=1) A <- nmfkc.kernel.gaussian(U,V,beta=28/1000) dim(A) # PDS example: V with NA in first row U2 <- matrix(rnorm(20), nrow=2) V2 <- matrix(rnorm(10), nrow=2) V2[1, c(2,4)] <- NA A2 <- nmfkc.kernel.gaussian(U2, V2, beta=0.5, na.method="pds")
Single entry point for symmetric NMF of network data with correct
multiplicative updates. Three model types are supported via type:
tri (type="tri", default):
with (both non-negative;
symmetric by design). Uses Frobenius-full bilateral gradient.
bi (type="bi"):
( fixed to ),
cube-root damping (He et al. 2011).
signed (type="signed"):
with and signed
. Preserves the soft-clustering interpretation
of while allowing negative off-diagonals of
(inter-cluster repulsion).
Non-negative adjacency matrix assumption. All three types
assume (a non-negative adjacency/affinity matrix).
The qualifier “signed” in type = "signed" refers to the
middle coefficient , not to itself. The underlying
Ding, Li & Jordan (2010) sign-splitting updates require
to guarantee monotone descent; supplying a signed triggers an
error. For a signed data matrix, see nmfkc.signed.
nmfkc.net( Y, rank = 2, type = c("tri", "bi", "signed"), epsilon = 1e-04, maxit = 5000, verbose = FALSE, ... )nmfkc.net( Y, rank = 2, type = c("tri", "bi", "signed"), epsilon = 1e-04, maxit = 5000, verbose = FALSE, ... )
Y |
Symmetric (N x N) non-negative adjacency matrix.
|
rank |
Integer Q. |
type |
|
epsilon, maxit, verbose
|
Standard. |
... |
Hidden options:
When Multi-start recommendation. For |
Object of class c("nmfkc.net.<type>", "nmfkc.net", "nmfkc").
For type = "signed" the return also carries $Cp, $Cn.
This function is experimental. The interface may change in future versions; details are to be described in an upcoming paper.
Creates a Graphviz DOT script that visualizes the two-layer structure
of a symmetric NMF model ().
The resulting diagram displays:
outer nodes: the original network nodes (rows/columns of Y),
inner nodes: the latent basis/group nodes (columns of X),
directed edges from basis to node: membership weights from X,
undirected edges between basis nodes: inter-group interactions from C matrix (for tri-symmetric models only).
nmfkc.net.DOT( result, threshold = 0.01, sig.level = 0.1, weight_scale = 5, weight_scale_xy = 1, weight_scale_xx = weight_scale, rankdir = "TB", fill = TRUE, hide.isolated = TRUE, Y.label = NULL, X.label = NULL, Y.title = "Nodes (Y)", X.title = "Basis (X)", show.theta = NULL, signed = inherits(result, "nmfkc.net.signed"), cluster.box = c("none", "normal", "faint", "invisible"), layout = c("fdp", "dot", "neato", "circo", "twopi"), X.color = NULL, Y.cluster = c("soft", "hard") )nmfkc.net.DOT( result, threshold = 0.01, sig.level = 0.1, weight_scale = 5, weight_scale_xy = 1, weight_scale_xx = weight_scale, rankdir = "TB", fill = TRUE, hide.isolated = TRUE, Y.label = NULL, X.label = NULL, Y.title = "Nodes (Y)", X.title = "Basis (X)", show.theta = NULL, signed = inherits(result, "nmfkc.net.signed"), cluster.box = c("none", "normal", "faint", "invisible"), layout = c("fdp", "dot", "neato", "circo", "twopi"), X.color = NULL, Y.cluster = c("soft", "hard") )
result |
A list returned by |
threshold |
Minimum coefficient value to display an edge. |
sig.level |
Significance level for filtering C edges (if inference
results are present). Set to |
weight_scale |
Base scaling factor for edge widths. |
weight_scale_xy |
Scaling factor for X edges (basis -> node). |
weight_scale_xx |
Scaling factor for C edges (basis <-> basis). |
rankdir |
Graphviz rank direction ( |
fill |
Logical; whether nodes are filled with color. |
hide.isolated |
Logical; if TRUE, omit outer nodes with no X edge above threshold. |
Y.label |
Character vector of labels for outer nodes. |
X.label |
Character vector of labels for basis nodes. |
Y.title |
Cluster title for outer nodes. |
X.title |
Cluster title for basis nodes. |
show.theta |
Logical or NULL. Whether to draw C edges between basis nodes. NULL = auto-detect (TRUE for tri, FALSE for bi). |
signed |
Logical. If |
cluster.box |
Style of cluster box: |
layout |
Graphviz layout engine: |
X.color |
Color palette for basis nodes (length Q). |
Y.cluster |
Coloring mode for outer nodes: |
A character string of class c("nmfkc.net.DOT", "nmfkc.DOT")
representing a valid Graphviz DOT script.
Use plot() to render (requires DiagrammeR).
This function is experimental. The interface may change in future versions; details are to be described in an upcoming paper.
nmfkc.net.inference, nmfkc.DOT,
plot.nmfkc.DOT
library(nmfkc) Y <- matrix(c(0,1,1,0,0,0, 1,0,1,0,0,0, 1,1,0,1,0,0, 0,0,1,0,1,1, 0,0,0,1,0,1, 0,0,0,1,1,0), 6, 6) res <- nmfkc.net(Y, rank = 2, type = "tri", nstart = 20) dot <- nmfkc.net.DOT(res) plot(dot)library(nmfkc) Y <- matrix(c(0,1,1,0,0,0, 1,0,1,0,0,0, 1,1,0,1,0,0, 0,0,1,0,1,1, 0,0,0,1,0,1, 0,0,0,1,1,0), 6, 6) res <- nmfkc.net(Y, rank = 2, type = "tri", nstart = 20) dot <- nmfkc.net.DOT(res) plot(dot)
k-fold CV with folds taken over the upper triangle of the
symmetric (mirrored to the lower triangle) to prevent information
leakage through symmetry. A single entry point covers all three symmetric
NMF variants; type selects the fitting function:
nmfkc.net.ecv(Y, rank = 1:3, type = c("tri", "bi", "signed"), ...)nmfkc.net.ecv(Y, rank = 1:3, type = c("tri", "bi", "signed"), ...)
Y |
Symmetric N x N non-negative matrix. |
rank |
Integer vector of ranks to evaluate. Default |
type |
Model type: |
... |
Passed to the underlying fitter; also accepts |
A list with objfunc, sigma, objfunc.fold,
folds, Q.grid, type.
This function is experimental. The interface may change in future versions; details are to be described in an upcoming paper.
Performs statistical inference on the parameter matrix of a
symmetric NMF model ().
This is a wrapper around nmfkc.inference that automatically
sets the covariate matrix to , which is the defining
property of symmetric NMF.
nmfkc.net.inference(object, Y, wild.bootstrap = TRUE, ...)nmfkc.net.inference(object, Y, wild.bootstrap = TRUE, ...)
object |
A fitted model returned by |
Y |
The original symmetric matrix (P x P). |
wild.bootstrap |
Logical; if TRUE (default), perform wild bootstrap inference for the C matrix. |
... |
Additional arguments passed to |
The object augmented with inference fields
(same as nmfkc.inference), with class
c("nmfkc.net.inference", "nmfkc.inference", "nmf.inference", "nmfkc", "nmf").
This function is experimental. The interface may change in future versions; details are to be described in an upcoming paper.
nmfkc.inference, nmfkc.net.DOT,
summary.nmfkc.net.inference
library(nmfkc) Y <- matrix(c(0,1,1,0,0,0, 1,0,1,0,0,0, 1,1,0,1,0,0, 0,0,1,0,1,1, 0,0,0,1,0,1, 0,0,0,1,1,0), 6, 6) res <- nmfkc.net(Y, rank = 2, type = "tri", nstart = 20) res_inf <- nmfkc.net.inference(res, Y) summary(res_inf)library(nmfkc) Y <- matrix(c(0,1,1,0,0,0, 1,0,1,0,0,0, 1,1,0,1,0,0, 0,0,1,0,1,1, 0,0,0,1,0,1, 0,0,0,1,1,0), 6, 6) res <- nmfkc.net(Y, rank = 2, type = "tri", nstart = 20) res_inf <- nmfkc.net.inference(res, Y) summary(res_inf)
nmfkc.normalize rescales the values of a matrix to lie between 0 and 1
using the column-wise minimum and maximum values of a reference matrix.
nmfkc.normalize(x, ref = x)nmfkc.normalize(x, ref = x)
x |
A numeric matrix (or vector) to be normalized. |
ref |
A reference matrix from which the column-wise minima and maxima are taken.
Default is |
A matrix of the same dimensions as x, with each column rescaled to the range.
# Example. x <- nmfkc.normalize(iris[,-5]) apply(x,2,range)# Example. x <- nmfkc.normalize(iris[,-5]) apply(x,2,range)
nmfkc.rank provides diagnostic criteria for selecting the rank ()
in NMF with kernel covariates. Several model selection measures are computed
(e.g., R-squared, silhouette, CPCC, ARI), and results can be visualized in a plot.
By default (save.time = FALSE), this function also computes the
Element-wise Cross-Validation error (Wold's CV Sigma) using nmfkc.ecv.
The plot explicitly marks the "BEST" rank based on two criteria:
Elbow Method (Red): Based on the curvature of the R-squared values (always computed if Q > 2).
Min RMSE (Blue): Based on the minimum Element-wise CV Sigma (only if detail="full").
nmfkc.rank(Y, A = NULL, rank = 1:2, detail = "full", plot = TRUE, data, ...)nmfkc.rank(Y, A = NULL, rank = 1:2, detail = "full", plot = TRUE, data, ...)
Y |
Observation matrix, or a formula (see |
A |
Covariate matrix. If |
rank |
A vector of candidate ranks to be evaluated. |
detail |
Level of criterion computation: |
plot |
Logical. If |
data |
A data frame (required when |
... |
Additional arguments passed to
|
A list containing:
rank.best |
The estimated optimal rank. Prioritizes ECV minimum if available, otherwise R-squared Elbow. |
criteria |
A data frame containing diagnostic metrics for each rank. |
Brunet, J.P., Tamayo, P., Golub, T.R., Mesirov, J.P. (2004). Metagenes and molecular pattern discovery using matrix factorization. Proc. Natl. Acad. Sci. USA, 101, 4164–4169. doi:10.1073/pnas.0308531101 Punera, K., & Ghosh, J. (2008). Consensus-based ensembles of soft clusterings. Applied Artificial Intelligence, 22(7–8), 780–810. doi:10.1080/08839510802170546
# Example. Y <- t(iris[,-5]) # Full run (default) nmfkc.rank(Y, rank=1:4) # Fast run (skip ECV) nmfkc.rank(Y, rank=1:4, detail="fast")# Example. Y <- t(iris[,-5]) # Full run (default) nmfkc.rank(Y, rank=1:4) # Fast run (skip ECV) nmfkc.rank(Y, rank=1:4, detail="fast")
This function generates a side-by-side plot of three heatmaps: the original observation matrix Y, the fitted matrix XB (from NMF), and the residual matrix E (Y - XB). This visualization aids in diagnosing whether the chosen rank Q is adequate by assessing if the residual matrix E appears to be random noise.
The axis labels (X-axis: Samples, Y-axis: Features) are integrated into the main title of each plot to maximize the plot area, reflecting the compact layout settings.
nmfkc.residual.plot( Y, result, fitted.palette = (grDevices::colorRampPalette(c("white", "orange", "red")))(256), residual.palette = (grDevices::colorRampPalette(c("blue", "white", "red")))(256), ... )nmfkc.residual.plot( Y, result, fitted.palette = (grDevices::colorRampPalette(c("white", "orange", "red")))(256), residual.palette = (grDevices::colorRampPalette(c("blue", "white", "red")))(256), ... )
Y |
The original observation matrix (P x N). |
result |
The result object returned by the nmfkc function. |
fitted.palette |
A vector of colors for Y and XB heatmaps. Defaults to white-orange-red.
For backward compatibility, |
residual.palette |
A vector of colors for the residuals heatmap. Defaults to blue-white-red.
For backward compatibility, |
... |
Additional graphical parameters passed to the internal image calls. |
NULL. The function generates a plot.
Y <- t(iris[1:30, 1:4]) result <- nmfkc(Y, rank = 2) nmfkc.residual.plot(Y, result)Y <- t(iris[1:30, 1:4]) result <- nmfkc(Y, rank = 2) nmfkc.residual.plot(Y, result)
Solves
where the covariate matrix and the coefficient matrix
may be signed. Internally
and with
(sign-splitting trick, Ding et al. 2010), and the problem is solved
by a Direct Multiplicative Update algorithm whose iteration cost is
, independent of .
Only is structurally constrained to be non-negative (Semi-NMF
sense of Ding, Li, & Jordan 2010). In particular, may
contain negative entries, in which case the response is fit in the
least-squares sense without any non-negativity requirement on .
When (so ), the result reduces to
nmfkc(Y, A, rank) with Euclidean loss, up to reordering.
nmfkc.signed( Y, A, rank = NULL, epsilon = 1e-04, maxit = 5000, verbose = TRUE, ... )nmfkc.signed( Y, A, rank = NULL, epsilon = 1e-04, maxit = 5000, verbose = TRUE, ... )
Y |
Real-valued |
A |
Real-valued |
rank |
Integer. Number of latent components |
epsilon |
Relative convergence tolerance on the objective
(default |
maxit |
Maximum number of iterations (default |
verbose |
Logical. Print dimensions at start (default |
... |
Additional arguments:
|
An object of class c("nmfkc.signed", "nmfkc") with
X: basis matrix (non-negative,
column-normalized according to X.restriction).
Cp, Cn: non-negative parts of
, so that .
C: (= ), signed.
B: , (signed).
objfunc.iter: objective values per iteration.
objfunc: final objective.
r.squared: .
mae: mean absolute error.
iter: number of iterations performed.
runtime: elapsed seconds.
Y.signed: logical; whether contained negative
entries during fitting.
pars: RFF generating parameters, if supplied.
call: the matched call.
This function is experimental. The interface may change in future versions.
Ding, C. H. Q., Li, T., & Jordan, M. I. (2010). Convex and semi-nonnegative matrix factorizations. IEEE TPAMI, 32(1), 45–55.
Rahimi, A., & Recht, B. (2007). Random features for large-scale kernel machines. Advances in NIPS, 20.
set.seed(1) ## Example 1: signed A (e.g., hand-built RFF features), non-negative Y ## Build simple signed features Z = sqrt(2/D) * cos(omega^T U + b): U <- matrix(stats::rnorm(5 * 40), 5, 40) # raw input D <- 20 # feature dim omega <- matrix(stats::rnorm(5 * D), 5, D) # random freqs b <- stats::runif(D, 0, 2 * pi) # phase Z <- sqrt(2 / D) * cos(t(omega) %*% U + matrix(b, D, 40)) # D x 40, signed Y <- matrix(abs(stats::rnorm(8 * 40)), 8, 40) res1 <- nmfkc.signed(Y, A = Z, rank = 3, maxit = 200) ## Example 2: signed Y (regression) Y2 <- matrix(stats::rnorm(8 * 40), 8, 40) # signed response res2 <- nmfkc.signed(Y2, A = Z, rank = 3, maxit = 200, warm.start = FALSE)set.seed(1) ## Example 1: signed A (e.g., hand-built RFF features), non-negative Y ## Build simple signed features Z = sqrt(2/D) * cos(omega^T U + b): U <- matrix(stats::rnorm(5 * 40), 5, 40) # raw input D <- 20 # feature dim omega <- matrix(stats::rnorm(5 * D), 5, D) # random freqs b <- stats::runif(D, 0, 2 * pi) # phase Z <- sqrt(2 / D) * cos(t(omega) %*% U + matrix(b, D, 40)) # D x 40, signed Y <- matrix(abs(stats::rnorm(8 * 40)), 8, 40) res1 <- nmfkc.signed(Y, A = Z, rank = 3, maxit = 200) ## Example 2: signed Y (regression) Y2 <- matrix(stats::rnorm(8 * 40), 8, 40) # signed response res2 <- nmfkc.signed(Y2, A = Z, rank = 3, maxit = 200, warm.start = FALSE)
Column-wise k-fold CV by held-out samples: for each
fold, the model is fit on the training columns and evaluated on the
held-out columns by solving for new-sample coefficients via a
weighted refit with fixed.
nmfkc.signed.cv(Y, A, rank = 2, ...)nmfkc.signed.cv(Y, A, rank = 2, ...)
Y |
Real-valued |
A |
Real-valued |
rank |
Integer |
... |
Passed to |
A list with objfunc (mean squared prediction error),
sigma (RMSE), objfunc.block (per-fold MSE vector),
block (integer fold assignment of length ). Field
names match nmfkc.cv.
This function is experimental.
Ding, C. H. Q., Li, T., & Jordan, M. I. (2010). Convex and semi-nonnegative matrix factorizations. IEEE Transactions on Pattern Analysis and Machine Intelligence, 32(1), 45–55.
nmfkc.signed, nmfkc.signed.ecv
Element-wise k-fold CV (Wold's CV): held-out elements
are masked via Y.weights = 0 during fitting, and the RMSE on
those elements is reported. Loops over candidate rank values.
nmfkc.signed.ecv(Y, A, rank = 1:3, ...)nmfkc.signed.ecv(Y, A, rank = 1:3, ...)
Y |
Real-valued |
A |
Real-valued |
rank |
Integer vector of candidate ranks (default |
... |
Passed to |
A list with objfunc (MSE per rank), sigma
(RMSE), objfunc.fold (per-fold per-rank), folds,
Q.grid.
This function is experimental.
Ding, C. H. Q., Li, T., & Jordan, M. I. (2010). Convex and semi-nonnegative matrix factorizations. IEEE Transactions on Pattern Analysis and Machine Intelligence, 32(1), 45–55.
Estimates the NMF-RE model
where () is a non-negative observation matrix,
() is a non-negative basis matrix learned from the data,
() is a non-negative coefficient matrix capturing
systematic covariate effects on latent scores,
() is a covariate matrix, and
() is a random effects matrix capturing
unit-specific deviations in the latent score space.
NMF-RE can be viewed as a mixed-effects latent-variable model defined on a
reconstruction (mean) structure. The non-negativity constraint on
induces sparse, parts-based loadings, achieving measurement-side variable
selection without an explicit sparsity penalty. Inference on
provides covariate-side variable selection by identifying which covariates
significantly affect which components.
Estimation alternates ridge-type BLUP-like closed-form updates for
with multiplicative non-negative updates for and .
The effective degrees of freedom consumed by are monitored and a
df-based cap can be enforced to prevent near-saturated fits.
When wild.bootstrap = TRUE, inference on is performed
conditional on via asymptotic linearization,
a one-step Newton update, and a multiplier (wild) bootstrap, yielding
standard errors, z-values, p-values, and confidence intervals without
repeated constrained re-optimization.
nmfre( Y, A = NULL, rank = 2, df.rate = NULL, wild.bootstrap = TRUE, epsilon = 1e-05, maxit = 5000, ... )nmfre( Y, A = NULL, rank = 2, df.rate = NULL, wild.bootstrap = TRUE, epsilon = 1e-05, maxit = 5000, ... )
Y |
Observation matrix (P x N), non-negative. |
A |
Covariate matrix (K x N). Default is a row of ones (intercept only). |
rank |
Integer. Rank of the basis matrix |
df.rate |
Rate for computing the dfU cap ( |
wild.bootstrap |
Logical. If |
epsilon |
Convergence tolerance for relative change in objective (default 1e-5). |
maxit |
Maximum number of iterations. Default |
... |
Additional arguments for initialization, variance control, dfU control, optimization, and inference settings.
|
A list of class "nmfre" with components.
The model is .
Core matrices
XBasis matrix (), columns normalized to sum to 1.
CCoefficient matrix ().
URandom effects matrix ().
Variance components
sigma2Residual variance .
tau2Random effect variance .
lambdaRidge penalty .
Convergence diagnostics
convergedLogical. Whether the algorithm converged.
stop.reasonCharacter string describing why iteration stopped.
iterNumber of iterations performed.
maxitMaximum iterations setting used.
epsilonConvergence tolerance used.
objfuncFinal objective function value
.
rel.change.finalFinal relative change in objective.
objfunc.iterNumeric vector of objective values per iteration.
rss.traceNumeric vector of per iteration.
Effective degrees of freedom (dfU) diagnostics
dfUFinal effective degrees of freedom
,
where are eigenvalues of .
dfU.capUpper bound imposed on .
dfU.cap.rateRate used to compute the cap.
dfU.cap.scanResult of nmfre.dfU.scan, or NULL.
lambda.enforcedFinal enforced to satisfy the cap.
dfU.hit.capLogical. Whether the cap was binding.
dfU.hit.iterIteration at which the cap first bound.
dfU.frac, fraction of maximum df.
dfU.cap.frac.
Fitted matrices
BFixed-effect scores ().
B.probColumn-normalized probabilities from
.
B.blupBLUP scores ().
B.blup.posNon-negative BLUP scores
().
B.blup.probColumn-normalized probabilities from
.
XBFitted values from fixed effects
().
XB.blupFitted values including random effects
().
Fit statistics
r.squaredCoefficient of determination for
vs (BLUP).
r.squared.fixedCoefficient of determination for
vs (fixed effects only).
ICCTrace-based Intraclass Correlation Coefficient.
In the NMF-RE model, the conditional covariance of the -th
observation column is
,
a matrix. Unlike a standard random intercept model
where the design matrix is a simple indicator (so the ICC
reduces to ), the basis matrix
plays the role of in a random slopes model,
making the variance contribution of depend on .
To obtain a scalar summary, we take the trace of each component:
This equals the average (over dimensions) proportion of
per-column variance attributable to the random effects.
Inference on (wild bootstrap)
sigma2.used used for inference.
C.vec.covVariance-covariance matrix for
().
C.seStandard error matrix for ().
C.se.hessSandwich (Hessian-based) SE matrix for .
C.se.bootBootstrap SE matrix for .
coefficientsData frame with columns Estimate, Std. Error, z value,
Pr(>|z|), and confidence interval bounds for each element of .
C.ci.lowerLower confidence interval matrix for ().
C.ci.upperUpper confidence interval matrix for ().
C.boot.sdBootstrap standard deviation matrix for ().
C.p.sideP-value sidedness used: "one.sided" or "two.sided".
Satoh, K. (2026). Wild Bootstrap Inference for Non-Negative Matrix Factorization with Random Effects. arXiv:2603.01468. https://arxiv.org/abs/2603.01468
nmfre.inference, nmfre.dfU.scan,
nmfkc.DOT, summary.nmfre
# Example 1. cars data Y <- matrix(cars$dist, nrow = 1) A <- rbind(intercept = 1, speed = cars$speed) res <- nmfre(Y, A, rank = 1, maxit = 5000) summary(res) # Example 2. Orthodont data (nlme) if (requireNamespace("nlme", quietly = TRUE)) { Y <- matrix(nlme::Orthodont$distance, 4, 27) male <- ifelse(nlme::Orthodont$Sex[seq(1, 108, 4)] == "Male", 1, 0) A <- rbind(intercept = 1, male = male) # Scan dfU cap rates to choose an appropriate value nmfre.dfU.scan(1:10/10, Y, A, rank = 1) # Fit with chosen rate res <- nmfre(Y, A, rank = 1, df.rate = 0.2) summary(res) }# Example 1. cars data Y <- matrix(cars$dist, nrow = 1) A <- rbind(intercept = 1, speed = cars$speed) res <- nmfre(Y, A, rank = 1, maxit = 5000) summary(res) # Example 2. Orthodont data (nlme) if (requireNamespace("nlme", quietly = TRUE)) { Y <- matrix(nlme::Orthodont$distance, 4, 27) male <- ifelse(nlme::Orthodont$Sex[seq(1, 108, 4)] == "Male", 1, 0) A <- rbind(intercept = 1, male = male) # Scan dfU cap rates to choose an appropriate value nmfre.dfU.scan(1:10/10, Y, A, rank = 1) # Fit with chosen rate res <- nmfre(Y, A, rank = 1, df.rate = 0.2) summary(res) }
Fits the NMF-RE model across a range of dfU.cap.rate values and
returns a diagnostic table showing the resulting effective degrees of freedom,
variance components, and convergence diagnostics for each rate.
The dfU cap limits the effective degrees of freedom consumed by the random
effects . The cap is computed as rate * N * Q, where
is the number of observations and is the rank. A suitable rate is
one where the final is below the cap
(safeguard = TRUE) and the model has converged
(converged = TRUE).
When called automatically by nmfre (i.e., dfU.cap.rate = NULL),
the minimum rate satisfying both safeguard = TRUE and
converged = TRUE is selected.
nmfre.dfU.scan( rates = (1:10)/10, Y, A, rank = NULL, X.init = NULL, C.init = NULL, U.init = NULL, print.trace = FALSE, ... )nmfre.dfU.scan( rates = (1:10)/10, Y, A, rank = NULL, X.init = NULL, C.init = NULL, U.init = NULL, print.trace = FALSE, ... )
rates |
Numeric vector of cap rates to scan (default |
Y |
Observation matrix (P x N). |
A |
Covariate matrix (K x N). |
rank |
Integer. Rank of the basis matrix.
For backward compatibility, |
X.init |
Initial basis matrix, or |
C.init |
Initial coefficient matrix, or |
U.init |
Initial random effects matrix, or |
print.trace |
Logical. Print progress for each fit (default |
... |
Additional arguments passed to |
An object of class "nmfre.dfU.scan" with two components:
tableA data frame with the following columns:
rateCap rate used. The dfU cap is rate * N * Q.
dfU.capThe dfU cap value (upper bound on effective degrees of freedom).
dfUFinal effective degrees of freedom for at convergence.
safeguardLogical. TRUE if the dfU cap is functioning
as a safeguard (dfU / dfU.cap < 0.99): the cap prevents
random-effects saturation without over-constraining .
FALSE if dfU is at or near the cap, indicating the cap is
binding and the rate may be too small.
hitLogical. TRUE if the cap was reached at least once
during iteration, even if dfU later decreased below the cap.
convergedLogical. TRUE if the algorithm converged
within the maximum number of iterations.
tau2Final random effect variance .
sigma2Final residual variance .
ICCTrace-based Intraclass Correlation Coefficient
.
See nmfre for details.
cap.rateOptimal cap rate selected automatically.
If rows with safeguard = TRUE and hit = TRUE exist,
the maximum rate among them is chosen (safeguard activated but
giving the most freedom). Otherwise, the minimum rate
with safeguard = TRUE and hit = FALSE is chosen.
NA if no suitable rate is found.
When printed, only the table is displayed. Access cap.rate
directly from the returned object.
# Example 1. cars data (small maxit for speed) Y <- matrix(cars$dist, nrow = 1) A <- rbind(intercept = 1, speed = cars$speed) tab <- nmfre.dfU.scan(rates = c(0.1, 0.2), Y = Y, A = A, rank = 1, maxit = 1000) print(tab) # Example 2. Orthodont data (nlme) if (requireNamespace("nlme", quietly = TRUE)) { Y <- matrix(nlme::Orthodont$distance, 4, 27) male <- ifelse(nlme::Orthodont$Sex[seq(1, 108, 4)] == "Male", 1, 0) A <- rbind(intercept = 1, male = male) nmfre.dfU.scan(1:10/10, Y, A, rank = 1) }# Example 1. cars data (small maxit for speed) Y <- matrix(cars$dist, nrow = 1) A <- rbind(intercept = 1, speed = cars$speed) tab <- nmfre.dfU.scan(rates = c(0.1, 0.2), Y = Y, A = A, rank = 1, maxit = 1000) print(tab) # Example 2. Orthodont data (nlme) if (requireNamespace("nlme", quietly = TRUE)) { Y <- matrix(nlme::Orthodont$distance, 4, 27) male <- ifelse(nlme::Orthodont$Sex[seq(1, 108, 4)] == "Male", 1, 0) A <- rbind(intercept = 1, male = male) nmfre.dfU.scan(1:10/10, Y, A, rank = 1) }
nmfre.inference performs statistical inference on the coefficient
matrix () from a fitted nmfre model,
conditional on the estimated basis matrix and random
effects .
Under the working model ,
inference is conducted via sandwich covariance estimation and
one-step wild bootstrap with non-negative projection.
The result is compatible with nmfkc.DOT for visualization
(pass the result directly as x with type = "YXA").
nmfre.inference(object, Y, A = NULL, wild.bootstrap = TRUE, ...)nmfre.inference(object, Y, A = NULL, wild.bootstrap = TRUE, ...)
object |
An object of class |
Y |
Observation matrix (P x N). Must match the data used in
|
A |
Covariate matrix (K x N). Default is |
wild.bootstrap |
Logical. If |
... |
Additional arguments:
|
The input object with additional inference components:
sigma2.used |
Estimated |
C.vec.cov |
Full covariance matrix for |
C.se |
Sandwich standard errors for |
C.se.boot |
Bootstrap standard errors for |
C.ci.lower |
Lower CI bounds for |
C.ci.upper |
Upper CI bounds for |
coefficients |
Data frame with Basis, Covariate, Estimate, SE, BSE, z_value, p_value, CI_low, CI_high. |
C.p.side |
P-value type used. |
Satoh, K. (2026). Wild Bootstrap Inference for Non-Negative Matrix Factorization with Random Effects. arXiv:2603.01468. https://arxiv.org/abs/2603.01468
nmfre, nmfkc.DOT,
summary.nmfre
Y <- matrix(cars$dist, nrow = 1) A <- rbind(intercept = 1, speed = cars$speed) res <- nmfre(Y, A, rank = 1, wild.bootstrap = FALSE) res2 <- nmfre.inference(res, Y, A) res2$coefficientsY <- matrix(cars$dist, nrow = 1) A <- rbind(intercept = 1, speed = cars$speed) res <- nmfre(Y, A, rank = 1, wild.bootstrap = FALSE) res2 <- nmfre.inference(res, Y, A) res2$coefficients
plot.nmfae displays the convergence trajectory of the objective function
across iterations. The title shows the achieved plot.nmfae displays the convergence trajectory of the objective function
across iterations. The title shows the achieved .
## S3 method for class 'nmfae' plot(x, ...)## S3 method for class 'nmfae' plot(x, ...)
x |
An object of class |
... |
Additional graphical parameters passed to |
Invisible NULL. Called for its side effect (plot).
set.seed(1) Y <- matrix(runif(20), nrow = 4) res <- nmfae(Y, rank = 2) plot(res)set.seed(1) Y <- matrix(runif(20), nrow = 4) res <- nmfae(Y, rank = 2) plot(res)
Displays a bar chart of per-fold cross-validation errors from
nmfae.cv. The overall RMSE (sigma) is shown in the title.
## S3 method for class 'nmfae.cv' plot(x, ...)## S3 method for class 'nmfae.cv' plot(x, ...)
x |
An object of class |
... |
Additional graphical parameters passed to |
Invisible NULL. Called for its side effect (plot).
Visualizes element-wise cross-validation results.
When rank.encoder was NULL (paired), a line plot of sigma vs rank is drawn.
When rank.encoder was explicitly specified (grid), a heatmap of sigma over the (rank, rank.encoder) grid is drawn.
## S3 method for class 'nmfae.ecv' plot(x, ...)## S3 method for class 'nmfae.ecv' plot(x, ...)
x |
An object of class |
... |
Additional graphical parameters (currently unused). |
Invisible NULL. Called for its side effect of producing a plot.
Displays the cross-validation objective function across candidate
beta values (log scale). The optimal beta is highlighted in red.
## S3 method for class 'nmfae.kernel.beta.cv' plot(x, ...)## S3 method for class 'nmfae.kernel.beta.cv' plot(x, ...)
x |
An object of class |
... |
Additional graphical parameters passed to |
Invisible NULL. Called for its side effect (plot).
Displays the convergence trajectory of the objective function.
## S3 method for class 'nmfae.signed' plot(x, ...)## S3 method for class 'nmfae.signed' plot(x, ...)
x |
An |
... |
Additional graphical parameters. |
Invisible NULL.
This function is experimental. The interface may change in future versions.
Ding, C. H. Q., Li, T., & Jordan, M. I. (2010). Convex and semi-nonnegative matrix factorizations. IEEE Transactions on Pattern Analysis and Machine Intelligence, 32(1), 45–55.
nmfkc
plot.nmfkc produces a diagnostic plot for the return value of
nmfkc, showing the objective function across iterations.
## S3 method for class 'nmfkc' plot(x, ...)## S3 method for class 'nmfkc' plot(x, ...)
x |
An object of class |
... |
Additional arguments passed to the base |
Called for its side effect (a plot). Returns NULL invisibly.
Y <- matrix(cars$dist, nrow = 1) A <- rbind(1, cars$speed) result <- nmfkc(Y, A, rank = 1) plot(result)Y <- matrix(cars$dist, nrow = 1) A <- rbind(1, cars$speed) result <- nmfkc(Y, A, rank = 1) plot(result)
Renders a DOT graph string using DiagrammeR::grViz.
If the DiagrammeR package is not installed, prints the DOT source
to the console instead.
This method handles all DOT objects produced by the nmfkc package:
nmfkc.DOT, nmfae.DOT, nmf.sem.DOT,
and nmfkc.ar.DOT.
## S3 method for class 'nmfkc.DOT' plot(x, ...)## S3 method for class 'nmfkc.DOT' plot(x, ...)
x |
An object of class |
... |
Not used. |
Called for its side effect (rendering). Returns x invisibly.
nmfkc.DOT, nmfae.DOT,
nmf.sem.DOT, nmfkc.ar.DOT
Plot method for nmfkc.signed (convergence)
## S3 method for class 'nmfkc.signed' plot(x, ...)## S3 method for class 'nmfkc.signed' plot(x, ...)
x |
An |
... |
Passed to |
Invisible x.
This function is experimental. The interface may change in future versions.
Ding, C. H. Q., Li, T., & Jordan, M. I. (2010). Convex and semi-nonnegative matrix factorizations. IEEE Transactions on Pattern Analysis and Machine Intelligence, 32(1), 45–55.
Plots the objective function value over iterations for nmfre and
nmf.sem objects. (For nmfkc and nmfae, plot methods
are defined in their respective source files.)
## S3 method for class 'nmfre' plot(x, ...) ## S3 method for class 'nmf.sem' plot(x, ..., which = c("full", "reconstruction", "both"))## S3 method for class 'nmfre' plot(x, ...) ## S3 method for class 'nmf.sem' plot(x, ..., which = c("full", "reconstruction", "both"))
x |
A fitted model object. |
... |
Additional graphical arguments passed to |
which |
For |
Invisible NULL.
set.seed(1) Y <- matrix(runif(20), nrow = 4) A <- diag(5) res <- nmfre(Y, A, rank = 2, wild.bootstrap = FALSE) plot(res)set.seed(1) Y <- matrix(runif(20), nrow = 4) A <- diag(5) res <- nmfre(Y, A, rank = 2, wild.bootstrap = FALSE) plot(res)
For type = "response": if actual values were stored,
displays an observed-vs-predicted scatter plot with in the title.
Otherwise, displays the predicted matrix as a heatmap.
For type = "class": if actual classes were stored, displays a
confusion matrix heatmap with accuracy (ACC) in the title.
## S3 method for class 'predict.nmfae' plot(x, ...)## S3 method for class 'predict.nmfae' plot(x, ...)
x |
An object of class |
... |
Additional graphical parameters passed to |
Invisible NULL. Called for its side effect (plot).
set.seed(1) Y <- matrix(runif(20), nrow = 4) res <- nmfae(Y, rank = 2) pred <- predict(res) plot(pred)set.seed(1) Y <- matrix(runif(20), nrow = 4) res <- nmfae(Y, rank = 2) pred <- predict(res) plot(pred)
predict.nmfae computes fitted or predicted values from a three-layer NMF model.
Without newY2, returns the in-sample fitted values .
With newY2, computes out-of-sample predictions .
When type = "class", each column is classified to the row with the
maximum predicted value (useful when is a one-hot class matrix
from nmfkc.class).
If Y1 (actual values) is provided, it is stored as an attribute so that
plot.predict.nmfae can produce an observed-vs-predicted scatter plot
(for type = "response") or a confusion matrix heatmap
(for type = "class").
## S3 method for class 'nmfae' predict(object, newY2 = NULL, Y1 = NULL, type = c("response", "class"), ...)## S3 method for class 'nmfae' predict(object, newY2 = NULL, Y1 = NULL, type = c("response", "class"), ...)
object |
An object of class |
newY2 |
Optional new input matrix (P2 x M) for prediction.
If |
Y1 |
Optional actual output matrix for comparison plotting. |
type |
Character. |
... |
Not used. |
For type = "response": a matrix of class "predict.nmfae".
For type = "class": a factor of class "predict.nmfae" with
predicted class labels. If Y1 was provided, actual classes are stored
in attr(result, "actual").
nmfae, plot.predict.nmfae,
nmfkc.class
set.seed(1) Y <- matrix(runif(20), nrow = 4) res <- nmfae(Y, rank = 2) pred <- predict(res)set.seed(1) Y <- matrix(runif(20), nrow = 4) res <- nmfae(Y, rank = 2) pred <- predict(res)
Computes .
Since is signed, predictions may contain
negative entries even when in training.
## S3 method for class 'nmfae.signed' predict(object, newY2 = NULL, Y1 = NULL, type = c("response", "class"), ...)## S3 method for class 'nmfae.signed' predict(object, newY2 = NULL, Y1 = NULL, type = c("response", "class"), ...)
object |
A fitted |
newY2 |
New input matrix (P2 x N_new). If |
Y1 |
Optional reference Y1 for scatter / confusion plot. |
type |
Output: |
... |
Unused. |
A numeric matrix ("response") or factor ("class").
This function is experimental. The interface may change in future versions.
Ding, C. H. Q., Li, T., & Jordan, M. I. (2010). Convex and semi-nonnegative matrix factorizations. IEEE Transactions on Pattern Analysis and Machine Intelligence, 32(1), 45–55.
nmfkc
predict.nmfkc generates predictions from an object of class nmfkc,
either using the fitted covariates or a new covariate matrix.
When the model was fitted using a formula (Formula Mode), a newdata
data frame can be supplied instead of newA; the covariate matrix is
then constructed automatically from the stored formula metadata.
## S3 method for class 'nmfkc' predict(object, newA = NULL, newdata = NULL, type = "response", ...)## S3 method for class 'nmfkc' predict(object, newA = NULL, newdata = NULL, type = "response", ...)
object |
An object of class |
newA |
Optional. A new covariate matrix to be used for prediction. |
newdata |
Optional data frame. Only available when the model was fitted
using a formula. Covariate columns are extracted automatically using the
stored formula metadata. If both |
type |
Type of prediction to return. Options are "response" (fitted values matrix), "prob" (soft-clustering probabilities), or "class" (hard-clustering labels based on row names of X). |
... |
Further arguments passed to or from other methods. |
Depending on type: a numeric matrix ("response" or "prob")
or a character vector of class labels ("class").
# Prediction with newA Y <- matrix(cars$dist, nrow = 1) A <- rbind(1, cars$speed) result <- nmfkc(Y, A, rank = 1) newA <- rbind(1, c(10, 20, 30)) predict(result, newA = newA)# Prediction with newA Y <- matrix(cars$dist, nrow = 1) A <- rbind(1, cars$speed) result <- nmfkc(Y, A, rank = 1) newA <- rbind(1, c(10, 20, 30)) predict(result, newA = newA)
Computes
().
For type = "response" the raw prediction is returned
(possibly signed). For type = "prob" and "class",
negative entries of are clipped to zero before
column normalization, since probabilities must be non-negative.
## S3 method for class 'nmfkc.signed' predict(object, newA = NULL, type = c("response", "prob", "class"), ...)## S3 method for class 'nmfkc.signed' predict(object, newA = NULL, type = c("response", "prob", "class"), ...)
object |
A fitted |
newA |
Real-valued |
type |
Output: |
... |
Unused. |
A numeric matrix ("response" or "prob") or a
character vector ("class").
This function is experimental. The interface may change in future versions.
Ding, C. H. Q., Li, T., & Jordan, M. I. (2010). Convex and semi-nonnegative matrix factorizations. IEEE Transactions on Pattern Analysis and Machine Intelligence, 32(1), 45–55.
Prints a summary of any NMF inference result object
("nmfkc.inference" or "nmfae.inference").
## S3 method for class 'nmf.inference' print(x, ...)## S3 method for class 'nmf.inference' print(x, ...)
x |
An object of class |
... |
Additional arguments passed to the corresponding
|
Called for its side effect (printing). Returns x invisibly.
nmfkc.inference, nmfae.inference
Prints a formatted summary of an NMF-AE model fit.
## S3 method for class 'summary.nmfae' print(x, digits = max(3L, getOption("digits") - 3L), max.coef = 20, ...)## S3 method for class 'summary.nmfae' print(x, digits = max(3L, getOption("digits") - 3L), max.coef = 20, ...)
x |
An object of class |
digits |
Minimum number of significant digits to be used. |
max.coef |
Maximum number of coefficient rows to display. If the table has more rows, only significant rows (p < 0.05) are shown. Default is 20. |
... |
Additional arguments (currently unused). |
Called for its side effect (printing). Returns x invisibly.
Prints a formatted summary including the coefficients table.
## S3 method for class 'summary.nmfae.inference' print(x, digits = max(3L, getOption("digits") - 3L), max.coef = 20, ...)## S3 method for class 'summary.nmfae.inference' print(x, digits = max(3L, getOption("digits") - 3L), max.coef = 20, ...)
x |
An object of class |
digits |
Minimum number of significant digits. |
max.coef |
Maximum coefficient rows to display. Default is 20. |
... |
Additional arguments (currently unused). |
Called for its side effect (printing). Returns x invisibly.
Print method for summary.nmfae.signed
## S3 method for class 'summary.nmfae.signed' print(x, digits = max(3L, getOption("digits") - 3L), ...)## S3 method for class 'summary.nmfae.signed' print(x, digits = max(3L, getOption("digits") - 3L), ...)
x |
A |
digits |
Number of significant digits. |
... |
Unused. |
Invisible x.
This function is experimental. The interface may change in future versions.
Ding, C. H. Q., Li, T., & Jordan, M. I. (2010). Convex and semi-nonnegative matrix factorizations. IEEE Transactions on Pattern Analysis and Machine Intelligence, 32(1), 45–55.
Prints the Signed-Bottleneck NMF-AE summary followed by the coefficients table of Theta.
## S3 method for class 'summary.nmfae.signed.inference' print(x, digits = max(3L, getOption("digits") - 3L), ...)## S3 method for class 'summary.nmfae.signed.inference' print(x, digits = max(3L, getOption("digits") - 3L), ...)
x |
An object of class |
digits |
Minimum number of significant digits. |
... |
Additional arguments (currently unused). |
Called for its side effect (printing). Returns x invisibly.
This function is experimental. The interface may change in future versions.
Ding, C. H. Q., Li, T., & Jordan, M. I. (2010). Convex and semi-nonnegative matrix factorizations. IEEE Transactions on Pattern Analysis and Machine Intelligence, 32(1), 45–55.
summary.nmfae.signed.inference
summary.nmfkc objectsPrints a formatted summary of an nmfkc model fit.
## S3 method for class 'summary.nmfkc' print(x, digits = max(3L, getOption("digits") - 3L), ...)## S3 method for class 'summary.nmfkc' print(x, digits = max(3L, getOption("digits") - 3L), ...)
x |
An object of class |
digits |
Minimum number of significant digits to be used. |
... |
Additional arguments (currently unused). |
Called for its side effect (printing). Returns x invisibly.
Y <- matrix(cars$dist, nrow = 1) A <- rbind(1, cars$speed) result <- nmfkc(Y, A, rank = 1) print(summary(result))Y <- matrix(cars$dist, nrow = 1) A <- rbind(1, cars$speed) result <- nmfkc(Y, A, rank = 1) print(summary(result))
Prints a formatted summary including the coefficients table.
## S3 method for class 'summary.nmfkc.inference' print(x, digits = max(3L, getOption("digits") - 3L), max.coef = 20, ...)## S3 method for class 'summary.nmfkc.inference' print(x, digits = max(3L, getOption("digits") - 3L), max.coef = 20, ...)
x |
An object of class |
digits |
Minimum number of significant digits. |
max.coef |
Maximum coefficient rows to display. Default is 20. |
... |
Additional arguments (currently unused). |
Called for its side effect (printing). Returns x invisibly.
Print method for summary.nmfkc.net objects
## S3 method for class 'summary.nmfkc.net' print(x, digits = max(3L, getOption("digits") - 3L), ...)## S3 method for class 'summary.nmfkc.net' print(x, digits = max(3L, getOption("digits") - 3L), ...)
x |
An object of class |
digits |
Minimum number of significant digits. |
... |
Unused. |
Invisible x.
Prints a formatted summary of a symmetric NMF model with inference results.
The coefficients table uses Basis.row and Basis.col labels
reflecting the symmetric structure .
## S3 method for class 'summary.nmfkc.net.inference' print(x, digits = max(3L, getOption("digits") - 3L), ...)## S3 method for class 'summary.nmfkc.net.inference' print(x, digits = max(3L, getOption("digits") - 3L), ...)
x |
An object of class |
digits |
Minimum number of significant digits. |
... |
Additional arguments (currently unused). |
Called for its side effect (printing). Returns x invisibly.
Print method for summary.nmfkc.net.signed objects
## S3 method for class 'summary.nmfkc.net.signed' print(x, digits = max(3L, getOption("digits") - 3L), ...)## S3 method for class 'summary.nmfkc.net.signed' print(x, digits = max(3L, getOption("digits") - 3L), ...)
x |
An object of class |
digits |
Minimum number of significant digits. |
... |
Unused. |
Invisible x.
Print method for summary.nmfkc.signed
## S3 method for class 'summary.nmfkc.signed' print(x, digits = max(3L, getOption("digits") - 3L), ...)## S3 method for class 'summary.nmfkc.signed' print(x, digits = max(3L, getOption("digits") - 3L), ...)
x |
Object of class |
digits |
Number of significant digits. |
... |
Unused. |
Invisible x.
This function is experimental. The interface may change in future versions.
Ding, C. H. Q., Li, T., & Jordan, M. I. (2010). Convex and semi-nonnegative matrix factorizations. IEEE Transactions on Pattern Analysis and Machine Intelligence, 32(1), 45–55.
Returns the residual matrix from a fitted NMF model.
Requires the original observation matrix Y to be supplied.
For nmfre objects, residuals are computed from the BLUP
reconstruction () by default. Set
type = "fixed" to use fixed-effects only.
## S3 method for class 'nmf' residuals(object, Y, ...) ## S3 method for class 'nmfae' residuals(object, Y, ...) ## S3 method for class 'nmfre' residuals(object, Y, type = c("blup", "fixed"), ...) ## S3 method for class 'nmf.sem' residuals(object, Y, ...)## S3 method for class 'nmf' residuals(object, Y, ...) ## S3 method for class 'nmfae' residuals(object, Y, ...) ## S3 method for class 'nmfre' residuals(object, Y, type = c("blup", "fixed"), ...) ## S3 method for class 'nmf.sem' residuals(object, Y, ...)
object |
A fitted model object. |
Y |
The original observation matrix used for fitting. |
... |
Not used. |
type |
For |
The residual matrix.
nmfkc, nmfae, nmfre,
nmf.sem, fitted.nmf
Y <- matrix(runif(50), 5, 10) result <- nmfkc(Y, rank = 2) residuals(result, Y)Y <- matrix(runif(50), 5, 10) result <- nmfkc(Y, rank = 2) residuals(result, Y)
Produces a formatted summary of a fitted NMF-FFB model, including matrix dimensions, convergence, stability diagnostics, fit statistics, and inference results (if available).
## S3 method for class 'nmf.sem' summary(object, ...)## S3 method for class 'nmf.sem' summary(object, ...)
object |
An object of class |
... |
Not used. |
Invisible object.
Y <- t(iris[, -5]) Y1 <- Y[1:2, ]; Y2 <- Y[3:4, ] result <- nmf.sem(Y1, Y2, rank = 2, maxit = 500) summary(result)Y <- t(iris[, -5]) Y1 <- Y[1:2, ]; Y2 <- Y[3:4, ] result <- nmf.sem(Y1, Y2, rank = 2, maxit = 500) summary(result)
summary.nmfae produces a summary of a fitted NMF-AE model,
including dimensions, convergence status, goodness-of-fit statistics,
and structure diagnostics (sparsity of factor matrices).
## S3 method for class 'nmfae' summary(object, ...)## S3 method for class 'nmfae' summary(object, ...)
object |
An object of class |
... |
Additional arguments (currently unused). |
An object of class "summary.nmfae", a list with components:
call |
The matched call. |
dims |
Named vector |
Q |
Decoder rank. |
R |
Encoder rank. |
n.params |
Total number of parameters (P1Q + QR + R*P2). |
autoencoder |
Logical; TRUE if P1 == P2 and Y1 was used as Y2. |
niter |
Number of iterations. |
runtime |
Elapsed time. |
objfunc |
Final objective value. |
r.squared |
R-squared. |
sigma |
Residual standard error (RMSE). |
mae |
Mean absolute error. |
n.missing |
Number of missing elements. |
prop.missing |
Percentage of missing elements. |
X1.sparsity |
Proportion of near-zero elements in X1. |
C.sparsity |
Proportion of near-zero elements in C. |
X2.sparsity |
Proportion of near-zero elements in X2. |
Produces a summary of a fitted NMF-AE model with inference results,
including the coefficients table for .
## S3 method for class 'nmfae.inference' summary(object, ...)## S3 method for class 'nmfae.inference' summary(object, ...)
object |
An object of class |
... |
Additional arguments (currently unused). |
An object of class "summary.nmfae.inference".
nmfae.inference, summary.nmfae
Produces a summary with dimensions, convergence, fit statistics, and structure diagnostics (sparsity and negative-mass ratio).
## S3 method for class 'nmfae.signed' summary(object, ...)## S3 method for class 'nmfae.signed' summary(object, ...)
object |
An |
... |
Unused. |
An object of class "summary.nmfae.signed".
This function is experimental. The interface may change in future versions.
Ding, C. H. Q., Li, T., & Jordan, M. I. (2010). Convex and semi-nonnegative matrix factorizations. IEEE Transactions on Pattern Analysis and Machine Intelligence, 32(1), 45–55.
Produces a summary of a fitted Signed-Bottleneck NMF-AE model with
inference results. Extends summary.nmfae.signed by
attaching the coefficients table and p-value side from
nmfae.signed.inference.
## S3 method for class 'nmfae.signed.inference' summary(object, ...)## S3 method for class 'nmfae.signed.inference' summary(object, ...)
object |
An object of class |
... |
Additional arguments (currently unused). |
An object of class "summary.nmfae.signed.inference".
This function is experimental. The interface may change in future versions.
Ding, C. H. Q., Li, T., & Jordan, M. I. (2010). Convex and semi-nonnegative matrix factorizations. IEEE Transactions on Pattern Analysis and Machine Intelligence, 32(1), 45–55.
nmfae.signed.inference, summary.nmfae.signed
nmfkc
Produces a summary of an nmfkc object, including matrix dimensions,
runtime, fit statistics, and diagnostics.
## S3 method for class 'nmfkc' summary(object, ...)## S3 method for class 'nmfkc' summary(object, ...)
object |
An object of class |
... |
Additional arguments (currently unused). |
An object of class summary.nmfkc, containing summary statistics.
nmfkc, nmfkc.inference, plot.nmfkc
Y <- matrix(cars$dist, nrow = 1) A <- rbind(1, cars$speed) result <- nmfkc(Y, A, rank = 1) summary(result)Y <- matrix(cars$dist, nrow = 1) A <- rbind(1, cars$speed) result <- nmfkc(Y, A, rank = 1) summary(result)
Produces a summary of a fitted NMF model with inference results,
including the coefficients table for ().
## S3 method for class 'nmfkc.inference' summary(object, ...)## S3 method for class 'nmfkc.inference' summary(object, ...)
object |
An object of class |
... |
Additional arguments (currently unused). |
An object of class "summary.nmfkc.inference".
nmfkc.inference, summary.nmfkc
Summary method for nmfkc.net objects
## S3 method for class 'nmfkc.net' summary(object, ...)## S3 method for class 'nmfkc.net' summary(object, ...)
object |
An |
... |
Unused. |
An object of class "summary.nmfkc.net".
Produces a summary of a symmetric NMF model with inference results,
including the coefficients table for .
## S3 method for class 'nmfkc.net.inference' summary(object, ...)## S3 method for class 'nmfkc.net.inference' summary(object, ...)
object |
An object of class |
... |
Additional arguments passed to |
An object of class "summary.nmfkc.net.inference".
Summary method for nmfkc.net.signed objects
## S3 method for class 'nmfkc.net.signed' summary(object, ...)## S3 method for class 'nmfkc.net.signed' summary(object, ...)
object |
An |
... |
Unused. |
An object of class "summary.nmfkc.net.signed".
Summary method for nmfkc.signed
## S3 method for class 'nmfkc.signed' summary(object, ...)## S3 method for class 'nmfkc.signed' summary(object, ...)
object |
An |
... |
Unused. |
An object of class "summary.nmfkc.signed".
This function is experimental. The interface may change in future versions.
Ding, C. H. Q., Li, T., & Jordan, M. I. (2010). Convex and semi-nonnegative matrix factorizations. IEEE Transactions on Pattern Analysis and Machine Intelligence, 32(1), 45–55.
nmfre
Displays a concise summary of an NMF-RE model fit, including dimensions, convergence, variance components, and a coefficient table following standard R regression output conventions.
## S3 method for class 'nmfre' summary(object, show_ci = FALSE, ...)## S3 method for class 'nmfre' summary(object, show_ci = FALSE, ...)
object |
An object of class |
show_ci |
Logical. If |
... |
Additional arguments (currently unused). |
The input object, invisibly.
Y <- matrix(cars$dist, nrow = 1) A <- rbind(intercept = 1, speed = cars$speed) res <- nmfre(Y, A, rank = 1, maxit = 5000) summary(res)Y <- matrix(cars$dist, nrow = 1) A <- rbind(intercept = 1, speed = cars$speed) res <- nmfre(Y, A, rank = 1, maxit = 5000) summary(res)