nmfkc

release that is not three days from a submission.

The deprecated nmf.sem* names are removed

nmf.sem(), nmf.sem.inference(), nmf.sem.cv(), nmf.sem.split() and

nmf.sem.DOT() are gone, together with the six S3 methods registered on the

nmf.sem classes. Use nmf.ffb() and its family; the names map one to one and

nothing else changes, because the removed functions were pure forwarders

(nmf.sem <- function(...) { .Deprecated("nmf.ffb"); nmf.ffb(...) }).

They were deprecated in 0.8.8 (2026-07-14) and have emitted a .Deprecated()

note through two CRAN releases, 0.8.8 and 0.9.6. No package on CRAN depends on

nmfkc, so nothing else is affected.

Fitted objects no longer carry the legacy class: nmf.ffb() now returns

c("nmf.ffb", "nmf") rather than c("nmf.ffb", "nmf.sem", "nmf"), inference

results drop "nmf.sem.inference", nmf.ffb.DOT() drops "nmf.sem.DOT", and

summary() returns "summary.nmf.ffb" alone. **Code that tests for those class

strings, and objects saved by an earlier version, will no longer dispatch to

the nmf.sem methods** -- which is the point of removing them, but it is worth

knowing before loading an old .rds.

NMF-FFB: the help pages no longer describe options that were removed

C1.restriction accepted "block" and "cross" while the exclusion

restriction was being settled; both were dropped in 0.9.8 in favour of

"union", but the help pages and the vignette still described them and still

listed them as admissible values. They now describe only what the code accepts,

"union" and "none" (or a user matrix).

The wording of the restriction itself is also corrected. It was "an outcome may

not feed back into a factor on which it loads", which reads as if any non-zero

loading blocked the entry; the rule is "a factor on which it has more than a

negligible loading" -- the dominant factor of the outcome, plus every factor

whose loading reaches C1.restriction.threshold. Neither half alone is the

rule, and the help now says why. The vignette adds the reference for reading a

BIC difference as evidence (Kass and Raftery 1995, p. 777).

The NMF-GMM family is marked experimental again

nmf.gmm(), nmf.gmm.inference(), nmf.gmm.select(), nmf.gmm.twostage()

and the S3 methods on their classes say on their help pages that they are

experimental and still under development: argument names, defaults and the

contents of the returned objects are not yet stable. The vignette says so too.

The notice was removed in 0.9.7 on the reasoning that publishing on CRAN is a

commitment to a fixed interface. That reasoning was premature — the family is

still being developed alongside the paper — so the notice is back, and now

covers nmf.gmm.twostage() and the S3 methods, which it had missed. Nothing

else in the package carries the caveat.

Every restriction on X that is not a gauge fix is removed

X.rowSums.min (both fitters) and X.restriction = "rowSums"

(nmfkc.signed()) are gone. Both acted on the **rows** of X, which changes

X %*% C %*% A, so neither was a gauge fix: the scale they removed could not

be handed to C, they sat outside the multiplicative form, and the objective

was no longer monotone.

• The row-sum floor pushed the pinned rows below the floor and the projection lifted them back, so the objective alternated between two values until maxit (observed on Covertype at rank 6, 200,000 iterations).
• "rowSums" has the same defect in a milder form: on a 10x30 example the objective rose at 45 steps, every second step from the 49th on. The oscillation is small enough that the fit still meets epsilon and stops, but it descends by luck rather than by construction.

Both were added after the last CRAN release, so nothing on CRAN is affected.

"rowSums" is refused with a message rather than silently re-mapped to

"colSums", which would change results without saying so. The remaining

restrictions -- "colSums" (default), "colSqSums", "totalSum", "none",

"fixed" -- are all gauge fixes and leave the updates monotone.

Both fitters now return epsilon.iter (relative change at the last step) and

objfunc.increases (steps at which the objective rose), and print() /

summary() show them, so a fit that is oscillating rather than descending is

visible. nmfkc.signed()'s converged is now the stopping rule's own test

rather than iter < maxit, so a run that stopped early on a non-finite

objective is no longer reported as converged.

The two epsilon.iter are not the same quantity and should not be compared

across the two fitters: nmfkc() divides by max(|f_i|, 1) and nmfkc.signed()

by |f_{i-1}|. Each matches the stopping rule of its own fitter, and they agree

while the objective exceeds 1; below 1 nmfkc()'s test is effectively an

absolute one. Both are documented on the respective help pages.

NMF-FFB: names brought into line with the rest of the package

nmf.ffb() grew its own vocabulary while the likelihood estimator was being

built, and of the 55 fields on a fit only nine shared a name with an nmfkc()

fit -- two of those meaning something different. The names are now the

package's. **This is a breaking change**, confined to the likelihood branch and

its inference, all of which was added after the last CRAN release.

| was | is | why |

|:--|:--|:--|

| fit$Q | fit$rank | rank is the field on every other fitter |

| fit$MAE | fit$mae | likewise (the path / candidates **columns** stay MAE, beside BIC) |

| fit$objfunc (NULL) | fit$objfunc = the minimized negative log-likelihood | it was the one house field the fiml path left empty |

| fit$objfunc.full | fit$objfunc.penalized | it is the penalized objective, unrelated to the full fit |

| mask = (argument) | C1.restriction = | mirrors X.restriction; the argument and the field of the same name held different things |

| fit$mask (matrix) | fit$C1.free | it marks the entries left **free**, and the argument mask was a rule string |

| fit$mask.rule | fit$C1.restriction | the field now means what the argument means |

| cross.threshold | C1.restriction.threshold | it parameterizes the restriction, so it shares its prefix |

| phi =, fit$phi | Phi.restriction | phi and Phi differed only in case |

| lambda1 | C1.L1.path | the L1 penalty on C1, as a path; fit$path$C1.L1 is one value of it |

| lambda1.selected | C1.L1.selected | |

| ci.level | boot.level | the confidence level of the bootstrap, as wild.level elsewhere |

| bootstrap.B, .threshold, .ci.level, .n.valid, .n.invalid, .type | boot.B, boot.threshold, boot.level, boot.n.valid, boot.n.invalid, boot.method | boot.method is the house name |

| C1.array, C2.array | C1.boot.draws, C2.boot.draws | as C.boot.draws in nmfkc.inference() |

| rho.boot | rho.boot.draws | |

| mask.change.rate | C1.restriction.change.rate | |

| calibration = "full" | calibration = "procedure" | "full" already named the unrestricted feedback fit |

| plot(fit, which = "full") | which = "penalized" | same reason |

| coefficients$p_value | (removed; use prob.unsupported) | it held 1 - support_rate, which is not a p-value |

| nmf.ffb.diagnostics()$top$rank | $top$order | rank now means the number of factors |

Three defects surfaced while doing this, all of them silent until now.

• nmf.ffb(C1.L1 = , C2.L1 = ) had **no effect at all** under the default method = "fiml": the arguments were accepted and never forwarded. They belong to the multiplicative updates; the likelihood path penalizes C1 along C1.L1.path and leaves C2 unpenalized. Passing them to a fiml fit now warns. Same in nmf.ffb.inference().
• fit$maxit held the **stage-2** cap while the maxit argument set the **stage-1** one, and print() paired stage 2's iteration count with stage 1's epsilon (87 / 3000 epsilon = 1e-06 -- three numbers from two different optimizers). iter, maxit, epsilon now describe stage 1, as the arguments of those names do; stage 2 is fiml.iter, fiml.maxit, factr, fiml.converged; and converged is TRUE only if both stages converged. print() shows both.
• plot() on a method = "fiml" fit failed inside sprintf(). A fiml fit has no iteration trace to draw (its optimizer is L-BFGS-B), so it now says so and names what to use instead.

Options withdrawn in 0.9.8 (starts, nsplit, calibration as an argument of

the fit) reached ... and were dropped without a word; they now warn. A

**renamed** argument is worse than a withdrawn one -- mask = "none" would be

dropped and the fit would silently use the default restriction, the opposite of

the request -- so the four renamed arguments stop with the new name instead.

NMF-FFB is the canonical name everywhere, NMF-SEM the alias

The nmf.sem* functions have been deprecated aliases of nmf.ffb* for some

time, but the rest of the package had not followed:

• the tutorial was vignettes/nmf-sem-with-nmfkc.Rmd and the engine file R/nmf.sem.R; they are now nmf-ffb-with-nmfkc.Rmd and R/nmf.ffb.R;
• **the six S3 methods were registered on nmf.sem, not on nmf.ffb** -- summary(), plot(), coef(), fitted(), residuals() and print.summary() -- so the deprecated name was the one dispatch resolved against and ?summary.nmf.sem was the page a user landed on. They are now defined on nmf.ffb, and the nmf.sem methods are one-line aliases collected at the end of R/nmf.sem-deprecated.R, so that removing nmf.sem later means removing one file. An object saved by a version that wrote only c("nmf.sem", "nmf"), and a summary object of class "summary.nmf.sem", still dispatch;
• nmf.ffb.DOT() tagged its result c("nmf.sem.DOT", "nmfkc.DOT"); the leading class is now "nmf.ffb.DOT".

The fitted object still carries c("nmf.ffb", "nmf.sem", "nmf"), and the

deprecated functions still work and still say so. The tutorial now also shows

the exclusion restriction (fit$C1.restriction, fit$C1.free), the BIC path

that plot() draws, and the two-stage convergence line.

NMF-FFB: one function per step of the procedure

The feedback model is now driven by four functions, one for each step, instead

of two that each did several things:

```r

ecv <- nmf.ffb.ecv(Y1, Y2, rank = 1:5) # 1. choose Q by element-wise CV

fit <- nmf.ffb(Y1, Y2, rank = Q) # 2. estimate; BIC selects the support

tst <- nmf.ffb.test(fit, Y1, Y2) # 3. test the feed-forward null

dgn <- nmf.ffb.diagnostics(fit) # 4. cycles, spectral radius, best supports

inf <- nmf.ffb.inference(fit, Y1, Y2) # 5. intervals for the retained entries

```

• **New** nmf.ffb.test(): the calibrated test of the feed-forward null. It runs the null bootstrap only, and returns LR.p.boot, the null quantiles, the null false-selection rate prob.select.null and, for the default calibration, C1.restriction.change.rate. Replicates run in parallel with cores = as elsewhere in the package.
• **New** nmf.ffb.ecv(): choosing *Q* under the name that says what it does. nmf.ffb.cv(method = "fiml") has delegated to element-wise CV since 0.9.8; the old name still works and is kept for the multiplicative-update path.
• **Breaking** nmf.ffb.inference() no longer runs the null bootstrap and no longer returns LR.boot, LR.p.boot, LR.null.quantile, prob.select.null, LR.boot.*, C1.restriction.change.rate, split.table or bootstrap.calibration; its calibration and nsplit arguments are gone. Use nmf.ffb.test(). An intervals object that also carried a *p*-value for the presence of feedback invited the reader to treat an interval that excludes zero as evidence for the entry, which it is not. This affects only the likelihood branch (method = "fiml"), which was added after the last release.
• nmf.ffb.diagnostics() now also reports the three best distinct supports with their differences in BIC, the entries common to all of them, their envelope, and whether they form a chain under inclusion. A difference in BIC below about 2 is not evidence for one support over another (Kass and Raftery 1995), so the presence of feedback can be settled while its composition is not.

Options removed

Measurement, not taste, decided each of these; keeping them invited the reader

to compare procedures as if they were equally valid.

• nmf.ffb(starts = ) is gone. Every penalized fit is warm-started from the unpenalized full-feedback fit. The three alternative starting points measured on six data sets never uniquely attained the minimum BIC.
• calibration (now an argument of nmf.ffb.test()) keeps "procedure" (the default: stage 1 and the exclusion restriction re-estimated in every null replicate) and "conditional" (valid only when the basis and the restriction come from outside the data being tested, and selected automatically in that case). The two sample-splitting levels are gone: "split" fixes the basis of the estimation half and is anti-conservative, and "split-full" is valid but strictly dominated by "procedure" -- same size, lower power, and it needs a large *N*.
• C1.restriction keeps "union" (an outcome may not feed back into a factor on which it loads) and "none", plus a user-supplied matrix. The partial rules "block" and "cross" were kept for comparison and are neither the rule of the paper nor useful on their own.

The feedback test: what the bootstrap conditions on, and two fixes

The parametric bootstrap that calibrates the feedback LR statistics used to

hold the estimated basis X and the exclusion restriction fixed at their

observed values while regenerating Y1*. Both are functions of Y1, so the

null distribution omitted the adaptivity of that selection and the p-values

were anti-conservative: on the two positive examples of the NMF-FFB paper the

fixed-basis bootstrap gives p < 0.001, re-running stage 1 on every replicate

gives p = 0.05 and 0.35, and the exclusion restriction turns out to move in

40% and 95% of the null replicates. nmf.ffb.test() therefore has a

calibration argument with two levels:

• "procedure" (default): stage 1 and the restriction are re-estimated on every replicate (one nmfkc() fit per replicate), so the p-value is the operating characteristic of the whole exploratory procedure. Returns C1.restriction.change.rate, the share of replicates whose restriction moved, and LR.boot.df.
• "conditional": stage 2 only, basis and restriction fixed (the pre-0.9.8 behaviour). Valid only if they came from data independent of Y1; labelled as conditional in print(), and selected automatically when the fit used a basis or a restriction supplied by the caller.

Two fixes in the same code. LR.p.boot is now (1 + #)/(1 + B_ok) instead of

the raw proportion, which was exactly 0 whenever no replicate reached the

observed statistic (the normal case for a strongly significant fit, and not a

valid p-value); the floor 1/(1 + B_ok) is printed as < floor. And the

L-BFGS-B convergence codes of the null replicates are no longer discarded:

LR.boot.n.nonconv reports how many missed the tolerance and a warning is

raised above 10%, because on a flat null likelihood (small N, full Phi) the

share can reach 40% and must be visible to the user.

nmf.ffb(): exclusion restriction "union" (new default)

`C