Package 'fcirt'

The 'fcirt' package.

Description

Forced Choice in Item Response Theory

References

Stan Development Team (2020). RStan: the R interface to Stan. R package version 2.21.2. https://mc-stan.org

---

bayesian convergence diagnosis plotting function

Description

This function provides plots including density plots, trace plots, and auto-correlation plots to aid model convergence diagnosis.

Usage

bayesplot(x, pars, plot, inc_warmup = FALSE)

Arguments

x	returned object
pars	Names of plotted parameters. They can be "theta", "alpha", "delta", "tau", or a subset of parameters. See vignette for fcirt for more details.
plot	Types of plots.They can be "density", "trace", or "autocorrelation".
inc_warmup	Whether to include warmup iterations or not when plotting. The default is FALSE.

Value

Selected plots for selected parameters

Examples

Data <- c(1,2)
Data <- matrix(Data,nrow = 1)
pairmap <- c(1,3,2,4)
pairmap <- matrix(pairmap,nrow = 2)
ind <- c(1,2,1,2)
ParInits <- c(1, 1, 1, 1,1,-1, -1,1, -1,-1,-1,-1)
ParInits <- matrix(ParInits, ncol = 3)
mod <- fcirt(fcirt.Data=Data,pairmap=pairmap,ind=ind,ParInits=ParInits,iter=3,warmup=1,chains=1)
bayesplot(mod, 'alpha', 'density', inc_warmup=FALSE)

---

results extraction

Description

This function extracts estimation results.

Usage

extract(x, pars)

Arguments

x

returned object

pars

Names of extracted parameters. They can be "theta" (person trait estimates), "alpha" (statement discrimination parameters), "delta" (statement location parameters), "tau" (statement threshold parameters), data" (fcirt.Data), "fit" (the stanfit object), "dimension" (the input column vector mapping each statement to each trait), "pairmap" (A two-column data matrix: the first column is the statement number for statement s; the second column is the statement number for statement t), and "ParInits" (A three-column matrix containing initial values for the three statement parameters. If using the direct MUPP estimation approach, 1 and -1 for alphas and taus are recommended and -1 or 1 for deltas are recommended depending on the signs of the statements. If using the two-step estimation approach, pre-estimated statement parameters are used as the initial values. The R package bmggum can be used to estimate statement parameters for the two-step approach).

Value

Selected results output

Examples

Data <- c(1,2)
Data <- matrix(Data,nrow = 1)
pairmap <- c(1,3,2,4)
pairmap <- matrix(pairmap,nrow = 2)
ind <- c(1,2,1,2)
ParInits <- c(1, 1, 1, 1,1,-1, -1,1, -1,-1,-1,-1)
ParInits <- matrix(ParInits, ncol = 3)
mod <- fcirt(fcirt.Data=Data,pairmap=pairmap,ind=ind,ParInits=ParInits,iter=3,warmup=1,chains=1)
alpha <- extract(mod, 'alpha')

---

forced choice model estimation

Description

This function implements full Bayesian estimation of forced choice models using rstan

Usage

fcirt(
  fcirt.Data,
  pairmap,
  ind,
  ParInits,
  model = "MUPP",
  covariate = NULL,
  iter = 3000,
  chains = 3,
  warmup = floor(iter/2),
  adapt_delta = 0.9,
  max_treedepth = 15,
  thin = 1,
  cores = 2,
  ma = 0,
  va = 0.5,
  md = 0,
  vd = 1,
  mt = 0,
  vt = 2
)

Arguments

fcirt.Data	Response data in wide format. If the first statement is preferred, the data should be coded as 1, otherwise it should be coded as 2.
pairmap	A two-column data matrix: the first column is the statement number for statement s; the second column is the statement number for statement t.
ind	A column vector mapping each statement to each trait. For example, c(1, 1, 1, 2, 2, 2) means that the first 3 statements belong to trait 1 and the last 3 statements belong to trait 2.
ParInits	A three-column matrix containing initial values for the three statement parameters. If using the direct MUPP estimation approach, 1 and -1 for alphas and taus are recommended and -1 or 1 for deltas are recommended depending on the signs of the statements. If using the two-step estimation approach, pre-estimated statement parameters are used as the initial values. The R package bmggum can be used to estimate statement parameters for the two-step approach. See documentation for bmggum for more details.
model	Models fitted. They can be "MUPP". The default is MUPP (Multi-Unidimensional Pairwise Preference) model.
covariate	An p*c person covariate matrix where p equals sample size and c equals the number of covariates. The default is NULL, meaning no person covariate.
iter	The number of iterations. The default value is 3000. See documentation for rstan for more details.
chains	The number of chains. The default value is 3. See documentation for rstan for more details.
warmup	The number of warmups to discard. The default value is 0.5*iterations. See documentation for rstan for more details.
adapt_delta	Target average proposal acceptance probability during Stan's adaptation period. The default value is 0.90. See documentation for rstan for more details.
max_treedepth	Cap on the depth of the trees evaluated during each iteration. The default value is 15. See documentation for rstan for more details.
thin	Thinning. The default value is 1. See documentation for rstan for more details.
cores	The number of computer cores used for parallel computing. The default value is 2.
ma	Mean of the prior distribution for alphas, which follows a lognormal distribution. The default value is 0.
va	Standard deviation of the prior distribution for alpha. The default value is 0.5.
md	Mean of the prior distribution for deltas, which follows a normal distribution. The default value is 0.
vd	Standard deviation of the prior distribution for deltas. The default value is 1.
mt	Means of the prior distributions for taus, which follows a normal distribution. The default values is 0.
vt	Standard deviation of the prior distribution for taus. The default value is 2.

Value

Result object that stores information including the (1) stanfit object, (2) estimated item parameters, (3) estimated person parameters, (4) response data, and (5) the input column vector mapping each statement to each trait.

Examples

Data <- c(1,2)
Data <- matrix(Data,nrow = 1)
pairmap <- c(1,3,2,4)
pairmap <- matrix(pairmap,nrow = 2)
ind <- c(1,2,1,2)
ParInits <- c(1, 1, 1, 1,1,-1, -1,1, -1,-1,-1,-1)
ParInits <- matrix(ParInits, ncol = 3)
mod <- fcirt(fcirt.Data=Data,pairmap=pairmap,ind=ind,ParInits=ParInits,iter=3,warmup=1,chains=1)

---

mfc item and test information

Description

This function calculates mfc item and test information.

Usage

information(x, approach, theta, information, items)

Arguments

x	returned object
approach	Estimation approaches used for parameters. They can be "direct", which is direct approach, and "two step", which is two step approach. The default is direct approach.
theta	Type of theta values used. They can be "quadrature", which is -3, -2.9, -2.8, -2.7...2.9, 3, and "estimated", which is estimated theta values. The default is quadrature.
information	Types of information.They can be "item", which is overall item information, and "test", which is overall test information. The default is overall item information.
items	The items of which information to be calculated. The default is all the items.

Value

Selected item information or overall test information

Examples

Data <- c(1,2)
Data <- matrix(Data,nrow = 1)
pairmap <- c(1,3,2,4)
pairmap <- matrix(pairmap,nrow = 2)
ind <- c(1,2,1,2)
ParInits <- c(1, 1, 1, 1,1,-1, -1,1, -1,-1,-1,-1)
ParInits <- matrix(ParInits, ncol = 3)
mod <- fcirt(fcirt.Data=Data,pairmap=pairmap,ind=ind,ParInits=ParInits,iter=3,warmup=1,chains=1)
information(mod, approach="direct", theta="quadrature", information="item", items=1)

---