traceline {irtQ}R Documentation

Compute Item/Test Characteristic Functions

Description

This function computes item category probabilities, item characteristic curves (ICCs), and the test characteristic curve (TCC) for a given set of theta values. The returned object can be used to visualize these functions using plot.traceline().

Usage

traceline(x, ...)

## Default S3 method:
traceline(x, theta, D = 1, ...)

## S3 method for class 'est_item'
traceline(x, theta, ...)

## S3 method for class 'est_irt'
traceline(x, theta, ...)

Arguments

x

A data frame containing item metadata (e.g., item parameters, number of categories, IRT model types, etc.); or an object of class est_irt obtained from est_irt(), or est_item from est_item().

See est_irt() or simdat() for more details about the item metadata. This data frame can be easily created using the shape_df() function.

...

Further arguments passed to or from other methods.

theta

A numeric vector of theta values at which item and test characteristic curves are computed.

D

A scaling constant used in IRT models to make the logistic function closely approximate the normal ogive function. A value of 1.7 is commonly used for this purpose. Default is 1.

Details

This function computes the item and test characteristic functions commonly used in IRT. For each item, the function computes the category response probabilities across a specified set of theta values. These probabilities are used to derive:

The output object can be visualized using the plot.traceline to inspect the relationship between ability levels (theta) and expected item/test scores.

If the input x is an object of class est_item or est_irt, the function automatically extracts item parameter estimates and the scaling constant D from the object. Otherwise, a properly formatted item metadata data frame must be provided.

Value

This function returns an object of class traceline, which is a list containing the following components:

prob.cats

A list of data frames containing the category response probabilities for each item across the specified theta values. Each data frame corresponds to an item, with rows representing theta values and columns representing response categories (e.g., "resp.0", "resp.1", ...).

icc

A numeric matrix representing ICCs. Each column corresponds to an item, and each row represents the expected item score at a given theta value. The column names are the item IDs.

tcc

A numeric vector representing the TCC, computed as the sum of expected item scores across all items at each theta value.

theta

A numeric vector of theta values at which the item and test information functions are evaluated. This matches the user-supplied theta argument.

Methods (by class)

Author(s)

Hwanggyu Lim hglim83@gmail.com

See Also

plot.traceline(), est_irt(), est_item()

Examples

## Example using a "-prm.txt" file exported from flexMIRT

# Import the "-prm.txt" output file from flexMIRT
flex_prm <- system.file("extdata", "flexmirt_sample-prm.txt", package = "irtQ")

# Read the item parameters and convert them into item metadata
test_flex <- bring.flexmirt(file = flex_prm, "par")$Group1$full_df

# Define a sequence of theta values
theta <- seq(-3, 3, 0.5)

# Compute item category probabilities, ICCs,
# and the TCC for the given theta values
traceline(x = test_flex, theta, D = 1)


[Package irtQ version 1.0.0 Index]