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()
)
Arguments
| 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. |
Value
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.
Details
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.
Note
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.