Package 'ebnm'

The fitted ebnm object.

Not used. Included for consistency as an S3 method.

The fitted ebnm object.

A vector of numeric indices specifying which means $\theta_i$ are to be given confidence intervals. If missing, all observations are considered.

The "confidence level" $1 - \alpha$ desired.

The number of samples to use to estimate confidence intervals.

Additional arguments to be passed to the posterior sampler function. Since ebnm_horseshoe returns an MCMC sampler, it takes parameter burn, the number of burn-in samples to discard. At present, no other samplers take any additional parameters.

A vector of observations. Missing observations (NAs) are not allowed.

A vector of standard errors (or a scalar if all are equal). Standard errors may not be exactly zero, and missing standard errors are not allowed. Two prior families have additional restrictions: when horseshoe priors are used, errors must be homoskedastic; and since function deconv in package deconvolveR takes $z$-scores, the "deconvolver" family requires that all standard errors be equal to 1.

A character string that specifies the prior family $G$. See Details below.

A scalar specifying the mode of the prior $g$ or "estimate" if the mode is to be estimated from the data. This parameter is ignored by the NPMLE, the deconvolveR family, and the improper uniform (or "flat") prior. For generalized binary priors, which are bimodal, the mode parameter specifies the mode of the truncated normal component (the location of the point mass is fixed at zero).

A scalar or vector specifying the scale parameter(s) of the prior or "estimate" if the scale parameters are to be estimated from the data. This parameter is ignored by the flat prior and the family of point mass priors.

The interpretation of scale depends on the prior family. For normal and point-normal families, it is a scalar specifying the standard deviation of the normal component. For point-Laplace and point-exponential families, it is a scalar specifying the scale parameter of the Laplace or exponential component. For the horseshoe family, it corresponds to $s\tau$ in the usual parametrization of the horseshoe distribution. For the family of generalized binary priors, it specifies the ratio of the (untruncated) standard deviation of the normal component to its mode. This ratio must be fixed in advance (i.e., argument "estimate" is unavailable for generalized binary priors). For the NPMLE and deconvolveR prior family, scale is a scalar specifying the distance between successive means in the grid of point masses or normal distributions used to estimate $g$. For all other prior families, which are implemented using the function ash in package ashr, it is a vector specifying the parameter mixsd to be passed to ash or "estimate" if mixsd is to be chosen by ebnm. (Note that ebnm chooses mixsd differently from ash: see functions ebnm_scale_normalmix, ebnm_scale_unimix, and ebnm_scale_npmle for details. To use the ash grid, set scale = "estimate" and pass in gridmult as an additional parameter. See ash for defaults and details.)

The prior distribution $g$. Usually this is left unspecified (NULL) and estimated from the data. However, it can be used in conjuction with fix_g = TRUE to fix the prior (useful, for example, to do computations with the "true" $g$ in simulations). If g_init is specified but fix_g = FALSE, g_init specifies the initial value of $g$ used during optimization. For non-parametric priors, this has the side effect of fixing the mode and scale parameters. If g_init is supplied, it should be an object of class normalmix for normal, point-normal, scale mixture of normals, and deconvolveR prior families, as well as for the NPMLE; class laplacemix for point-Laplace families; class gammamix for point-exponential families; class horseshoe for horseshoe families; class unimix for unimodal_ families; or class tnormalmix for generalized binary priors. An object of class ebnm can also be supplied as argument, provided that field fitted_g contains a prior of the correct class (see Examples below).

If TRUE, fix the prior $g$ at g_init instead of estimating it.

A character vector indicating which values are to be returned. Function ebnm_output_default() provides the default return values, while ebnm_output_all() lists all possible return values. See Value below.

A string specifying which optimization function is to be used.

For parametric families other than the horseshoe and generalized binary (normal, point-normal, point-Laplace, and point-exponential), options include "nlm" (which calls nlm), "lbfgsb" (which calls optim with method = "L-BFGS-B"), and "trust" (which calls into the trust package). Other options are "nohess_nlm", "nograd_nlm", and "nograd_lbfgsb", which use numerical approximations rather than exact expressions for the Hessian; both of the "nograd" functions use numerical approximations for the gradient as well. The default option is "nohess_nlm".

Since the horseshoe, generalized binary, and point mass families only require one parameter to be estimated (at most), the only available optimization method is optimize, and thus the optmethod parameter is ignored by ebnm_horseshoe, ebnm_generalized_binary, and ebnm_point_mass.

For most nonparametric families (scale mixtures of normals; unimodal, symmetric unimodal, nonnegative unimodal, and nonpositive unimodal families; and the NPMLE), optmethod options are provided by package ashr. The default method uses the mix-SQP algorithm implemented in the mixsqp package. See the ash function documentation for other options. For the NPMLE only, it is also possible to specify optmethod = "REBayes", which uses function GLmix in the REBayes package to estimate the NPMLE rather than using the ashr package. Note that REBayes requires installation of the commercial interior-point solver MOSEK; for details, see the documentation for REBayes function KWDual.

The nonparametric exception is the the "deconvolveR" family. Since the deconvolveR package only ever uses nlm, ebnm_deconvolver ignores the optmethod parameter.

A list of control parameters to be passed to the optimization function specified by parameter optmethod.

Additional parameters. When a unimodal_ prior family is used, these parameters are passed to function ash in package ashr. Although it does not call into ashr, the scale mixture of normals family accepts parameter gridmult for purposes of comparison. When gridmult is set, an ashr-style grid will be used instead of the default ebnm grid. When the "deconvolver" family is used, additional parameters are passed to function deconv in package deconvolveR. Families of generalized binary priors take several additional parameters; see ebnm_generalized_binary. In all other cases, additional parameters are ignored.

The fitted ebnm object.

A vector of observations. Missing observations (NAs) are not allowed.

A vector of standard errors (or a scalar if all are equal). Standard errors may not be exactly zero, and missing standard errors are not allowed.

Passed to ash as parameter mode.

Passed to ash as parameter mixsd.

Passed to ash as parameter g.

Passed to ash as parameter fixg.

A character vector indicating which values are to be returned. Function ebnm_output_default() provides the default return values, while ebnm_output_all() lists all possible return values. See Value below.

Passed to ash as parameter control.

Additional parameters to be passed to ash.

The function to be checked.

A test set (vector) of observations.

A test set of standard errors. Typically, ebnm-style functions should be able to accept a vector of standard errors or a scalar if all standard errors are identical. This is not always the case; for example, the horseshoe prior family requires homoskedastic standard errors.

A vector of observations. Missing observations (NAs) are not allowed.

Standard errors, which must be uniformly equal to 1 (i.e., s = 1) since the deconvolveR method takes $z$-scores as input.

A deconvolveR prior is a finite mixture of point masses

$\pi_1 \delta_{\mu_1} + \ldots + \pi_K \delta_{\mu_K},$

where parameters $\pi_k$ are estimated and the point masses are evenly spaced over $(\mu_1, \mu_K)$.The distance between successive point masses can be specified by the user via parameter scale, in which case the argument should be a scalar specifying the distance $d = \mu_2 - \mu_1 = \cdots = \mu_K - \mu_{K - 1}$; alternatively, if scale = "estimate", then ebnm sets the grid via function ebnm_scale_npmle.

The prior distribution $g$. Usually this is left unspecified (NULL) and estimated from the data. However, it can be used in conjuction with fix_g = TRUE to fix the prior (useful, for example, to do computations with the "true" $g$ in simulations). If g_init is specified but fix_g = FALSE, g_init specifies the initial value of $g$ used during optimization. This has the side effect of fixing the scale parameter. When supplied, g_init should be an object of class normalmix or an ebnm object in which the fitted prior is an object of class normalmix.

If TRUE, fix the prior $g$ at g_init instead of estimating it.

A character vector indicating which values are to be returned. Function ebnm_output_default() provides the default return values, while ebnm_output_all() lists all possible return values. See Value below.

A list of control parameters to be passed to optimization function nlm.

Additional parameters to be passed to function deconv in package deconvolveR.

A vector of observations. Missing observations (NAs) are not allowed.

A vector of standard errors (or a scalar if all are equal). Standard errors may not be exactly zero, and missing standard errors are not allowed.

Not used by ebnm_flat, but included for consistency with other ebnm functions.

Not used by ebnm_flat, but included for consistency with other ebnm functions.

A character vector indicating which values are to be returned. Function ebnm_output_default() provides the default return values, while ebnm_output_all() lists all possible return values. See Value below.

A vector of observations. Missing observations (NAs) are not allowed.

A vector of standard errors (or a scalar if all are equal). Standard errors may not be exactly zero, and missing standard errors are not allowed.

A scalar specifying the mode of the truncated normal component, or "estimate" if the mode is to be estimated from the data (the location of the point mass is fixed at zero).

A scalar specifying the ratio of the (untruncated) standard deviation of the normal component to its mode. This ratio must be fixed in advance (i.e., it is not possible to set scale = "estimate" when using generalized binary priors).

The prior distribution $g$. Usually this is left unspecified (NULL) and estimated from the data. However, it can be used in conjuction with fix_g = TRUE to fix the prior (useful, for example, to do computations with the "true" $g$ in simulations). If g_init is specified but fix_g = FALSE, g_init specifies the initial value of $g$ used during optimization. When supplied, g_init should be an object of class tnormalmix or an ebnm object in which the fitted prior is an object of class tnormalmix.

If TRUE, fix the prior $g$ at g_init instead of estimating it.

A character vector indicating which values are to be returned. Function ebnm_output_default() provides the default return values, while ebnm_output_all() lists all possible return values. See Value below.

A list of control parameters to be passed to function optimize.

The following additional arguments act as control parameters for the outer EM loops in the fitting algorithm. Each loop iteratively updates parameters $w$ (the mixture proportion corresponding to the truncated normal component) and $\mu$ (the mode of the truncated normal component):

wlist

A vector defining intervals of $w$ for which optimal solutions will separately be found. For example, if wlist = c(0, 0.5, 1), then two optimal priors will be found: one such that $w$ is constrained to be less than 0.5 and one such that it is constrained to be greater than 0.5.

maxiter

A scalar specifying the maximum number of iterations to perform in each outer EM loop.

tol

A scalar specifying the convergence tolerance parameter for each outer EM loop.

mu_init

A scalar specifying the initial value of $\mu$ to be used in each outer EM loop.

mu_range

A vector of length two specifying lower and upper bounds for possible values of $\mu$.

A vector of observations. Missing observations (NAs) are not allowed.

A vector of standard errors (or a scalar if all are equal). Standard errors may not be exactly zero, and missing standard errors are not allowed. Two prior families have additional restrictions: when horseshoe priors are used, errors must be homoskedastic; and since function deconv in package deconvolveR takes $z$-scores, the "deconvolver" family requires that all standard errors be equal to 1.

A vector of character strings that gives the group to which each observation belongs. It must have the same length as argument x. For an example of usage, see Examples below.

A named vector that specifies the prior family $G$ for each group. If the same prior family is to be used for all groups, then a character string may be used instead.

A named list that specifies, for each group, the mode of the respective prior $g$, or "estimate" if the mode is to be estimated from the data. If the mode is the same across groups, then a scalar may be used instead. If all modes are to be estimated, then mode = "estimate" may be used.

A named list that specifies, for each group, the scale parameter(s) of the respective prior, or "estimate" if the scale parameters are to be estimated from the data. If the scale parameter is the same across groups, then a scalar may be used instead. If all scales are to be estimated, then scale = "estimate" may be used.

The prior distributions $g$. Usually this is left unspecified (NULL) and estimated from the data. However, it can be used in conjuction with fix_g = TRUE to fix the prior (useful, for example, to do computations with the "true" $g$ in simulations). If g_init is specified but fix_g = FALSE, g_init specifies the initial value of $g$ used during optimization. If g_init is supplied, it should be a named list that specifies, for each group, a prior of the appropriate class (normalmix for normal, point-normal, scale mixture of normals, and deconvolveR prior families, as well as for the NPMLE; class laplacemix for point-Laplace families; class gammamix for point-exponential families; class horseshoe for horseshoe families; and class unimix for unimodal_ families).

If TRUE, fix the prior $g$ at g_init instead of estimating it.

A character vector indicating which values are to be returned. Function ebnm_output_default() provides the default return values, while ebnm_output_all() lists all possible return values. See Value below.

Additional parameters. When a unimodal_ prior family is used, these parameters are passed to function ash in package ashr. Although it does not call into ashr, the scale mixture of normals family accepts parameter gridmult for purposes of comparison. When gridmult is set, an ashr-style grid will be used instead of the default ebnm grid. When the "deconvolver" family is used, additional parameters are passed to function deconv in package deconvolveR. Families of generalized binary priors take several additional parameters; see ebnm_generalized_binary. In all other cases, additional parameters are ignored.

A vector of observations. Missing observations (NAs) are not allowed.

A scalar specifying the standard error of the observations (observations must be homoskedastic).

A scalar corresponding to $s\tau$ in the usual parametrization of the horseshoe distribution, or "estimate" if this parameter is to be estimated from the data.

The prior distribution $g$. Usually this is left unspecified (NULL) and estimated from the data. However, it can be used in conjuction with fix_g = TRUE to fix the prior (useful, for example, to do computations with the "true" $g$ in simulations). If g_init is specified but fix_g = FALSE, g_init specifies the initial value of $g$ used during optimization. When supplied, g_init should be an object of class horseshoe or an ebnm object in which the fitted prior is an object of class horseshoe.

If TRUE, fix the prior $g$ at g_init instead of estimating it.

A character vector indicating which values are to be returned. Function ebnm_output_default() provides the default return values, while ebnm_output_all() lists all possible return values. See Value below.

A list of control parameters to be passed to function optimize.

A vector of observations. Missing observations (NAs) are not allowed.

A vector of standard errors (or a scalar if all are equal). Standard errors may not be exactly zero, and missing standard errors are not allowed.

A scalar specifying the mode of the prior $g$ or "estimate" if the mode is to be estimated from the data.

A scalar specifying the standard deviation of the normal prior or "estimate" if the standard deviation is to be estimated from the data.

The prior distribution $g$. Usually this is left unspecified (NULL) and estimated from the data. However, it can be used in conjuction with fix_g = TRUE to fix the prior (useful, for example, to do computations with the "true" $g$ in simulations). If g_init is specified but fix_g = FALSE, g_init specifies the initial value of $g$ used during optimization. When supplied, g_init should be an object of class normalmix or an ebnm object in which the fitted prior is an object of class normalmix.

If TRUE, fix the prior $g$ at g_init instead of estimating it.

A character vector indicating which values are to be returned. Function ebnm_output_default() provides the default return values, while ebnm_output_all() lists all possible return values. See Value below.

A string specifying which optimization function is to be used. Options include "nlm" (which calls nlm), "lbfgsb" (which calls optim with method = "L-BFGS-B"), and "trust" (which calls into the trust package). Other options are "nohess_nlm", "nograd_nlm", and "nograd_lbfgsb", which use numerical approximations rather than exact expressions for the Hessian; both of the "nograd" functions use numerical approximations for the gradient as well. The default option is "nohess_nlm".

A list of control parameters to be passed to the optimization function specified by parameter optmethod.

A vector of observations. Missing observations (NAs) are not allowed.

A vector of standard errors (or a scalar if all are equal). Standard errors may not be exactly zero, and missing standard errors are not allowed.

A scalar specifying the mode of the prior $g$ or "estimate" if the mode is to be estimated from the data.

The nonparametric family of scale mixtures of normals is approximated via a finite mixture of normal distributions

$\pi_1 N(\mu, \sigma_1^2) + \ldots + \pi_K N(\mu, \sigma_K^2),$

where parameters $\pi_k$ are estimated and the grid of standard deviations $(\sigma_1, \ldots, \sigma_K)$ is fixed in advance. By making the grid sufficiently dense, one can obtain an arbitrarily good approximation. The grid can be specified by the user via parameter scale, in which case the argument should be the vector of standard deviations $(\sigma_1, \ldots, \sigma_K)$; alternatively, if scale = "estimate", then ebnm sets the grid via function ebnm_scale_normalmix. Note that ebnm sets the grid differently from function ash. To use the ash grid, set scale = "estimate" and pass in gridmult as an additional parameter. See ash for defaults and details.

The prior distribution $g$. Usually this is left unspecified (NULL) and estimated from the data. However, it can be used in conjuction with fix_g = TRUE to fix the prior (useful, for example, to do computations with the "true" $g$ in simulations). If g_init is specified but fix_g = FALSE, g_init specifies the initial value of $g$ used during optimization. This has the side effect of fixing the mode and scale parameters. When supplied, g_init should be an object of class normalmix or an ebnm object in which the fitted prior is an object of class normalmix.

If TRUE, fix the prior $g$ at g_init instead of estimating it.

A character vector indicating which values are to be returned. Function ebnm_output_default() provides the default return values, while ebnm_output_all() lists all possible return values. See Value below.

A string specifying which optimization function is to be used. Options are provided by package ashr. The default method uses the mix-SQP algorithm implemented in the mixsqp package. See the ash function documentation for other options.

A list of control parameters to be passed to the optimization function specified by parameter optmethod.

When parameter gridmult is set, an ash-style grid will be used instead of the default ebnm grid (see parameter scale above). Other additional parameters are ignored.

A vector of observations. Missing observations (NAs) are not allowed.

A vector of standard errors (or a scalar if all are equal). Standard errors may not be exactly zero, and missing standard errors are not allowed.

The nonparametric family of all distributions is approximated via a finite mixture of point masses

$\pi_1 \delta_{\mu_1} + \ldots + \pi_K \delta_{\mu_K},$

where parameters $\pi_k$ are estimated and the point masses are evenly spaced over $(\mu_1, \mu_K)$. By taking a sufficiently dense grid of point masses, one can obtain an arbitrarily good approximation. The distance between successive point masses can be specified by the user via parameter scale, in which case the argument should be a scalar specifying the distance $d = \mu_2 - \mu_1 = \cdots = \mu_K - \mu_{K - 1}$; alternatively, if scale = "estimate", then ebnm sets the grid via function ebnm_scale_npmle.

The prior distribution $g$. Usually this is left unspecified (NULL) and estimated from the data. However, it can be used in conjuction with fix_g = TRUE to fix the prior (useful, for example, to do computations with the "true" $g$ in simulations). If g_init is specified but fix_g = FALSE, g_init specifies the initial value of $g$ used during optimization. This has the side effect of fixing the scale parameter. When supplied, g_init should be an object of class normalmix or an ebnm object in which the fitted prior is an object of class normalmix.

If TRUE, fix the prior $g$ at g_init instead of estimating it.

A character vector indicating which values are to be returned. Function ebnm_output_default() provides the default return values, while ebnm_output_all() lists all possible return values. See Value below.

A string specifying which optimization function is to be used. Options are provided by package ashr. The default method uses the mix-SQP algorithm implemented in the mixsqp package. See the ash function documentation for other options. It is also possible to specify optmethod = "REBayes", which uses function GLmix in the REBayes package to estimate the NPMLE rather than ashr. Note that REBayes requires installation of the commercial interior-point solver MOSEK; for details, see KWDual (the core optimization routine for the REBayes package).

A list of control parameters to be passed to the optimization function specified by parameter optmethod.

A vector of observations. Missing observations (NAs) are not allowed.

A vector of standard errors (or a scalar if all are equal). Standard errors may not be exactly zero, and missing standard errors are not allowed.

A scalar specifying the mode of the prior $g$ or "estimate" if the mode is to be estimated from the data.

A scalar specifying the scale parameter of the exponential component or "estimate" if the scale is to be estimated from the data. The mean of the exponential component is the same as the value of scale.

The prior distribution $g$. Usually this is left unspecified (NULL) and estimated from the data. However, it can be used in conjuction with fix_g = TRUE to fix the prior (useful, for example, to do computations with the "true" $g$ in simulations). If g_init is specified but fix_g = FALSE, g_init specifies the initial value of $g$ used during optimization. When supplied, g_init should be an object of class gammamix or an ebnm object in which the fitted prior is an object of class gammamix.

If TRUE, fix the prior $g$ at g_init instead of estimating it.

A character vector indicating which values are to be returned. Function ebnm_output_default() provides the default return values, while ebnm_output_all() lists all possible return values. See Value below.

A string specifying which optimization function is to be used. Options include "nlm" (which calls nlm), "lbfgsb" (which calls optim with method = "L-BFGS-B"), and "trust" (which calls into the trust package). Other options are "nohess_nlm", "nograd_nlm", and "nograd_lbfgsb", which use numerical approximations rather than exact expressions for the Hessian; both of the "nograd" functions use numerical approximations for the gradient as well. The default option is "nohess_nlm".

A list of control parameters to be passed to the optimization function specified by parameter optmethod.

A vector of observations. Missing observations (NAs) are not allowed.

A vector of standard errors (or a scalar if all are equal). Standard errors may not be exactly zero, and missing standard errors are not allowed.

A scalar specifying the mode of the prior $g$ or "estimate" if the mode is to be estimated from the data.

A scalar specifying the scale parameter of the Laplace component or "estimate" if the scale is to be estimated from the data.

The prior distribution $g$. Usually this is left unspecified (NULL) and estimated from the data. However, it can be used in conjuction with fix_g = TRUE to fix the prior (useful, for example, to do computations with the "true" $g$ in simulations). If g_init is specified but fix_g = FALSE, g_init specifies the initial value of $g$ used during optimization. When supplied, g_init should be an object of class laplacemix or an ebnm object in which the fitted prior is an object of class laplacemix.

If TRUE, fix the prior $g$ at g_init instead of estimating it.

A character vector indicating which values are to be returned. Function ebnm_output_default() provides the default return values, while ebnm_output_all() lists all possible return values. See Value below.

A string specifying which optimization function is to be used. Options include "nlm" (which calls nlm), "lbfgsb" (which calls optim with method = "L-BFGS-B"), and "trust" (which calls into the trust package). Other options are "nohess_nlm", "nograd_nlm", and "nograd_lbfgsb", which use numerical approximations rather than exact expressions for the Hessian; both of the "nograd" functions use numerical approximations for the gradient as well. The default option is "nohess_nlm".

A list of control parameters to be passed to the optimization function specified by parameter optmethod.

A vector of observations. Missing observations (NAs) are not allowed.

A vector of standard errors (or a scalar if all are equal). Standard errors may not be exactly zero, and missing standard errors are not allowed.

A scalar specifying the location of the point mass or "estimate" if the location is to be estimated from the data.

The prior distribution $g$. Usually this is left unspecified (NULL) and estimated from the data. However, it can be used in conjuction with fix_g = TRUE to fix the prior (useful, for example, to do computations with the "true" $g$ in simulations). If g_init is specified but fix_g = FALSE, g_init specifies the initial value of $g$ used during optimization. When supplied, g_init should be an object of class normalmix or an ebnm object in which the fitted prior is an object of class normalmix.

If TRUE, fix the prior $g$ at g_init instead of estimating it.

A character vector indicating which values are to be returned. Function ebnm_output_default() provides the default return values, while ebnm_output_all() lists all possible return values. See Value below.

A list of control parameters to be passed to function optimize.

A vector of observations. Missing observations (NAs) are not allowed.

A vector of standard errors (or a scalar if all are equal). Standard errors may not be exactly zero, and missing standard errors are not allowed.

A scalar specifying the mode of the prior $g$ or "estimate" if the mode is to be estimated from the data.

A scalar specifying the standard deviation of the normal component or "estimate" if the standard deviation is to be estimated from the data.

The prior distribution $g$. Usually this is left unspecified (NULL) and estimated from the data. However, it can be used in conjuction with fix_g = TRUE to fix the prior (useful, for example, to do computations with the "true" $g$ in simulations). If g_init is specified but fix_g = FALSE, g_init specifies the initial value of $g$ used during optimization. When supplied, g_init should be an object of class normalmix or an ebnm object in which the fitted prior is an object of class normalmix.

If TRUE, fix the prior $g$ at g_init instead of estimating it.

A character vector indicating which values are to be returned. Function ebnm_output_default() provides the default return values, while ebnm_output_all() lists all possible return values. See Value below.

A string specifying which optimization function is to be used. Options include "nlm" (which calls nlm), "lbfgsb" (which calls optim with method = "L-BFGS-B"), and "trust" (which calls into the trust package). Other options are "nohess_nlm", "nograd_nlm", and "nograd_lbfgsb", which use numerical approximations rather than exact expressions for the Hessian; both of the "nograd" functions use numerical approximations for the gradient as well. The default option is "nohess_nlm".

A list of control parameters to be passed to the optimization function specified by parameter optmethod.

A vector of observations. Missing observations (NAs) are not allowed.

A vector of standard errors (or a scalar if all are equal). Standard errors may not be exactly zero, and missing standard errors are not allowed.

A scalar specifying the mode of the prior $g$.

The minimum number of components $K$ to include in the finite mixture of normal distributions used to approximate the nonparametric family of scale mixtures of normals.

The maximum number of components $K$ to include in the approximating mixture of normal distributions.

The desired bound $\kappa$ on the KL-divergence from the solution obtained using the approximating mixture to the exact solution. More precisely, the scale parameter is set such that given the exact MLE

$\hat{g} := \mathrm{argmax}_{g \in G} L(g),$

where $G$ is the full nonparametric family, and given the MLE for the approximating family $\tilde{G}$

$\tilde{g} := \mathrm{argmax}_{g \in \tilde{G}} L(g),$

we have that

$\mathrm{KL}(\hat{g} \ast N(0, s^2) \mid \tilde{g} \ast N(0, s^2)) \le \kappa,$

where $\ast \ N(0, s^2)$ denotes convolution with the normal error distribution (the derivation of the bound assumes homoskedastic observations). For details, see References below.

A vector of observations. Missing observations (NAs) are not allowed.

A vector of standard errors (or a scalar if all are equal). Standard errors may not be exactly zero, and missing standard errors are not allowed.

The minimum number of components $K$ to include in the mixture of point masses used to approximate the nonparametric family of all distributions.

The maximum number of components $K$ to include in the approximating mixture of point masses.

The desired bound $\kappa$ on the KL-divergence from the solution obtained using the approximating mixture to the exact solution. More precisely, the scale parameter is set such that given the exact MLE

$\hat{g} := \mathrm{argmax}_{g \in G} L(g),$

where $G$ is the full nonparametric family, and given the MLE for the approximating family $\tilde{G}$

$\tilde{g} := \mathrm{argmax}_{g \in \tilde{G}} L(g),$

we have that

$\mathrm{KL}(\hat{g} \ast N(0, s^2) \mid \tilde{g} \ast N(0, s^2)) \le \kappa,$

where $\ast \ N(0, s^2)$ denotes convolution with the normal error distribution (the derivation of the bound assumes homoskedastic observations). For details, see References below.

When the range of the data is so large that max_K point masses cannot provide a good approximation to the family of all distributions, then ebnm will instead use a mixture of normal distributions, with the standard deviation of each component equal to scale$/ 2$. Setting pointmass = FALSE gives the default scale for this mixture of normal distributions.

To be exact, ebnm uses a mixture of normal distributions rather than a mixture of point masses when

$\frac{\max(x) - \min(x)}{\min(s)} > 3 \ \mathrm{max}_K;$

for a rationale, see References below. Note however that ebnm only uses a mixture of normal distributions when scale = "estimate"; if parameter scale is set manually, then a mixture of point masses will be used in all cases. To use a mixture of normal distributions with the scale set manually, an object created by the constructor function normalmix must be provided as argument to parameter g_init in function ebnm_npmle or function ebnm_deconvolver.

A vector of observations. Missing observations (NAs) are not allowed.

A vector of standard errors (or a scalar if all are equal). Standard errors may not be exactly zero, and missing standard errors are not allowed.

A scalar specifying the mode of the prior $g$.

The minimum number of components $K$ to include in the finite mixture of uniform distributions used to approximate the nonparametric family of unimodal distributions.

The maximum number of components $K$ to include in the approximating mixture of uniform distributions.

The desired bound $\kappa$ on the KL-divergence from the solution obtained using the approximating mixture to the exact solution. More precisely, the scale parameter is set such that given the exact MLE

$\hat{g} := \mathrm{argmax}_{g \in G} L(g),$

where $G$ is the full nonparametric family, and given the MLE for the approximating family $\tilde{G}$

$\tilde{g} := \mathrm{argmax}_{g \in \tilde{G}} L(g),$

we have that

$\mathrm{KL}(\hat{g} \ast N(0, s^2) \mid \tilde{g} \ast N(0, s^2)) \le \kappa,$

where $\ast \ N(0, s^2)$ denotes convolution with the normal error distribution (the derivation of the bound assumes homoskedastic observations). For details, see References below.

A vector of observations. Missing observations (NAs) are not allowed.

A vector of standard errors (or a scalar if all are equal). Standard errors may not be exactly zero, and missing standard errors are not allowed.

A scalar specifying the mode of the prior $g$ or "estimate" if the mode is to be estimated from the data.

The nonparametric family of unimodal distributions is approximated via a finite mixture of uniform distributions

$\pi_1^l \mathrm{Unif}(\mu - a_1, \mu) + \pi_1^u \mathrm{Unif}(\mu, \mu + a_1) + \ldots + \pi_K^l \mathrm{Unif}(\mu - a_K, \mu) + \pi_K^u \mathrm{Unif}(\mu, \mu + a_K),$

where parameters $\pi_k^l$ and $\pi_k^u$ are estimated and the grid of lengths $(a_1, \ldots, a_K)$ is fixed in advance. By making the grid sufficiently dense, one can obtain an arbitrarily good approximation. The grid can be specified by the user via parameter scale, in which case the argument should be the vector of lengths $(a_1, \ldots, a_K)$; alternatively, if scale = "estimate", then ebnm sets the grid via function ebnm_scale_unimix. Note that ebnm sets the grid differently from function ash. To use the ash grid, set scale = "estimate" and pass in gridmult as an additional parameter. See ash for defaults and details.

The prior distribution $g$. Usually this is left unspecified (NULL) and estimated from the data. However, it can be used in conjuction with fix_g = TRUE to fix the prior (useful, for example, to do computations with the "true" $g$ in simulations). If g_init is specified but fix_g = FALSE, g_init specifies the initial value of $g$ used during optimization. This has the side effect of fixing the mode and scale parameters. When supplied, g_init should be an object of class unimix or an ebnm object in which the fitted prior is an object of class unimix.

If TRUE, fix the prior $g$ at g_init instead of estimating it.

A character vector indicating which values are to be returned. Function ebnm_output_default() provides the default return values, while ebnm_output_all() lists all possible return values. See Value below.

A string specifying which optimization function is to be used. Options are provided by package ashr. The default method uses the mix-SQP algorithm implemented in the mixsqp package. See the ash function documentation for other options.

A list of control parameters to be passed to the optimization function specified by parameter optmethod.

Additional parameters to be passed to function ash in package ashr.

A vector of observations. Missing observations (NAs) are not allowed.

A vector of standard errors (or a scalar if all are equal). Standard errors may not be exactly zero, and missing standard errors are not allowed.

A scalar specifying the mode of the prior $g$ or "estimate" if the mode is to be estimated from the data.

The nonparametric family of nonnegative unimodal distributions is approximated via a finite mixture of uniform distributions

$\pi_1 \mathrm{Unif}(\mu, \mu + a_1) + \ldots + \pi_K \mathrm{Unif}(\mu, \mu + a_K),$

where parameters $\pi_k$ are estimated and the grid of lengths $(a_1, \ldots, a_K)$ is fixed in advance. By making the grid sufficiently dense, one can obtain an arbitrarily good approximation. The grid can be specified by the user via parameter scale, in which case the argument should be the vector of lengths $(a_1, \ldots, a_K)$; alternatively, if scale = "estimate", then ebnm sets the grid via function ebnm_scale_unimix. Note that ebnm sets the grid differently from function ash. To use the ash grid, set scale = "estimate" and pass in gridmult as an additional parameter. See ash for defaults and details.

The prior distribution $g$. Usually this is left unspecified (NULL) and estimated from the data. However, it can be used in conjuction with fix_g = TRUE to fix the prior (useful, for example, to do computations with the "true" $g$ in simulations). If g_init is specified but fix_g = FALSE, g_init specifies the initial value of $g$ used during optimization. This has the side effect of fixing the mode and scale parameters. When supplied, g_init should be an object of class unimix or an ebnm object in which the fitted prior is an object of class unimix.

If TRUE, fix the prior $g$ at g_init instead of estimating it.

A character vector indicating which values are to be returned. Function ebnm_output_default() provides the default return values, while ebnm_output_all() lists all possible return values. See Value below.

A string specifying which optimization function is to be used. Options are provided by package ashr. The default method uses the mix-SQP algorithm implemented in the mixsqp package. See the ash function documentation for other options.

A list of control parameters to be passed to the optimization function specified by parameter optmethod.

Additional parameters to be passed to function ash in package ashr.

A vector of observations. Missing observations (NAs) are not allowed.

A vector of standard errors (or a scalar if all are equal). Standard errors may not be exactly zero, and missing standard errors are not allowed.

A scalar specifying the mode of the prior $g$ or "estimate" if the mode is to be estimated from the data.

The nonparametric family of nonnpositive unimodal distributions is approximated via a finite mixture of uniform distributions

$\pi_1 \mathrm{Unif}(\mu - a_1, \mu) + \ldots + \pi_K \mathrm{Unif}(\mu - a_K, \mu),$

where parameters $\pi_k$ are estimated and the grid of lengths $(a_1, \ldots, a_K)$ is fixed in advance. By making the grid sufficiently dense, one can obtain an arbitrarily good approximation. The grid can be specified by the user via parameter scale, in which case the argument should be the vector of lengths $(a_1, \ldots, a_K)$; alternatively, if scale = "estimate", then ebnm sets the grid via function ebnm_scale_unimix. Note that ebnm sets the grid differently from function ash. To use the ash grid, set scale = "estimate" and pass in gridmult as an additional parameter. See ash for defaults and details.

The prior distribution $g$. Usually this is left unspecified (NULL) and estimated from the data. However, it can be used in conjuction with fix_g = TRUE to fix the prior (useful, for example, to do computations with the "true" $g$ in simulations). If g_init is specified but fix_g = FALSE, g_init specifies the initial value of $g$ used during optimization. This has the side effect of fixing the mode and scale parameters. When supplied, g_init should be an object of class unimix or an ebnm object in which the fitted prior is an object of class unimix.

If TRUE, fix the prior $g$ at g_init instead of estimating it.

A character vector indicating which values are to be returned. Function ebnm_output_default() provides the default return values, while ebnm_output_all() lists all possible return values. See Value below.

A string specifying which optimization function is to be used. Options are provided by package ashr. The default method uses the mix-SQP algorithm implemented in the mixsqp package. See the ash function documentation for other options.

A list of control parameters to be passed to the optimization function specified by parameter optmethod.

Additional parameters to be passed to function ash in package ashr.

A vector of observations. Missing observations (NAs) are not allowed.

A vector of standard errors (or a scalar if all are equal). Standard errors may not be exactly zero, and missing standard errors are not allowed.

A scalar specifying the mode of the prior $g$ or "estimate" if the mode is to be estimated from the data.

The nonparametric family of symmetric unimodal distributions is approximated via a finite mixture of uniform distributions

$\pi_1 \mathrm{Unif}(\mu - a_1, \mu + a_1) + \ldots + \pi_K \mathrm{Unif}(\mu - a_K, \mu + a_K),$

where parameters $\pi_k$ are estimated and the grid of (half-)lengths $(a_1, \ldots, a_K)$ is fixed in advance. By making the grid sufficiently dense, one can obtain an arbitrarily good approximation. The grid can be specified by the user via parameter scale, in which case the argument should be the vector $(a_1, \ldots, a_K)$; alternatively, if scale = "estimate", then ebnm sets the grid via function ebnm_scale_unimix. Note that ebnm sets the grid differently from function ash. To use the ash grid, set scale = "estimate" and pass in gridmult as an additional parameter. See ash for defaults and details.

The prior distribution $g$. Usually this is left unspecified (NULL) and estimated from the data. However, it can be used in conjuction with fix_g = TRUE to fix the prior (useful, for example, to do computations with the "true" $g$ in simulations). If g_init is specified but fix_g = FALSE, g_init specifies the initial value of $g$ used during optimization. This has the side effect of fixing the mode and scale parameters. When supplied, g_init should be an object of class unimix or an ebnm object in which the fitted prior is an object of class unimix.

If TRUE, fix the prior $g$ at g_init instead of estimating it.

A character vector indicating which values are to be returned. Function ebnm_output_default() provides the default return values, while ebnm_output_all() lists all possible return values. See Value below.

A string specifying which optimization function is to be used. Options are provided by package ashr. The default method uses the mix-SQP algorithm implemented in the mixsqp package. See the ash function documentation for other options.

A list of control parameters to be passed to the optimization function specified by parameter optmethod.

Additional parameters to be passed to function ash in package ashr.

The fitted ebnm object.

Not used. Included for consistency as an S3 method.

A vector of mixture proportions.

A vector of shape parameters.

A vector of scale parameters.

A vector of shift parameters.

The scale parameter (must be a scalar).

A vector of mixture proportions.

A vector of means.

A vector of scale parameters.

The fitted ebnm object.

Not used. Included for consistency as an S3 method.

The fitted ebnm object.

Not used. Included for consistency as an S3 method.

The fitted ebnm object.

Additional ebnm objects to be included on the same plots.

Plot posterior means vs. observations?

Plot the cumulative distribution functions?

The subset of observations to include on the plot of posterior means vs. observations. Can be a numeric vector corresponding to indices of observations to plot, or a character vector if observations are named. If subset = NULL then all observations will be plotted.

To better illustrate shrinkage effects, the plot of posterior means vs. observations includes the line $y = x$ by default. If remove_abline = TRUE, then this line will not be drawn.