Sum of Single Effects Regression using the RSS-lambda likelihood

Specialized interface for the regularized eigendecomposition RSS likelihood of Zou et al. (2022). This path accepts a single reference matrix or a single factor matrix and does not support multi-panel mixture, finite-reference inflation, or R-mismatch correction.

Usage

susie_rss_lambda(
  z = NULL,
  R = NULL,
  n = NULL,
  X = NULL,
  L = min(10, if (!is.null(R)) ncol(R) else ncol(X)),
  lambda,
  maf = NULL,
  maf_thresh = 0,
  prior_variance = 50,
  residual_variance = NULL,
  prior_weights = NULL,
  null_weight = 0,
  intercept_value = 0,
  estimate_residual_variance = FALSE,
  estimate_residual_method = "MLE",
  estimate_prior_variance = TRUE,
  estimate_prior_method = c("optim", "EM", "simple"),
  prior_variance_grid = NULL,
  mixture_weights = NULL,
  check_null_threshold = 0,
  prior_tol = 1e-09,
  residual_variance_lowerbound = 0,
  model_init = NULL,
  coverage = 0.95,
  min_abs_corr = 0.5,
  max_iter = NULL,
  L_greedy = NULL,
  greedy_lbf_cutoff = 0.1,
  tol = NULL,
  convergence_method = c("elbo", "pip"),
  verbose = FALSE,
  track_fit = FALSE,
  check_prior = TRUE,
  check_R = TRUE,
  check_z = FALSE,
  n_purity = 100,
  r_tol = 1e-08,
  refine = FALSE,
  init_only = FALSE,
  slot_prior = NULL
)

Arguments

z: A p-vector of z-scores.
R: A p by p correlation matrix. Exactly one of R or X must be provided.
n: The sample size, not required but recommended.
X: Optional factor matrix (B by p) such that R = crossprod(X) / nrow(X) approximates the correlation matrix R. The RSS-lambda path always builds the eigen decomposition via SVD of standardized X; there is no separate low-rank branch. Provide either R or X, not both.
L: Maximum number of non-zero effects in the model. If L is larger than the number of covariates, p, L is set to p.
lambda: Regularization parameter for the RSS-lambda likelihood. Must be supplied. lambda = "estimate" estimates lambda from the null-space residual.
maf: A p-vector of minor allele frequencies; to be used along with maf_thresh to filter input summary statistics.
maf_thresh: Variants with MAF smaller than this threshold are not used.
prior_variance: Prior variance for each non-zero effect on the z-score scale. Replaces scaled_prior_variance from susie_rss. Default 50.
residual_variance: Residual variance on the RSS-lambda scale. If NULL, it is initialized to 1 - lambda; if supplied, the working residual variance is residual_variance - lambda.
prior_weights: A vector of length p, in which each entry gives the prior probability that corresponding column of X has a nonzero effect on the outcome, y. The weights are internally normalized to sum to 1. When NULL (the default), uniform prior weights are used (each variable is assigned probability 1/p).
null_weight: Prior probability of no effect (a number between 0 and 1, and cannot be exactly 1).
intercept_value: Intercept used by the RSS-lambda likelihood. Default 0.
estimate_residual_variance: If TRUE, estimate the RSS-lambda residual variance by maximum likelihood.
estimate_residual_method: Variance-component estimator. The RSS-lambda path supports "MLE" only; any other value errors.
estimate_prior_variance: If estimate_prior_variance = TRUE, the prior variance is estimated (a separate parameter for each of the L effects). When TRUE, prior_variance provides the initial value; when FALSE, it is held fixed.
estimate_prior_method: The method used for estimating prior variance. When estimate_prior_method = "simple" is used, the likelihood at the specified prior variance is compared to the likelihood at a variance of zero, and the setting with the larger likelihood is retained. When prior_variance_grid is provided, this is automatically set to "fixed_mixture".
prior_variance_grid: Numeric vector of K prior variances defining a mixture-of-normals prior on effect sizes. When provided, the SER evaluates Bayes factors at each grid point and forms a mixture BF weighted by mixture_weights. This bypasses the scalar prior variance optimization. Default is NULL (standard scalar V path).
mixture_weights: Numeric vector of K non-negative weights summing to 1, giving the mixture proportions for the variance grid. Default is NULL, which uses uniform weights when prior_variance_grid is provided.
check_null_threshold: When the prior variance is estimated, compare its likelihood to the likelihood at zero and use zero unless the larger value exceeds it by at least check_null_threshold. 0 (default) takes the larger likelihood at face value.
prior_tol: When the prior variance is estimated, compare the estimated value to prior_tol at the end of the computation, and exclude a single effect from PIP computation if the estimated prior variance is smaller than this tolerance value.
residual_variance_lowerbound: Lower limit on the estimated residual variance. It is only relevant when estimate_residual_variance = TRUE.
model_init: A previous susie fit with which to initialize.
coverage: A number between 0 and 1 specifying the “coverage” of the estimated confidence sets.
min_abs_corr: Minimum absolute correlation allowed in a credible set. The default, 0.5, corresponds to a squared correlation of 0.25, which is a commonly used threshold for genotype data in genetic studies. This "purity" filter is applied to the CSs reported in the fit object, so the CS list returned here may be a subset of the one produced by calling susie_get_cs on the same fit without passing X or Xcorr (in which case the purity filter is skipped).
max_iter: Maximum number of IBSS iterations to perform. For susie_rss() and susie_rss_lambda(), NULL uses 50 with a hint; other interfaces use 100.
L_greedy: Integer or NULL. When non-NULL, run a greedy outer loop that grows the number of effects from L_greedy up to L in linear steps until the fit saturates. The default NULL runs the usual fixed-L fit.
greedy_lbf_cutoff: Numeric saturation threshold for the L_greedy outer loop. Default is 0.1.
tol: A small, non-negative number specifying the convergence tolerance for the IBSS fitting procedure. When NULL, the default is 1e-4; for estimate_residual_method = "NIG", the default is tightened to 1e-6.
convergence_method: When converge_method = "elbo" the fitting procedure halts when the difference in the variational lower bound, or “ELBO” (the objective function to be maximized), is less than tol. When converge_method = "pip" the fitting procedure halts when the maximum absolute difference in alpha is less than tol.
verbose: If verbose = TRUE, the algorithm's progress, a summary of the optimization settings, and refinement progress (if refine = TRUE) are printed to the console.
track_fit: If track_fit = TRUE, a compact susie_track object is returned in trace, containing alpha history, effect summaries and available diagnostics at each iteration of the IBSS fitting procedure.
check_prior: If check_prior = TRUE, it checks if the estimated prior variance becomes unreasonably large (comparing with 10 * max(abs(z))^2).
check_R: If TRUE, verify that R is positive semidefinite.
check_z: If TRUE, verify that z lies in the column space of R.
n_purity: Passed as argument n_purity to susie_get_cs.
r_tol: Tolerance level for eigenvalue check of positive semidefinite matrix XtX.
refine: If refine = TRUE, then an additional iterative refinement procedure is used, after the IBSS algorithm, to check and escape from local optima (see details).
init_only: Logical. If TRUE, return a list with data and params objects without running the IBSS algorithm. Default is FALSE.
slot_prior: Optional slot activity prior created by slot_prior_betabinom or slot_prior_poisson. Use slot_prior_betabinom(a_beta, b_beta) for the usual single-locus setting; it places a Beta-Binomial prior on the number of active effects and gives an adaptive multiplicity correction. Use slot_prior_poisson(C, nu) when you want a Gamma-Poisson prior centered on an expected number C of active effects. When supplied, each single-effect slot has an estimated activity probability c_hat; fitted values and PIPs are weighted by these activity probabilities, and convergence is checked using convergence_method = "pip".

Value

A "susie" fit (or, with init_only = TRUE, the constructed data and params objects).