The Expected Rank from a JAGS model — get_er_from

This function computes the ER via JAGS

Usage

get_er_from_jags(
  data,
  id_proposal,
  id_assessor = NULL,
  grade_variable,
  path_to_jags_model = NULL,
  n_chains = 4,
  n_iter = 10000,
  n_burnin = 4000,
  n_adapt = 1000,
  max_iter = 1e+06,
  id_panel = NULL,
  theta_name = "proposal_intercept",
  assessor_name = "assessor_intercept",
  tau_name_proposal = "tau_proposal",
  tau_name_assessor = "tau_assessor",
  tau_name_panel = NULL,
  sigma_name = "sigma",
  rank_theta_name = "rank_theta",
  rank_pm = TRUE,
  ordinal_scale = FALSE,
  heterogeneous_residuals = FALSE,
  point_scale = NULL,
  mcmc_samples = NULL,
  inits_type = "random",
  initial_values = NULL,
  names_variables_to_sample = NULL,
  seed = 1991,
  quiet = FALSE,
  rhat_threshold = 1.01,
  runjags_method = "parallel"
)

Arguments

data: data frame, in long format, with all needed variables as specified in the JAGS model defined in the text file with path given in `path_to_jags_model`.
id_proposal: the name of the variable in `data` that indicates the ID of the evaluated proposal.
id_assessor: the name of the variable in `data` that indicates the ID of the assessor. The default `= NULL`, for the case where each assessor only evaluates/grades one proposal.
grade_variable: the name of the variable in `data` with the outcome variable, i.e. the grade or score.
path_to_jags_model: the path to text file including the JAGS model definition. By default `= NULL`, and the function will use a default model as implemented in the package; in `get_default_jags_model()`.
n_chains: the number of chains for the JAGS sampler. The default number of chains is set to four. This creates optimal conditions and should not be changed. The same parameter in `runjags::run.jags()` is called `n.chains`.
n_iter: how many iterations should be used in the JAGS sampler? This is the same as `sample` in the `runjags::run.jags()` function. It is set to `10000` by default.
n_burnin: the number of burnin iterations which will not be included in the adaptation phase. By default it is set to `4000` and the same parameter in `runjags::run.jags()` is called `burnin`.
n_adapt: the number of adaptive iterations discarded for the adaptation phase. By default it is set to `1000`. The same parameter in `runjags::run.jags()` is called `adapt`.
max_iter: the maximum number of iteration. The JAGS sample will be extended until convergence of the chains. To ensure that the sampler does not run and extend forever a maximum number of iterations per chain can be defined. Once this number of iterations is achieved, the sampler will not be further extended. By default, the function allows up to `1000000` iterations before stopping.
id_panel: the name of the variable in `data` that indicates the ID of the panel. The default `= NULL`, for the case where all proposals were evaluated in the same panel, or were each panel creates its own ranking. In the other scenario, a ranking would be established combining or merging all panels.
theta_name: the name of the proposal intercept in the JAGS model. The default that also goes with the default JAGS model build in the package is `proposal_intercept`.
assessor_name: the name of the assessor intercept in the JAGS model. The default that also goes with the default JAGS model build in the package is `assessor_intercept`.
tau_name_proposal: the name of tau in the JAGS model, being the standard error of the proposal effects. The default that also goes with the default JAGS model build in the package is `tau_proposal`.
tau_name_assessor: name of the standard error of the assessor effect in the JAGS model. The default that also goes with the default JAGS model build in the package is `tau_assessor`.
tau_name_panel: the name of the standard error of the panel effect, if needed. The default that also goes with the default JAGS model build in the package is `tau_panel`. This is only needed if a ranking has to be established combining or merging all panels, and therefore only important if `id_panel` is not `NULL`.
sigma_name: name of the standard deviation of the full model. The default that also goes with the default JAGS model build in the package is `sigma`.
rank_theta_name: the name of the rank of theta in the JAGS model. The default that also goes with the default JAGS model build in the package is `rank_theta`.
rank_pm: should the rank based on the posterior mean by computed and presented in the Figure? By default this parameter is set to `TRUE`.
ordinal_scale: dummy variable informing us on whether or not the outcome is on an ordinal scale. By default, we assume a numeric scale and this parameter is set to `FALSE`.
heterogeneous_residuals: dummy variable informing us on whether or not the residuals should be heterogeneous. By default the residuals are assumed homogeneous and this parameter is set to `FALSE`.
point_scale: integer informing us on the number of points of the ordinal scale; not needed for continuous scale. By default, we assume a numeric scale and do not need this information and the parameter is set to `NULL`.
mcmc_samples: if the mcmc sample has already been run. This should be the direct output from the `get_mcmc_samples()`. By default, it is set to `NULL` and the sampler will be run. If mcmc samples are provided here, all further sampling information below, e.g. number of chains and iterations will be disgarded.
inits_type: the type of the initial values. By default the initial values are randomly selected, i.e. `inits_type = "random"`. Alternatively, if four chains are used, the initial values can also be `"overdispersed"`.
initial_values: The list of initial values for the jags sampler can be provided directly. Otherwise `get_inits_overdispersed_four_chains` for the overdispersed version is used, or they are randomly selected. Always using a seed to ensure computational reproducibility.
names_variables_to_sample: if variables to sample are specified, write their names here, as a character-vector, default is NULL.
seed: the seed for the JAGS model (default = `1991`). This seed will generate the seeds for the JAGS samplers, which ensures reproducibility; see also Details.
quiet: if the default model is used this function generates a warning. if `quiet = TRUE`, the warning is not shown.
rhat_threshold: the threshold for rhat to decide whether or not the chains converged. Gelman suggested 1.1, but the smaller the better. Hence this functions threshold is set to `1.01` by default.
runjags_method: the method with which to call JAGS (from `runjags::run.jags()` with the default being set to `parallel`).

Value

the result is a list with the

1) a table with the ranked proposals: id_proposal is the unique identifier of the proposal. rank is the simplistic rank based on the average of the individual votes, avg_grade. er is the expected rank. rank_pm is the rank of the posterior mean and pcer is the percentile based on er.

2) the number of chains (n_chains), the number of adaptive iterations (n_adapt), the number of burnin iterations (n_burnin), and the final number of iterations actually samples (n_iter).

3) the MCMC summary and the convergence status.

Examples

data_panel1 <- get_mock_data() %>%
         filter(panel == "p1")
if (FALSE) {
ER_results <- get_er_from_jags(data = data_panel1,
                               id_proposal = "proposal",
                               id_assessor = "assessor",
                               grade_variable = "num_grade",
                               path_to_jags_model = NULL)
# OR, by giving an mcmc object into the function
mcmc_samples <- get_mcmc_samples(data = data_panel1,
                                 id_proposal = "proposal",
                                 id_assessor = "assessor",
                                 grade_variable = "num_grade")
ER_results <- get_er_from_jags(data = data_panel1,
                              id_proposal = "proposal",
                              id_assessor = "assessor",
                              grade_variable = "num_grade",
                              mcmc_samples = mcmc_samples)
}