Used in a flash
pipeline to set the output that will be printed
after each greedy or backfitting iteration.
flash_set_verbose(
flash,
verbose = 1L,
fns = NULL,
colnames = NULL,
colwidths = NULL
)
A flash
or flash_fit
object.
When and how to display progress updates. Set to 0
for no updates; 1
for updates after a "greedy" factor is added or
a backfit is completed; 2
for additional notifications about the
variational lower bound (ELBO); and 3
for updates after every
iteration. By default, per-iteration update information includes the
change in ELBO and the maximum (absolute) change over all L2-normalized
loadings \(\ell_1, \ldots, \ell_K\) and factors \(f_1, \ldots, f_K\).
Update information is customizable via parameters fns
,
colnames
, and colwidths
.
A single tab-delimited table of values may also be output using
option verbose = -1
. This format is especially convenient for
downstream analysis of the fitting history. For example, it may be used
to plot the value of the ELBO after each iteration (see the "Advanced
Flashier" vignette for an illustration).
A vector of functions. Used to calculate values to display
after each greedy/backfit iteration when verbose
is either -1 or 3
(see Details below). Ignored for other values of verbose
(0, 1, or 2).
A vector of column names, one for each function in
fns
.
A vector of column widths, one for each function in
fns
.
The flash
object from argument flash
, with the
new verbose settings reflected in updates to the "internal"
flash_fit
object. These settings will persist across
all subsequent calls to flash_xxx
functions until they are modified
by another call to flash_set_verbose
.
Function flash_set_verbose
can be used to customize
the output that is printed to console while fitting a flash
object.
After each greedy or backfitting iteration (see, respectively,
flash_greedy
and flash_backfit
), each
function in argument fns
is successively evaluated and the
result is printed to console in a table with column names defined by
argument colnames
and column widths defined by argument
colwidths
.
Each function in fns
must accept exactly three parameters,
curr
, prev
, and k
: curr
refers to the
flash_fit
object from the current iteration; prev
,
to the flash_fit
object from the previous iteration;
and, if the iteration is a sequential backfitting iteration (that is, a
flash_backfit
iteration with argument
extrapolate = FALSE
), k
identifies the factor/loadings pair
that is currently being updated (in all other cases, k
is
NULL
). Package flashier
provides a number of functions that
may be used to customize output: see
flash_verbose_elbo
,
flash_verbose_elbo_diff
,
flash_verbose_max_chg
,
flash_verbose_max_chg_L
, and
flash_verbose_max_chg_F
. Custom functions may also be
defined. They might inspect the current flash_fit
object
via argument curr
; compare the fit in curr
to the fit from the
previous iteration (provided by argument prev
); or
ignore both flash_fit
objects entirely (for example, to
track progress over time, one might simply call Sys.time
).
To facilitate working with flash_fit
objects, package
flashier
provides a number of accessors, which are enumerated in
the documentation for object flash_fit
. Custom functions
should return a character string that contains the output exactly as it is
to displayed; see Examples below.
# Suppress all verbose output.
fl <- flash_init(gtex) |>
flash_set_verbose(0) |>
flash_greedy(Kmax = 5)
# Set custom verbose output.
sparsity_F <- function(curr, prev, k) {
g_F <- flash_fit_get_g(curr, n = 2)
g_F_pi0 <- g_F$pi[1] # Mixture weight of the "null" component.
return(g_F_pi0)
}
verbose_fns <- c(flash_verbose_elbo, flash_verbose_max_chg_F, sparsity_F)
colnames <- c("ELBO", "Max Chg (Tiss)", "Sparsity (Tiss)")
colwidths <- c(12, 18, 18)
fl <- flash_init(gtex) |>
flash_set_verbose(
verbose = 3,
fns = verbose_fns,
colnames = colnames,
colwidths = colwidths
) |>
flash_greedy(Kmax = 3)
#> Adding factor 1 to flash object...
#> Optimizing factor...
#> Iteration ELBO Max Chg (Tiss) Sparsity (Tiss)
#> 1 -86179.13 4.58e-04 2.67e-07
#> 2 -86178.93 2.79e-05 2.70e-07
#> 3 -86178.93 1.11e-06 2.70e-07
#> Factor successfully added. Objective: -86178.931
#> Adding factor 2 to flash object...
#> Optimizing factor...
#> Iteration ELBO Max Chg (Tiss) Sparsity (Tiss)
#> 1 -85148.21 6.87e-03 8.13e-03
#> 2 -85147.47 4.37e-03 1.41e-02
#> 3 -85147.34 3.15e-03 1.70e-02
#> 4 -85147.29 2.23e-03 1.87e-02
#> 5 -85147.26 1.58e-03 1.98e-02
#> 6 -85147.25 1.12e-03 2.06e-02
#> 7 -85147.25 7.90e-04 2.11e-02
#> 8 -85147.25 5.60e-04 2.15e-02
#> 9 -85147.25 3.97e-04 2.17e-02
#> 10 -85147.25 2.83e-04 2.19e-02
#> Factor successfully added. Objective: -85147.246
#> Adding factor 3 to flash object...
#> Optimizing factor...
#> Iteration ELBO Max Chg (Tiss) Sparsity (Tiss)
#> 1 -84374.20 2.21e-02 1.90e-01
#> 2 -84369.21 1.73e-02 2.26e-01
#> 3 -84366.35 1.53e-02 2.47e-01
#> 4 -84364.24 1.66e-02 2.69e-01
#> 5 -84362.26 1.97e-02 3.04e-01
#> 6 -84359.99 1.86e-02 3.47e-01
#> 7 -84357.84 2.01e-02 3.84e-01
#> 8 -84356.24 1.76e-02 4.10e-01
#> 9 -84355.29 8.89e-03 4.23e-01
#> 10 -84354.82 7.69e-03 4.29e-01
#> 11 -84354.54 6.48e-03 4.31e-01
#> 12 -84354.35 5.49e-03 4.34e-01
#> 13 -84354.21 4.71e-03 4.36e-01
#> 14 -84354.11 4.11e-03 4.39e-01
#> 15 -84354.02 3.65e-03 4.42e-01
#> 16 -84353.95 3.52e-03 4.45e-01
#> 17 -84353.88 3.42e-03 4.49e-01
#> 18 -84353.83 3.28e-03 4.52e-01
#> 19 -84353.78 3.08e-03 4.56e-01
#> 20 -84353.74 2.82e-03 4.59e-01
#> 21 -84353.70 2.51e-03 4.63e-01
#> 22 -84353.67 2.17e-03 4.66e-01
#> 23 -84353.64 1.96e-03 4.69e-01
#> 24 -84353.62 1.76e-03 4.71e-01
#> 25 -84353.61 1.57e-03 4.73e-01
#> 26 -84353.59 1.37e-03 4.75e-01
#> 27 -84353.58 1.19e-03 4.76e-01
#> 28 -84353.58 1.02e-03 4.78e-01
#> 29 -84353.57 8.62e-04 4.78e-01
#> 30 -84353.57 7.27e-04 4.79e-01
#> 31 -84353.57 6.09e-04 4.80e-01
#> 32 -84353.57 5.08e-04 4.80e-01
#> 33 -84353.57 4.22e-04 4.81e-01
#> 34 -84353.57 3.50e-04 4.81e-01
#> 35 -84353.57 2.90e-04 4.82e-01
#> Factor successfully added. Objective: -84353.565
#> Wrapping up...
#> Done.
# Output can be changed as needed.
fl <- flash_init(gtex) |>
flash_set_verbose(verbose = 1) |>
flash_greedy(Kmax = 5L) |>
flash_backfit(verbose = 3) |>
flash_greedy(Kmax = 1L)
#> Adding factor 1 to flash object...
#> Adding factor 2 to flash object...
#> Adding factor 3 to flash object...
#> Adding factor 4 to flash object...
#> Adding factor 5 to flash object...
#> Wrapping up...
#> Done.
#> Backfitting 5 factors (tolerance: 6.56e-04)...
#> Iteration Factor ELBO Diff LF Max Chg
#> 1 all 6.73e+01 4.12e-02
#> 2 all 4.36e+01 5.00e-02
#> 3 all 3.76e+01 6.95e-02
#> 4 all 2.02e+01 6.23e-02
#> 5 all 2.85e+00 4.32e-02
#> 6 all 7.42e+00 6.01e-02
#> 7 all 1.44e+00 7.02e-02
#> 8 all 4.77e+00 6.20e-02
#> 9 all 4.62e+00 1.09e-02
#> 10 all 1.87e+00 1.54e-02
#> 11 all 6.74e-01 2.00e-02
#> 12 all 1.70e-01 3.78e-03
#> 13 all 7.57e-02 3.90e-03
#> 14 all 3.06e-02 3.08e-03
#> 15 all 1.17e-02 2.29e-03
#> 16 all 2.52e-03 2.52e-04
#> 17 all 1.79e-03 3.24e-04
#> 18 all 1.23e-03 3.79e-04
#> 19 all 8.99e-04 4.18e-04
#> 20 all 1.71e-04 9.81e-05
#> Backfit complete. Objective: -82938.956
#> Wrapping up...
#> Done.
#> Adding factor 6 to flash object...
#> Wrapping up...
#> Done.