Package 'dexter'

Description

Dexter provides a comprehensive solution for managing and analyzing educational test data.

Details

The main features are:

• project databases providing a structure for storing data about persons, items, responses and booklets.

• methods to assess data quality using Classical test theory and plots.

• CML calibration of the extended nominal response model and interaction model.

To learn more about dexter, start with the vignettes: 'browseVignettes(package="dexter")'

Dexter uses the following global options

• 'dexter.use_tibble' return tibbles instead of data.frames, defaults to FALSE

• 'dexter.progress' show progress bars, defaults to TRUE in interactive sessions

• 'dexter.max_cores' set a maximum number of cores that dexter will use, defaults to the minimum of 'Sys.getenv("OMP_THREAD_LIMIT")' and 'getOption("Ncpus")', otherwise unlimited.

Author(s)

Maintainer: Jesse Koops [email protected]

Authors:

• Gunter Maris

• Timo Bechger

• Ivailo Partchev

See Also

Useful links:

• https://dexter-psychometrics.github.io/dexter/

• Report bugs at https://github.com/dexter-psychometrics/dexter/issues

Description

Computes estimates of ability for persons or for booklet scores

Usage

ability(
  dataSrc,
  parms,
  predicate = NULL,
  method = c("MLE", "EAP", "WLE"),
  prior = c("normal", "Jeffreys"),
  parms_draw = "average",
  mu = 0,
  sigma = 4,
  merge_within_persons = FALSE
)

ability_tables(
  parms,
  design = NULL,
  method = c("MLE", "EAP", "WLE"),
  prior = c("normal", "Jeffreys"),
  parms_draw = "average",
  mu = 0,
  sigma = 4
)

Arguments

Details

MLE estimates of ability will produce -Inf and Inf estimates for the minimum (=0) and the maximum score on a booklet. If this is undesirable, we advise to use WLE. The WLE was proposed by Warm (1989) to reduce bias in the MLE and is also known as the Warm estimator.

Value

ability

a data.frame with columns: booklet_id, person_id, booklet_score, theta and optionally se (standard error)

ability_tables

a data.frame with columns: booklet_id, booklet_score, theta and optionally se (standard error)

References

Warm, T. A. (1989). Weighted likelihood estimation of ability in item response theory. Psychometrika, 54(3), 427-450.

Examples

db = start_new_project(verbAggrRules, ":memory:")
add_booklet(db, verbAggrData, "agg")

f = fit_enorm(db)

mle = ability_tables(f, method="MLE")
eap = ability_tables(f, method="EAP", mu=0, sigma=1)
wle = ability_tables(f, method="WLE")

plot(wle$booklet_score, wle$theta, xlab="test-score", ylab="ability est.", pch=19)
points(mle$booklet_score, mle$theta, col="red", pch=19,)
points(eap$booklet_score, eap$theta, col="blue", pch=19)
legend("topleft", legend = c("WLE", "MLE", "EAP N(0,1)"), 
        col = c("black", "red", "blue"), bty = "n",pch = 19)

close_project(db)

Description

Add item response data in long or wide format.

Usage

add_booklet(db, x, booklet_id, auto_add_unknown_rules = FALSE)

add_response_data(
  db,
  data,
  design = NULL,
  missing_value = "NA",
  auto_add_unknown_rules = FALSE
)

Arguments

Details

It is a common practice to keep response data in tables where each row contains the responses from a single person. add_booklet is provided to input data in that form, one booklet at a time.

If the dataframe x contains a variable named person_id this variable will be used to identify unique persons. It is assumed that a single person will only make a single booklet once, otherwise an error will be generated.

If a person_id is not supplied, dexter will generate unique person_id's for each row of data.

Any column whose name has an exact match in the scoring rules inputted with function start_new_project will be treated as an item; any column whose name has an exact match in the person_properties will be treated as a person property. If a name matches both a person_property and an item_id, the item takes precedence. Columns other than items, person properties and person_id will be ignored.

add_response_data can be used to add data that is already normalized. This function takes a data.frame in long format with columns person_id, booklet_id, item_id and response such as can usually be found in databases for example. For booklets that are not already known in your project, you need to specify the design via the design argument. Failure to do so will result in an error. Responses to items that should be there according to the design but which do not have a corresponding row in data will be added with missing_value used for the response. If this missing value is not defined in your scoring rules and auto_add_unknown_rules is set to FALSE, this will lead to an error message.

Note that responses are always treated as strings (in both functions), and NA values are transformed to the string "NA".

Value

A list with information about the recent import.

Examples

db = start_new_project(verbAggrRules, ":memory:", 
                       person_properties=list(gender="unknown"))
head(verbAggrData)
add_booklet(db, verbAggrData, "agg")      

close_project(db)

Description

Add, change or define item properties in a dexter project

Usage

add_item_properties(db, item_properties = NULL, default_values = NULL)

Arguments

Details

When entering response data in the form of a rectangular person x item table, it is easy to provide person properties but practically impossible to provide item properties. This function provides a possibility to do so.

Note that is is not possible to add new items with this function, use touch_rules if you want to add new items to your project.

Value

nothing

See Also

fit_domains, profile_plot for possible uses of item_properties

Examples

## Not run: \donttest{
db = start_new_project(verbAggrRules, "verbAggression.db")
head(verbAggrProperties)
add_item_properties(db, verbAggrProperties)
get_items(db) 

close_project(db)
}
## End(Not run)

Description

Add, change or define person properties in a dexter project. Person properties defined here will also be automatically imported with add_booklet

Usage

add_person_properties(db, person_properties = NULL, default_values = NULL)

Arguments

Details

Due to limitations in the sqlite database backend that we use, the default values for a person property can only be defined once for each person_property

Value

nothing

Description

This is just an alias for DBI::dbDisconnect(db), included for completeness

Usage

close_project(db)

Arguments

Description

extract equating information

Usage

## S3 method for class 'p2pass'
coef(object, ...)

Arguments

Value

A data.frame with columns:

booklet_id

id of the target booklet

score_new

score on the target booklet

probability_to_pass

probability to pass on the reference test given score_new

true_positive

proportion that correctly passes

sensitivity

The proportion of positives that are correctly identified as such

specificity

The proportion of negatives that are correctly identified as such

proportion

proportion in sample with score_new

Description

extract enorm item parameters

Usage

## S3 method for class 'prms'
coef(object, hpd = 0.95, what = c("items", "var", "posterior"), ...)

Arguments

Details

The parametrisation of IRT models is far from uniform and depends on the author. Dexter uses the following parametrisation for the extended Nominal Response Model (NRM):

$P(X=a_j|\beta,\theta) = \frac{\exp\left(a_j\theta-\sum_{g=1}^{j}\beta_g(a_g-a_{g-1})\right)}{1+\sum_h \exp\left(a_h\theta-\sum_{g=1}^{h}\beta_g(a_g-a_{g-1})\right)}$

where $a_j$ is a shorthand for the integer score belonging to the j-th category of an item.

For dichotomous items with $a_1=1$ (i.e. the only possible scores are 0 and 1) this formula simplifies to the standard Rasch model: $P(x=1|\beta,\theta)=\frac{\exp(\theta-\beta)}{1+\exp(\theta-\beta)}$. For polytomous items, when all scores are equal to the categories (i.e. $a_j=j$ for all $j$) the NRM is equal to the Partial Credit Model, although with a different parametrisation than is commonly used. For dichotomous items and for all polytomous items where $a_j-a_{j-1}$ is constant, the formulation is equal to the OPLM.

Value

Depends on the calibration method and the value of 'what'. For what="items":

CML calibration

a data.frame with columns: item_id, item_score, beta, SE_beta

Bayesian calibration

a data.frame with columns: item_id, item_score, mean_beta, SD_beta, <hpd_b_left>, <hpd_b_right>

If what="var" or what="posterior" then a matrix is returned with the variance-covariance matrix or the posterior draws respectively.

Description

This function is useful to inspect incomplete designs

Usage

design_info(dataSrc, predicate = NULL)

Arguments

Value

a list with the following components

design

a data.frame with columns booklet_id, item_id, item_position, n_persons

connected_booklets

a data.frame with columns booklet_id, group; booklets with the same 'group' are connected to each other.

connected

TRUE/FALSE indicating whether the design is connected or not

testlets

a data.frame with columns item_id and testlet; items within the same testlet always occur together in a booklet

adj_matrix

list of two adjacency matrices: *weighted_by_items* and *weighted_by_persons*; These matrices can be useful in visually inspecting the design using a package like *igraph*

Description

Exploratory test for Differential Item Functioning

Usage

DIF(dataSrc, person_property, predicate = NULL)

Arguments

Details

Tests for equality of relative item/category difficulties across groups. Supplements the confirmatory approach of the profile plot.

Value

An object of class DIF_stats holding statistics for overall-DIF and a matrix of statistics for DIF in the relative position of item-category parameters in the beta-parameterization where they represent locations on the ability scale where adjacent categories are equally likely. If there is DIF, the function 'plot' can be used to produce an image of the pairwise DIF statistics.

References

Bechger, T. M. and Maris, G (2015); A Statistical Test for Differential Item Pair Functioning. Psychometrika. Vol. 80, no. 2, 317-340.

See Also

A plot of the result is produced by the function plot.DIF_stats

Examples

db = start_new_project(verbAggrRules, ":memory:", person_properties=list(gender='unknown'))
add_booklet(db, verbAggrData, "agg")
dd = DIF(db,person_property="gender")
print(dd)
plot(dd)
str(dd)

close_project(db)

Description

Produce a diagnostic distractor plot for an item

Usage

distractor_plot(
  dataSrc,
  item_id,
  predicate = NULL,
  legend = TRUE,
  curtains = 10,
  adjust = 1,
  col = NULL,
  ...
)

Arguments

Details

Customization of title and subtitle can be done by using the arguments main and sub. These arguments can contain references to the variables item_id, booklet_id, item_position(if available), pvalue, rit and rir. References are made by prefixing these variables with a dollar sign. Variable names may be postfixed with a sprintf style format string, e.g. distractor_plot(db, main='item: $item_id', sub='Item rest correlation: $rir:.2f')

Value

Silently, a data.frame of response categories and colors used. Potentially useful if you want to customize the legend or print it separately

Description

Estimate the parameters of the Rasch model and the Interaction model

Usage

fit_domains(dataSrc, item_property, predicate = NULL)

Arguments

Details

We have generalised the interaction model for items having more than two (potentially, a largish number) of response categories. This function represents scores on subtests as super-items and analyses these as normal items.

Value

An object of class imp holding results for the Rasch model and the interaction model.

See Also

plot.rim, fit_inter, add_item_properties

Examples

db = start_new_project(verbAggrRules, ":memory:")
add_booklet(db, verbAggrData, "agg")
add_item_properties(db, verbAggrProperties)
mSit = fit_domains(db, item_property= "situation")
plot(mSit)

close_project(db)

Description

Fits an Extended NOminal Response Model (ENORM) using conditional maximum likelihood (CML) or a Gibbs sampler for Bayesian estimation.

Usage

fit_enorm(
  dataSrc,
  predicate = NULL,
  fixed_params = NULL,
  method = c("CML", "Bayes"),
  nDraws = 1000,
  merge_within_persons = FALSE
)

Arguments

Details

To support some flexibility in fixing parameters, fixed_params can be a dexter prms object or a data.frame. If a data.frame, it should contain the columns item_id, item_score and a difficulty parameter. Three types of parameters are supported:

delta/beta

thresholds between subsequent item categories

eta

item-category parameters

b

exp(-eta)

Each type corresponds to a different parametrization of the model.

Value

An object of type prms. The prms object can be cast to a data.frame of item parameters using function coef or used directly as input for other Dexter functions.

References

Maris, G., Bechger, T.M. and San-Martin, E. (2015) A Gibbs sampler for the (extended) marginal Rasch model. Psychometrika. 80(4), 859-879.

Koops, J. and Bechger, T.M. and Maris, G. (in press); Bayesian inference for multistage and other incomplete designs. In Research for Practical Issues and Solutions in Computerized Multistage Testing. Routledge, London.

See Also

functions that accept a prms object as input: ability, plausible_values, plot.prms, and plausible_scores

Description

Estimate the parameters of the Interaction model and the Rasch model

Usage

fit_inter(dataSrc, predicate = NULL)

Arguments

Details

Unlike the Rasch model, the interaction model cannot be computed concurrently for a whole design of test forms. This function therefore fits the Rasch model and the interaction model on complete data. This typically consist of responses to items in one booklet but can also consist of the intersection (common items) in two or more booklets. If the intersection is empty (no common items for all persons), the function will exit with an error message.

Value

An object of class rim holding results for the Rasch model and the interaction model.

See Also

plot.rim, fit_domains

Examples

db = start_new_project(verbAggrRules, ":memory:")
add_booklet(db, verbAggrData, "agg")

m = fit_inter(db, booklet_id=='agg')
plot(m, "S1DoScold", show.observed=TRUE)

close_project(db)

Description

Retrieve information about the booklets entered in the db so far

Usage

get_booklets(db)

Arguments

Value

A data frame with columns: booklet_id, n_persons, n_items and booklet_max_score. booklet_max_score gives the maximum theoretically possible score according to the scoring rules

Description

Retrieve all items that have been entered in the db so far by booklet and position in the booklet

Usage

get_design(
  dataSrc,
  format = c("long", "wide"),
  rows = c("booklet_id", "item_id", "item_position"),
  columns = c("item_id", "booklet_id", "item_position"),
  fill = NA
)

Arguments

Value

A data.frame with the design. The contents depend on the rows, columns and format parameters if format is 'long' a data.frame with columns: booklet_id, item_id, item_position (if available) if format is 'wide' a data.frame with the rows defined by the rows parameter and the columns by the columns parameter, with the remaining variable (i.e. item_id, booklet_id or item_position) making up the cells

Description

Retrieve all items that have been entered in the db so far together with the item properties

Usage

get_items(db)

Arguments

Value

A data frame with column item_id and a column for each item property

Description

Retrieve all persons/respondents that have been entered in the db so far together with their properties

Usage

get_persons(db)

Arguments

Value

A data frame with columns person_id and columns for each person_property

Description

These functions are meant for people who want to develop their own models based on the data management structure of dexter. The benefit is some extra speed and less memory usage compared to using get_responses or get_testscores. The return value of get_resp_data can be used as the 'dataSrc' argument in analysis functions.

Usage

get_resp_data(
  dataSrc,
  qtpredicate = NULL,
  extra_columns = NULL,
  summarised = FALSE,
  env = NULL,
  protect_x = TRUE,
  retain_person_id = TRUE,
  merge_within_persons = FALSE,
  parms_check = NULL,
  raw = FALSE
)

get_resp_matrix(dataSrc, qtpredicate = NULL, env = NULL)

Arguments

Details

Regular users are advised not to use these functions as incorrect use can crash your R-session or lead to unexpected results.

Value

get_resp_data

returns a list with class 'dx_resp_data' with elements

x

when summarised is FALSE, a tibble(person_id, booklet_id, item_id, item_score, booklet_score [, extra_columns]), sorted in such a way that all rows pertaining to the same person-booklet are together

when summarised is TRUE, a tibble(person_id, booklet_id, booklet_score [, extra_columns])

design

tibble(booklet_id, item_id), sorted

get_resp_matrix

returns a matrix of item scores as commonly used in other IRT packages, facilitating easy connection of your own package to the data management capabilities of dexter

Description

Extract data from a dexter database

Usage

get_responses(
  dataSrc,
  predicate = NULL,
  columns = c("person_id", "item_id", "item_score")
)

Arguments

Details

Many functions in Dexter accept a data source and a predicate. Predicates are extremely flexible but they have a few limitations because they work on the individual response level. It is therefore not possible for example, to remove complete person cases from an analysis based on responses to a single item by using just a predicate expression.

For such cases, Dexter supports selecting the data and manipulating it before passing it back to a Dexter function or possibly doing something else with it. The following example will hopefully clarify this.

Value

a data.frame of responses

Examples

## Not run: 
# goal: fit the extended nominal response model using only persons 
# without any missing responses
library(dplyr)

# the following would not work since it will omit only the missing 
# responses, not the persons; which is not what we want in this case
wrong = fit_enorm(db, response != 'NA')

# to select on an aggregate level, we need to gather the data and 
# manipulate it ourselves
data = get_responses(db, 
   columns=c('person_id','item_id','item_score','response')) |>
   group_by(person_id) |>
   mutate(any_missing = any(response=='NA')) |>
   filter(!any_missing)

correct = fit_enorm(data)


## End(Not run)

Description

Retrieve the scoring rules currently present in the dexter project db

Usage

get_rules(db)

Arguments

Value

data.frame of scoring rules containing columns: item_id, response, item_score

Description

Supplies the sum of item scores for each person selected.

Usage

get_testscores(dataSrc, predicate = NULL)

Arguments

Value

A tibble with columns person_id, item_id, booklet_score

Description

Inspect the variables defined in your dexter project and their datatypes

Usage

get_variables(db)

Arguments

Details

The variables in Dexter consist of the item properties and person properties you specified and a number of reserved variables that are automatically defined like response and booklet_id.

Variables in Dexter are most useful when used in predicate expressions. A number of functions can take a dataSrc argument and an optional predicate. Predicates are a concise and flexible way to filter data for the different psychometric functions in Dexter.

The variables can also be used to retrieve data in get_responses

Value

a data.frame with name and type of the variables defined in your dexter project

Description

Test individual differences

Usage

individual_differences(dataSrc, predicate = NULL)

Arguments

Details

This function uses a score distribution to test whether there are individual differences in ability. First, it estimates ability based on the score distribution. Then, the observed distribution is compared to the one expected from the single estimated ability. The data are typically from one booklet but can also consist of the intersection (i.e., the common items) of two or more booklets. If the intersection is empty (i.e., no common items for all persons), the function will exit with an error message.

Value

An object of type tind. Printing the object will show test results. Plotting it will produce a plot of expected and observed score frequencies. The former under the hypothesis that there are no individual differences.

Examples

db = start_new_project(verbAggrRules, ":memory:")
add_booklet(db, verbAggrData, "agg")

dd = individual_differences(db)
print(dd)
plot(dd)

close_project(db)

Description

returns information function, expected score function, score simulation function, or score distribution for a single item, an arbitrary group of items or all items

Usage

information(
  parms,
  items = NULL,
  booklet_id = NULL,
  parms_draw = c("average", "sample")
)

expected_score(
  parms,
  items = NULL,
  booklet_id = NULL,
  parms_draw = c("average", "sample")
)

r_score(
  parms,
  items = NULL,
  booklet_id = NULL,
  parms_draw = c("average", "sample")
)

p_score(
  parms,
  items = NULL,
  booklet_id = NULL,
  parms_draw = c("average", "sample")
)

Arguments

Value

Each function returns a new function which accepts a vector of theta's. These return the following values:

information

an equal length vector with the information estimate at each value of theta.

expected_score

an equal length vector with the expected score at each value of theta

r_score

a matrix with length(theta) rows and one column for each item containing simulated scores based on theta. To obtain test scores, use rowSums on this matrix

p_score

a matrix with length(theta) rows and one column for each possible sumscore containing the probability of the score given theta

Examples

db = start_new_project(verbAggrRules,':memory:')
add_booklet(db,verbAggrData, "agg")
p = fit_enorm(db)

# plot information function for single item

ifun = information(p, "S1DoScold")

plot(ifun,from=-4,to=4)

# compare test information function to the population ability distribution

ifun = information(p, booklet="agg")

pv = plausible_values(db,p)

op = par(no.readonly=TRUE)
par(mar = c(5,4,2,4))

plot(ifun,from=-4,to=4, xlab='theta', ylab='test information')

par(new=TRUE)

plot(density(pv$PV1), col='green', axes=FALSE, xlab=NA, ylab=NA, main=NA)
axis(side=4)
mtext(side = 4, line = 2.5, 'population density (green)')

par(op)
close_project(db)

Description

For multiple choice items that will be scored as 0/1, derive the scoring rules from the keys to the correct responses

Usage

keys_to_rules(keys, include_NA_rule = FALSE)

Arguments

Details

This function might be useful in setting up the scoring rules when all items are multiple-choice and scored as 0/1.

The input data frame must contain the exact id of each item, the number of options, and the key. If the keys are all integers, it will be assumed that responses are coded as 1 through noptions. If they are all letters, it is assumed that responses are coded as A,B,C,... All other cases result in an error.

Value

A data frame that can be used as input to start_new_project

Description

Estimates correlations between latent traits using plausible values as described in Marsman, et al. (2022). An item_property is used to distinguish the different scales.

Usage

latent_cor(
  dataSrc,
  item_property,
  predicate = NULL,
  nDraws = 500,
  hpd = 0.95,
  use = "complete.obs"
)

Arguments

Details

This function uses plausible values so results may differ slightly between calls.

Value

List containing a estimated correlation matrix, the corresponding standard deviations, and the lower and upper limits of the highest posterior density interval

References

Marsman, M., Bechger, T. M., & Maris, G. K. (2022). Composition algorithms for conditional distributions. In Essays on Contemporary Psychometrics (pp. 219-250). Cham: Springer International Publishing.

Description

Opens a database created by function start_new_project

Usage

open_project(db_name = "dexter.db")

Arguments

Value

a database connection object

Description

Draw plausible, i.e. posterior predictive sumscores on a set of items.

Usage

plausible_scores(
  dataSrc,
  parms = NULL,
  predicate = NULL,
  items = NULL,
  parms_draw = c("sample", "average"),
  covariates = NULL,
  nPS = 1,
  prior_dist = c("normal", "mixture"),
  keep.observed = TRUE,
  by_item = FALSE,
  merge_within_persons = FALSE
)

Arguments

Details

A typical use of this function is to generate plausible scores on a complete item bank when data is collected using an incomplete design

Value

A data.frame with columns booklet_id, person_id, booklet_score and nPS plausible scores named PS1...PSn.

Description

Draws plausible values based on test scores

Usage

plausible_values(
  dataSrc,
  parms = NULL,
  predicate = NULL,
  covariates = NULL,
  nPV = 1,
  parms_draw = c("sample", "average"),
  prior_dist = c("normal", "mixture"),
  merge_within_persons = FALSE
)

Arguments

Details

When the item parameters are estimated using fit_enorm(..., method='Bayes') and parms_draw = 'sample', the uncertainty of the item parameters estimates is taken into account when drawing multiple plausible values.

In there are covariates, the prior distribution is a hierarchical normal with equal variances across groups. When there is only one group this becomes a regular normal distribution. When there are no covariates and prior_dist = "mixture", the prior is a mixture distribution of two normal distributions which gives a little more flexibility than a normal prior.

Value

A data.frame with columns booklet_id, person_id, booklet_score, any covariate columns, and nPV plausible values named PV1...PVn.

References

Marsman, M., Maris, G., Bechger, T. M., and Glas, C.A.C. (2016) What can we learn from plausible values? Psychometrika. 2016; 81: 274-289. See also the vignette.

Examples

db = start_new_project(verbAggrRules, ":memory:", 
   person_properties=list(gender="<unknown>"))
add_booklet(db, verbAggrData, "agg")
add_item_properties(db, verbAggrProperties)

f=fit_enorm(db)
pv_M=plausible_values(db,f,(mode=="Do")&(gender=="Male"))
pv_F=plausible_values(db,f,(mode=="Do")&(gender=="Female"))

par(mfrow=c(1,2))

plot(ecdf(pv_M$PV1), 
   main="Do: males versus females", xlab="Ability", col="red")
lines(ecdf(pv_F$PV1), col="green")
legend(-2.2,0.9, c("female", "male") , 
   lty=1, col=c('green', 'red'), bty='n', cex=.75)

pv_M=plausible_values(db,f,(mode=="Want")&(gender=="Male"))
pv_F=plausible_values(db,f,(mode=="Want")&(gender=="Female"))

plot(ecdf(pv_M$PV1), 
   main="Want: males versus females", xlab=" Ability", col="red")
lines(ecdf(pv_F$PV1),col="green")
legend(-2.2,0.9, c("female", "male") , 
   lty=1, col=c('green', 'red'), bty='n', cex=.75)
   
   
close_project(db)

Description

plot method for pairwise DIF statistics

Usage

## S3 method for class 'DIF_stats'
plot(x, items = NULL, itemsX = items, itemsY = items, alpha = 0.05, ...)

Arguments

Details

Plotting produces an image of the matrix of pairwise DIF statistics. The statistics are standard normal deviates and colored to distinguish significant from non-significant values. If there is no DIF, a proportion alpha off the cells will be colored significant by chance alone.

References

Feskens, R., Fox, J. P., & Zwitser, R. (2019). Differential item functioning in PISA due to mode effects. In Theoretical and Practical Advances in Computer-based Educational Measurement (pp. 231-247). Springer, Cham.

Description

Plot equating information from probability_to_pass

Usage

## S3 method for class 'p2pass'
plot(
  x,
  what = c("all", "equating", "sens/spec", "roc"),
  booklet_id = NULL,
  ...
)

Arguments

Description

The plot shows 'fit' by comparing the expected score based on the model (grey line) with the average scores based on the data (black line with dots) for groups of students with similar estimated ability.

Usage

## S3 method for class 'prms'
plot(
  x,
  item_id = NULL,
  dataSrc = NULL,
  predicate = NULL,
  nbins = 5,
  ci = 0.95,
  add = FALSE,
  col = "black",
  col.model = "grey80",
  ...
)

Arguments

Details

The standard plot shows the fit against the sample on which the parameters were fitted. If dataSrc is provided, the fit is shown against the observed data in dataSrc. This may be useful for plotting the fit in different subgroups as a visual test for item level DIF. The confidence intervals denote the uncertainty about the predicted pvalues within the ability groups for the sample size in dataSrc (if not NULL) or the original data on which the model was fit.

Value

Silently, a data.frame with observed and expected values possibly useful to create a numerical fit measure.

Description

Plot the item-total regressions fit by the interaction (or Rasch) model

Usage

## S3 method for class 'rim'
plot(
  x,
  items = NULL,
  summate = TRUE,
  overlay = FALSE,
  curtains = 10,
  show.observed = TRUE,
  ...
)

Arguments

Details

Customization of title and subtitle can be done by using the arguments main and sub. These arguments can contain references to the variables item_id (if overlay=FALSE) or model (if overlay=TRUE) by prefixing them with a dollar sign, e.g. plot(m, main='item: $item_id')

Description

Given response data that form a connected design, compute the probability to pass on the reference set conditional on each score on one or more target tests.

Usage

probability_to_pass(
  dataSrc,
  parms,
  ref_items,
  pass_fail,
  predicate = NULL,
  target_booklets = NULL,
  nDraws = 1000
)

Arguments

Details

Note that this function is computationally intensive and can take some time to run, especially when computing the probability to pass for multiple target booklets. Further technical details can be found in a vignette.

Value

An object of type p2pass. Use coef() to extract the probablity to pass for each booklet and score. Use plot() to plot the probabilities, sensitivity and specificity or a ROC-curve.

See Also

The function used to plot the results: plot.p2pass

Description

Profile plot

Usage

profile_plot(
  dataSrc,
  item_property,
  covariate,
  predicate = NULL,
  model = c("IM", "RM"),
  x = NULL,
  col = NULL,
  col.diagonal = "lightgray",
  ...
)

Arguments

Details

Profile plots can be used to investigate whether two (or more) groups of respondents attain the same test score in the same way. The user must provide a (meaningful) classification of the items in two non-overlapping subsets such that the test score is the sum of the scores on the subsets. The plot shows the probabilities to obtain any combinations of subset scores with thin gray lines indicating the combinations that give the same test score. The thick lines connect the most likely combination for each test score in each group. When applied to educational test data, the plots can be used to detect differences in the relative difficulty of (sets of) items for respondents that belong to different groups and are matched on the test score. This provides a content-driven way to investigate differential item functioning.

Examples

db = start_new_project(verbAggrRules, ":memory:", 
                         person_properties=list(gender="unknown"))
add_booklet(db, verbAggrData, "agg")
add_item_properties(db, verbAggrProperties)
profile_plot(db, item_property='mode', covariate='gender')

close_project(db)

Description

Expected and observed domain scores, conditional on the test score, per person or test score. Domains are specified as categories of items using item_properties.

Usage

profile_tables(parms, domains, item_property, design = NULL)

profiles(
  dataSrc,
  parms,
  item_property,
  predicate = NULL,
  merge_within_persons = FALSE
)

Arguments

Details

When using a unidimensional IRT Model like the extended nominal response model in dexter (see: fit_enorm), the model is as a rule to simple to catch all the relevant dimensions in a test. Nevertheless, a simple model is quite useful in practice. Profile analysis can complement the model in this case by indicating how a test-taker, conditional on her/his test score, performs on a number of pre-specified domains, e.g. in case of a mathematics test the domains could be numbers, algebra and geometry or in case of a digital test the domains could be animated versus non-animated items. This can be done by comparing the achieved score on a domain with the expected score, given the test score.

Value

profiles

a data.frame with columns person_id, booklet_id, booklet_score, <item_property>, domain_score, expected_domain_score

profile_tables

a data.frame with columns booklet_id, booklet_score, <item_property>, expected_domain_score

References

Verhelst, N. D. (2012). Profile analysis: a closer look at the PISA 2000 reading data. Scandinavian Journal of Educational Research, 56 (3), 315-332.

Description

Simulate item scores conditional on test scores using the interaction model

Usage

r_score_IM(m, scores)

Arguments

Value

a matrix with item scores, one column per item and one row per test score. Row order equal to scores

Description

A data set with rated data. A number of student performances are rated twice on several aspects by independent judges. The ratings are binary and have been summed following the theory discussed by Maris and Bechger (2006, Handbook of Statistics). Data are a small subset of data collected on the State Exam Dutch as a second language for Speaking.

Format

A data set with 75 rows and 15 columns.

Description

A data set of item properties related to the rated data. These are the aspects: IH = content, WZ = word choice and phrasing, and WK = vocabulary.

Format

A data set with 14 rows and 2 columns: item_id and aspect

Description

A set of (trivial) scoring rules for the rated data set

Format

A data set with 42 rows and 3 columns (item_id, response, item_score).

Description

Read item parameters from oplm PAR or CML files

Usage

read_oplm_par(par_path)

Arguments

Details

It is very occasionally useful to calibrate new items on an existing scale. This function offers the possibility to read parameters from the proprietary oplm format so that they can be used to fix a new calibration in Dexter on an existing scale of items that were calibrated in oplm.

Value

depends on the input. For .PAR files a data.frame with columns: item_id, item_score, beta, nbr, for .CML files also several statistics columns that are outputted by OPLM as part of the calibration.

Examples

## Not run: 
\donttest{
par = read_oplm_par('/parameters.PAR')
f = fit_enorm(db, fixed_params=par)
}
## End(Not run)

Description

Set performance standards on one or more test forms using the data driven direct consensus (3DC) method

Usage

standards_3dc(parms, design)

## S3 method for class 'sts_par'
coef(object, ...)

## S3 method for class 'sts_par'
plot(x, booklet_id = NULL, ...)

Arguments

Details

The data driven direct consensus (3DC) method of standard setting was invented by Gunter Maris and described in Keuning et. al. (2017). To easily apply this procedure, we advise to use the free digital 3DC application. This application can be downloaded from the Cito website, see the 3DC application download page. If you want to apply the 3DC method using paper forms instead, you can use the plot method to generate the forms from the sts_par object.

Although the 3DC method is used as explained in Keuning et. al., the method we use for computing the forms is a simple maximum likelihood scaling from an IRT model, described in Moe and Verhelst (2017)

Value

an object of type 'sts_par'

References

Keuning J., Straat J.H., Feskens R.C.W. (2017) The Data-Driven Direct Consensus (3DC) Procedure: A New Approach to Standard Setting. In: Blomeke S., Gustafsson JE. (eds) Standard Setting in Education. Methodology of Educational Measurement and Assessment. Springer, Cham

Moe E., Verhelst N. (2017) Setting Standards for Multistage Tests of Norwegian for Adult Immigrants In: Blomeke S., Gustafsson JE. (eds) Standard Setting in Education. Methodology of Educational Measurement and Assessment. Springer, Cham

See Also

how to make a database for the 3DC standard setting application: standards_db

Examples

library(dplyr)
db = start_new_project(verbAggrRules, ":memory:")
            
add_booklet(db, verbAggrData, "agg")
add_item_properties(db, verbAggrProperties)

design = get_items(db) |>
  rename(cluster_id='behavior')

f = fit_enorm(db)

sts_par = standards_3dc(f, design)

plot(sts_par)


# db_sts = standards_db(sts_par,'test.db',c('mildly aggressive','dangerously aggressive'))

Description

This function creates an export (an sqlite database file) which can be used by the 3DC application. This is a free application with which a standard setting session can be facilitated through a LAN network using the Chrome browser. The 3DC application can be downloaded from 3DC application download page

Usage

standards_db(
  par.sts,
  file_name,
  standards,
  population = NULL,
  group_leader = "admin"
)

Arguments

Description

Imports a complete set of scoring rules and starts a new project (database)

Usage

start_new_project(rules, db_name = "dexter.db", person_properties = NULL)

Arguments

Details

This package only works with closed items (e.g. likert, MC or possibly short answer) it does not score any open items. The first step to creating a project is to import an exhaustive list of all items and all admissible responses, along with the score that any of the latter will be given. Responses may be integers or strings but they will always be treated as strings. Scores must be integers, and the minimum score for an item must be 0. When inputting data, all responses not specified in the rules can optionally be treated as missing and ultimately scored 0, but it is good style to include the missing responses in the list. NA values will be treated as the string "NA"'.

Value

a database connection object.

Examples

head(verbAggrRules)
db_name = tempfile(fileext='.db')
db = start_new_project(verbAggrRules, db_name, 
                       person_properties = list(gender = "unknown"))

Description

Creates a dexter project database and fills it with response data based on a .dat and .scr file

Usage

start_new_project_from_oplm(
  dbname,
  scr_path,
  dat_path,
  booklet_position = NULL,
  responses_start = NULL,
  response_length = 1,
  person_id = NULL,
  missing_character = c(" ", "9"),
  use_discrim = FALSE,
  format = "compressed"
)

Arguments

Details

start_new_project_from_oplm builds a complete dexter database from a .dat and .scr file in the proprietary oplm format. Four custom variables are added to the database: booklet_on_off, oplm_marginal, item_local_on_off, item_global_on_off. These are taken from the .scr file and can be used in predicates in the various dexter functions.

Booklet_position and responses_start are usually inferred from the scr file but since they are sometimes misspecified in the scr file they can be overridden. Response_length is not inferred from the scr file since anything other than 1 is most often a mistake.

Value

a database connection object.

Examples

## Not run: \donttest{
db = start_new_project_from_oplm('test.db',
   'path_to_scr_file', 'path_to_dat_file', 
   booklet_position=c(1,3), responses_start=101,
   person_id=c(50,62))

prms = fit_enorm(db, 
   item_global_on_off==1 & item_local_on_off==1 & booklet_on_off==1)


}
## End(Not run)

Description

Show simple Classical Test Analysis statistics at item and test level

Usage

tia_tables(
  dataSrc,
  predicate = NULL,
  type = c("raw", "averaged", "compared"),
  max_scores = c("observed", "theoretical"),
  distractor = FALSE
)

Arguments

Value

A list containing:

Description

It is occasionally necessary to alter or add a scoring rule, e.g. in case of a key error. This function offers the possibility to do so and also allows you to add new items to your project

Usage

touch_rules(db, rules)

Arguments

Details

The rules should contain all rules that you want to change or add. This means that in case of a key error in a single multiple choice question, you typically have to change two rules.

Value

If the scoring rules pass a sanity check, a small summary of changes is printed and nothing is returned. Otherwise this function returns a data frame listing the problems found, with 4 columns:

item_id

id of the problematic item

less_than_two_scores

if TRUE, the item has only one distinct score

duplicated_responses

if TRUE, the item contains two or more identical response categories

min_score_not_zero

if TRUE, the minimum score of the item was not 0

Examples

## Not run: \donttest{
# given that in your dexter project there is an mc item with id 'itm_01', 
# which currently has key 'A' but you want to change it to 'C'.

new_rules = data.frame(item_id='itm_01', response=c('A','C'), item_score=c(0,1))
touch_rules(db, new_rules)
}
## End(Not run)

Description

A data set of self-reported verbal behaviour in different frustrating situations (Vansteelandt, 2000). The dataset also contains participants reported gender and scores on the 'anger' questionnaire.

Format

A data set with 316 rows and 26 columns.

Description

A data set of item properties related to the verbal aggression data

Format

A data set with 24 rows and 5 columns.

Description

A set of (trivial) scoring rules for the verbal aggression data set

Format

A data set with 72 rows and 3 columns (item_id, response, item_score).