Fitting Single Effect Regression Models
Source:R/single_effect_regression.R
single_effect_regression.RdMethods 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_modelcall.- 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:
A function that initializes the SER model (e.g.,
init_ser_model_normal). It returns an ‘ser’ model.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’).
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.