get_er_from_jags: The Expected Rank from a JAGS model
In snsf-data/ERforResearch: Expected Rank for Research Evaluation
get_er_from_jags R Documentation
The Expected Rank from a JAGS model
Description
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",
assessor_behavior_name = "nu",
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'.
assessor_behavior_name
the name of the parameter in the JAGS model
indicating the voter behavior. By default it is set to 'nu' as this is the
name in the default JAGS model.
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")
## Not run:
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)
## End(Not run)
snsf-data/ERforResearch documentation built on May 12, 2024, 9:25 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| get_er_from_jags | R Documentation |
The Expected Rank from a JAGS model
Description
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",
assessor_behavior_name = "nu",
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'. |
assessor_behavior_name |
the name of the parameter in the JAGS model indicating the voter behavior. By default it is set to 'nu' as this is the name in the default JAGS model. |
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")
## Not run:
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)
## End(Not run)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.