Skip to contents

Methods for fitting single effect regression (SER) models and computing posterior statistics from summary data. Typically the model fitting involves estimating parameters in the prior (“hyperparameters”) by maximizing the likelihood, but potentially other parameters could be estimated as well. The ‘fit_ser_model’ method is the main method for fitting SER models and returning key posterior statistics. SER models are implemented as a modular (“object-oriented”) interface, allowing for different types of SER families (see ‘Details’ for a general specification of SER classes).

Usage

init_ser_model(
  variable.names,
  family = "normal",
  prior = list(prob = 1/length(variable.names), prior_variance = 1),
  init_method = "null",
  control = list()
)

init_ser_model_normal(
  variable.names,
  prior = list(prob = 1/length(variable.names), prior_variance = 1),
  init_method = c("null", "random"),
  control = list()
)

fit_ser_model(fit, dat, return_data = missing(dat), ...)

# S3 method for class 'ser_normal'
fit_ser_model(fit, dat, return_data = missing(dat), ...)

ser_normal_control_default()

prepare_ser_data(bhat, shat, X, y, residual_variance = 1)

Arguments

variable.names

The names of the variables in the SER model.

family

The SER family. See “Details” for more information.

prior

An object, possibly a list, specifying the SER prior. The exact form of this input will depend on which SER model is used. See ‘Details’ for further information.

init_method

Posterior statistics need to be in SER model fits at all times, even if they are just initial guesses. This argument specifies how the initial guess is obtained.

control

An object, possibly a list, specifying settings that affect the model fitting. See ‘Details’ for further information.

fit

An object of class ‘ser’ that captures the state of an SER model fit, typically the output from running an ‘init_ser_model’ function, or an output from a previous fit_ser_model call.

dat

An object of class ‘ser_data’, such as the output from a call to prepare_ser_data.

return_data

If return_data = TRUE, the input data are included in the output.

...

Additional arguments controlling the model fitting.

bhat

A vector of least-squares estimates of the coefficients.

shat

A vector of variances of the least-squares estimates.

X

A matrix of with rows corresponding to observations (samples) and columns corresponding to candidate explanatory variables.

y

A vector of regression outcomes.

residual_variance

The residual variance parameter which is used to compute the the outputted statistics. This is only used when X, y are provided instead of bhat, shat.

Value

init_ser_model and fit_ser_model return objects of class ‘ser’ storing key posterior statistics for all variables and the state of the SER model fit. It is a list with the following elements:

prior

Data structure specifying the prior. This may include hyperparameters that change during model fitting.

posterior

A data frame with one row per variable and the following columns: ‘lbf’, the log-Bayes factor; ‘PIP’, the posterior inclusion probability; ‘mean’, the posterior mean of the regression coefficient; ‘var’, the posterior variance of the regression coefficient.

lbf

Log-Bayes factor comparing the SER model to the “null” model (b = 0).

KL

Kullback-Leibler divergence between the SER posterior distribution and the SER prior.

progress

A data frame containing detailed information about the progress on the model fitting.

local

Logical specifying whether one or more parameters may be estimated “locally” (that is, they are estimated separately in this SER).

global

Logical specifying whether one or more parameters may be estimated “globally” (that is, they are estimated simultaneously in multiple SERs). This is used when the SER model is used as a building block for another model such as a SuSiE model.

control

A data structure, likely a list, containing the settings that affect how the model fitting is conducted.

dat

When return_data = TRUE, this contains the data that were used to fit the model.

prepare_ser_data returns a data frame with two columns: ‘bhat’, the least-squares estimates of the coefficients; ‘shat’, the variances of these estimates. See ‘Details’ for precise definitions of these terms.

Details

A single effect regression (SER) model is a Bayesian multiple regression model in which only a single candidate variable is active (“included”). Therefore, the posterior distribution becomes a “mixture” of simpler single-variable regression models.

The first element of an SER model is a multiple regression model of an outcome y, $$y = Xb + e,$$ where \(e\) is a vector of independent, normally distributed error terms, \(e \sim N(0, \sigma^2 I)\). The residual variance \(\sigma^2\) is assumed to be known.

The second element of a an SER model is an SER prior on the coefficients vector \(b\). An SER prior has the property that any \(b\) drawn from the prior has exactly one nonzero coefficient. For example, the SER model initialized by init_ser_model_normal() defines a prior in which coefficient \(j\) is nonzero with prior probability \(\pi_j\), and the nonzero coefficient is assigned a normal prior with zero mean and a variance \(\sigma_0^2\) which may be estimated. Because the SER posterior reduces to a mixture of single-variable regression models, the sufficient statistics needed to compute the posterior are the same as the sufficient statistics needed to compute the posterior under each single-variable model, such as the least-squares estimate of each coefficient and its variance.

The key steps of an analysis with a single effect regression are: (i) prepare the data using the prepare_ser_data function; (ii) initialize the SER model using the init_ser_data function; and (iii) fit the model and compute posterior statistics from the fitted model using the fit_ser_data function.

Design of single effect regression classes. A “single effect regression” (SER) class has at a minimum the following three elements:

  1. A function that initializes the SER model (e.g., init_ser_model_normal). It returns an ‘ser’ model.

  2. A ‘fit_ser_model’ method that takes (at least) two inputs, an ‘ser’ model and an ‘ser_data’ data set. It returns an updated SER model (object of class ‘ser’).

  3. A ‘variable.names’ method that returns the variable names.

Note

This is a lightweight interface with relatively few features and few checks; it is mainly used to implement the susie methods.

In prepare_set_data, only provide (bhat, shat) or (X, y); an error will occur if the wrong combination of data are provided.

See also

Examples

# TO DO: Add one or several examples.