flash_ebnm: Construct an EBNM function

Description

flash_ebnm is a helper function that provides readable syntax for constructing ebnm functions that can serve as arguments to parameter ebnm_fn in functions flash, flash_greedy, and flash_factors_init (see Examples below). It is also possible to write a custom function from scratch: see Details below for a simple example. A more involved example can be found in the "Advanced flashier" vignette.

Usage

flash_ebnm(...)

Value

A function that can be passed as argument to parameter

ebnm_fn in functions flash,

flash_greedy, and flash_factors_init.

Arguments

...: Parameters to be passed to function ebnm in package ebnm. An argument to prior_family should be provided unless the default family of point-normal priors is desired. Arguments to parameters x, s, or output must not be included. Finally, if g_init is included, then fix_g = TRUE must be as well. To fix a prior grid, use parameter scale rather than g_init.

Details

As input to parameter ebnm_fn in functions flash, flash_greedy, and flash_factors_init, it should suffice for many purposes to provide functions from package ebnm as is (for example, one might set ebnm_fn = ebnm_point_laplace). To use non-default arguments, function flash_ebnm may be used (see Examples). Custom functions may also be written. In general, any function that is used as an argument to ebnm_fn must accept parameters:

x

A vector of observations.

s

A vector of standard errors, or a scalar if all standard errors are equal.

g_init

The prior \(g\). Usually, this is left unspecified (NULL) and estimated from the data. If it is supplied and fix_g = TRUE, then the prior is fixed at g_init; if fix_g = FALSE, then g_init gives the initial value of \(g\) used during optimization.

In flashier, \(g\) is fixed during the wrap-up phase when estimating local false sign rates and constructing a sampler; and g_init is used with fix_g = FALSE to "warmstart" backfits (see flash_backfit). If none of these features (local false sign rates, samplers, or warmstarts) are needed, then both g_init and fix_g can be ignored (the EBNM function must still accept them as parameters, but it need not do anything with their arguments).

fix_g

If TRUE, the prior is fixed at g_init instead of estimated. See the description of g_init above.

output

A character vector indicating which values are to be returned. Custom EBNM functions can safely ignore this parameter (again, they must accept it as a parameter, but they do not need to do anything with its argument).

The return object must be a list that includes fields:

posterior: A data frame that includes columns mean and second_moment (the first and second moments for each posterior distribution \(p(\theta_i \mid s_i, \hat{g}), i = 1, ..., n\)). Optionally, a column lfsr giving local false sign rates may also be included.
fitted_g: The estimated prior \(\hat{g}\). Within flashier, fitted_g is only ever used as an argument to g_init in subsequent calls to the same EBNM function, so the manner in which it is represented is unimportant.
log_likelihood: The optimal log likelihood \(L(\hat{g}) := \sum_i \log p(x_i \mid \hat{g}, s_i)\).
posterior_sampler: An optional field containing a function that samples from the posterior distributions of the "means" \(\theta_i\). If included, the function should take a single parameter nsamp and return a matrix where rows correspond to samples and columns correspond to observations (that is, there should be nsamp rows and \(n\) columns).

Examples

Run this code

# A custom EBNM function might be written as follows:
my_ebnm_fn <- function(x, s, g_init, fix_g, output) {
  ebnm_res <- ebnm_point_laplace(
    x = x,
    s = s,
    g_init = g_init,
    fix_g = fix_g,
    output = output,
    control = list(iterlim = 10)
  )
  return(ebnm_res)
}

# The following are equivalent:
fl1 <- flash(
  gtex,
  ebnm_fn = my_ebnm_fn,
  greedy_Kmax = 2
)
fl2 <- flash(
  gtex,
  ebnm_fn = flash_ebnm(
    prior_family = "point_laplace",
    control = list(iterlim = 10)
  ),
  greedy_Kmax = 2
)