adapt_test: Adaptive test
In pmcharrison/psychTestRCAT: Computerised Adaptive Testing With PsychTestR

Description Usage Arguments Details Value Note

Defines an adaptive test for use within psychTestR.

adapt_test(
  label,
  item_bank,
  show_item,
  stopping_rule = stopping_rule.num_items(n = NULL),
  opt = adapt_test_options()
)

`label`	(Character scalar, e.g. 'MDT') A label for the test when saving the participant's results.
`item_bank`	(Data frame, or coerceable to such) Defines the item bank, the collection of items available for administration during the adaptive test. Each row should correspond to a different item. Four columns are mandatory, corresponding to the item's psychometric parameters according to item response theory: `discrimination` - The item's discrimination parameter, with higher values indicating that the item is better at discriminating between participants. `difficulty` - The item's difficulty parameter, with higher values corresponding to harder items. `guessing` - The item's guessing parameter, corresponding to the probability that a participant with no ability can nevertheless answer the item correctly. `inattention` - The item's inattention parameter, corresponding to the probability that a participant with infinite ability answers the question correctly. The data frame must also contain a column called `answer`, defining the correct answer for each item. These answers will be checked for equality with the answer output from `show_item` using `==`, which coerces to a shared class (e.g. numeric answers can be coerced to character answers). List-columns are not permitted. This argument must also provide sufficient information for presenting a particular item to the participant. When an item has been selected, the corresponding row from the item bank is extracted and passed to the `show_item` function, another of the arguments to `adapt_test`. The `show_item` function uses this row as a basis to display the item to the participant.
`show_item`	(Function, list, or psychTestR timeline) This function defines the logic for administering an item from its definition in `item_bank`. This function may take two forms: Single-page items - If your test item takes one psychTestR page to administer, `show_item` should be a function of the form `function(item, state, ...) {...}`. The `item` parameter will correspond to a row of the `item_bank` data frame. The `state` parameter (advanced use only) allows the `show_item` function to access additional information about the current psychTestR session, e.g. local variables (see `get_local`). The function should return a psychTestR `page` displaying the test item and storing the response in `answer(state)`; psychTestR's built-in question functions (e.g. `NAFC_page`) do the latter automatically. Multi-page items - If your test item takes multiple psychTestR pages to administer, `show_item` should be a list of psychTestR test elements or, equivalently, a psychTestR timeline as created by `new_timeline`). Mutability is achieved by using reactive pages (`reactive_page`), which can access the current value of `item` from the psychTestR session state object as follows: `psychTestR::get_local("item", state)`. When the timeline completes, `answer(state)` must be set to the participant's answer. If several pages contribute to the final answer, this may involve accumulating values in a temporary variable (see `get_local` and `set_local`). psychTestR's built-in question functions (e.g. `NAFC_page`) by default save each response to the psychTestR results list. This behaviour is unnecessary in `show_item`, because psychTestRCAT accumulates and saves its own store of item-wise results. It is therefore recommended to set `save_answer = FALSE` in these question functions.
`stopping_rule`	(Function) A stopping rule for determining when the test should terminate, as created by `new_stopping_rule`. In the common case where the test terminates after a set number of items, use `stopping_rule.num_items`, passing the number of items as a function parameter.
`opt`	(List) A list of further options as created by `adapt_test_options`.

This is the top-level function of the psychTestRCAT package. It defines adaptive tests within the framework of item response theory. An aadptive test is one that tailors item selection to the current test-taker on the basis of their performance during the test.

A psychTestR timeline representing the adaptive test. Once the adaptive test is complete, psychTestR saves three primary results into the results table:

ability - The participant's final ability estimate.
ability_sem - The standard error of the final ability estimate, as computed from the IRT model.
num_items - The number of items administered to the participant.

Further information, in particular item-by-item results, can be extracted from the metadata slot of the ability field. This can be accessed by loading psychTestR RDS results files. Alternatively, item-by-item results can be accessed using the function compile_trial_by_trial_results.

By default, adapt_test displays no feedback to the participant when they finish the test. Use cat.feedback.graph directly after adapt_test to display a feedback graph to the participant.

Ability estimation and item selection are performed using the catR package.

pmcharrison/psychTestRCAT documentation built on Sept. 12, 2020, 7:18 a.m.