nmfkc.DOT: Generate Graphviz DOT Scripts for NMF or NMF-with-Covariates...

In nmfkc: Non-Negative Matrix Factorization with Kernel Covariates

Generate Graphviz DOT Scripts for NMF or NMF-with-Covariates Models

Description

Produces a Graphviz DOT script visualizing the structure of an NMF model (Y \approx X C A) or its simplified forms.

Supported visualization types:

• "YX" — Standard NMF view: latent factors X map to observations Y.

• "YA" — Direct regression view: covariates A map directly to Y using the combined coefficient matrix X C.

• "YXA" — Full tri-factorization: A \rightarrow C \rightarrow X \rightarrow Y.

Edge widths are scaled by coefficient magnitude, and nodes with no edges above the threshold are omitted from the visualization.

Usage

nmfkc.DOT(
  result,
  type = c("YX", "YA", "YXA"),
  threshold = 0.01,
  C.signed = NULL,
  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
)

Arguments

result	The return value from nmfkc, containing matrices X, B, and optionally C.
type	Character string specifying the visualization style: one of "YX", "YA", "YXA".
threshold	Minimum coefficient magnitude to display an edge. When C.signed = TRUE (signed \Theta) this is an absolute-value cut, i.e. an edge is drawn when |coef| \ge threshold.
C.signed	Logical or NULL. Whether the coefficient matrix \Theta (= C) may be signed (real-valued). When TRUE, the threshold is applied to |coef|, edge widths are scaled by |coef|, and negative edges are drawn as black dashed lines (positive edges remain solid) to distinguish them; the numeric edge labels keep their sign. When FALSE, the historical non-negative behaviour is used (negative coefficients fall below the threshold and are hidden). When NULL (default), the mode is auto-detected from the fit (result$C.signed) or from the presence of negative entries in C / XC. The basis X is always non-negative, so X \rightarrow Y edges are unaffected.
sig.level	Significance level for filtering C edges when inference results are available (i.e., x is of class "nmfkc.inference"). Only edges with p-value below sig.level are shown, decorated with significance stars (*, **, ***). Set to NULL to disable filtering and show all edges above threshold. Default is 0.1.
rankdir	Graphviz rank direction (e.g., "LR", "TB").
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 A \rightarrow X (type "YXA").
weight_scale_xy	Scaling factor for edges X \rightarrow Y.
weight_scale_ay	Scaling factor for edges A \rightarrow Y (type "YA").
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 TRUE (default), Y and A nodes that have no edges at or above threshold are excluded from the graph.

Value

A character string representing a Graphviz DOT script.

See Also

nmfkc, nmfae.DOT, nmf.sem.DOT, nmfkc.ar.DOT, plot.nmfkc.DOT

Examples

Y <- matrix(cars$dist, nrow = 1)
A <- rbind(1, cars$speed)
result <- nmfkc(Y, A, rank = 1)
dot <- nmfkc.DOT(result)
cat(dot)

nmfkc documentation built on July 14, 2026, 1:07 a.m.