rvalues: R-values
In rvalues: R-Values for Ranking in High-Dimensional Settings

Description Usage Arguments Details Value Author(s) References See Also Examples

Given data on a collection of units, this function computes r-values which are percentiles constructed to maximize the agreement between the reported percentiles and the percentiles of the effect of interest. Additional details about r-values are provided below and can also be found in the listed references.

1 2	rvalues(data, family = gaussian, hypers = "estimate", prior = "conjugate", alpha.grid = NULL, ngrid = NULL, smooth = "none", control = list())

`data`	A data frame or a matrix with the number of rows equal to the number of sampling units. The first column should contain the main estimates, and the second column should contain the nuisance terms.
`family`	An argument which determines the sampling distribution; this could be either `family = gaussian`, `family = tdist`, `family = binomial`, `family = poisson`
`hypers`	values of the hyperparameters; only meaningful when the conjugate prior is used; if set to "estimate", the hyperparameters are found through maximum likelihood; if not set to "estimate" the user should supply a vector of length two.
`prior`	the form of the prior; either `prior="conjugate"` or `prior="nonparametric"`.
`alpha.grid`	a numeric vector of points in (0,1); this grid is used in the discrete approximation of r-values
`ngrid`	number of grid points for alpha.grid; only relevant when `alpha.grid=NULL`
`smooth`	either `smooth="none"` or `smooth` takes a value between 0 and 10; this determines the level of smoothing applied to the estimate of λ(α) (see below for the definition of λ(α)); if `smooth` is given a number, the number is used as the `bass` argument in `supsmu`.
`control`	a list of control parameters for estimation of the prior; only used when the prior is nonparametric

The r-value computation assumes the following two-level sampling model X_i|θ_i ~ p(x|θ_i,η_i) and θ_i ~ F, for i = 1,...,n, with parameters of interest θ_i, effect size estimates X_i, and nuisance terms η_i. The form of p(x|θ_i,η_i) is determined by the family argument. When family = gaussian, it is assumed that X_i|θ_i,η_i ~ N(θ_i,η_i^{2}). When family = binomial, the (X_i,η_i) represent the number of successes and number of trials respectively, and it is assumed that X_i|θ_i,η_i ~ Binomial(θ_i,η_i). When family = poisson, the {X_i} should be counts, and it is assumed that X_i|θ_i,η_i ~ Poisson(θ_i * η_i).

The distribution of the effect sizes F may be a parametric distribution that is conjugate to the corresponding family argument, or it may be estimated nonparametrically. When it is desired that F be parametric (i.e., prior = "conjugate"), the default is to estimate the hyperparameters (i.e., hypers = "estimate"), but these may be supplied by the user as a vector of length two. To estimate F nonparametrically, one should use prior = "nonparametric" (see npmle for further details about nonparametric estimation of F).

The r-value, r_i, assigned to the ith case of interest is determined by r_i = inf[ 0 < α < 1: V_α(X_i,η_i) ≥ λ(α) ] where V_α(X_i,η_i) = P( θ_i ≥ θ_α|X_i,η_i) is the posterior probability that θ_i exceeds the threshold θ_α, and λ(α) is the upper-αth quantile associated with the marginal distribution of V_α(X_i,η_i) (i.e., P(V_α(X_i,η_i) ≥ λ(α)) = α). Similarly, the threshold θ_α is the upper-αth quantile of F (i.e., P(θ_i ≥ θ_α) = α ).

An object of class "rvals" which is a list containing at least the following components:

`main`	a data frame containing the r-values, the r-value rankings along with the rankings from several other common procedures
`aux`	a list containing other extraneous information
`rvalues`	a vector of r-values

Nicholas C. Henderson and Michael A. Newton

Henderson, N.C. and Newton, M.A. (2016). Making the cut: improved ranking and selection for large-scale inference. J. Royal Statist. Soc. B., 78(4), 781-804. doi: 10.1111/rssb.12131 https://arxiv.org/abs/1312.5776

rvaluesMCMC, PostSummaries, Valpha

## Not run: 
### Binomial example with Beta prior:
data(fluEnrich)
flu.rvals <- rvalues(fluEnrich, family = binomial)
hist(flu.rvals$rvalues)

### look at the r-values for indices 10 and 2484
fig_indices  <- c(10,2484)
fluEnrich[fig_indices,]

flu.rvals$rvalues[fig_indices]

### Gaussian sampling distribution with nonparametric prior
### Use a maximum of 5 iterations for the nonparam. estimate
data(hiv)
hiv.rvals <- rvalues(hiv, prior = "nonparametric")

## End(Not run)