# CATFunctions
This package provides functions for conducting computerized adaptive tests (CAT).
## Installation
You can install the development version from GitHub with:
```r
devtools::install_github("scottfrohn/CATFunctions") library(CATFunctions)
### Generating an Item Bank
# The `generate_item_bank` function generates an item bank with specified parameters for different IRT models.
# Example: Generate an item bank with 10 items using the 3PL model.
item_bank <- generate_item_bank(n_items = 10, model = "3pl")
print(item_bank)
### Calculating Probabilities
# The `prob` function calculates the probability of a correct response in an IRT model.
# Example: Calculate the probability of a correct response given ability level (`theta`) and item parameters (`a`, `b`, `c`).
theta <- 1.5
a <- 1.2
b <- 0.5
c <- 0.2
probability <- prob(theta, a, b, c)
print(probability)
### Calculating Item Information
# The `item_info` function calculates the item information for a given ability level (`theta`) based on the parameters of an IRT model.
# Example: Calculate the item information for a given ability level and item parameters.
item_information <- item_info(theta, a, b, c)
print(item_information)
### Calculating Item Information for an Item Bank
# The `item_info_bank` function calculates the item information for each item in an item bank across a specified range of ability levels (`theta`).
# Example: Calculate the item information for an item bank across a range of ability levels.
item_information_bank <- item_info_bank(item_bank)
print(item_information_bank)
### Calculating Item Characteristic Curves (ICCs) for an Item Bank
# The `item_ICC_bank` function calculates the item characteristic curves (ICCs) for each item in an item bank across a specified range of ability levels (`theta`).
# Example: Calculate the ICCs for an item bank across a range of ability levels.
item_ICCs <- item_ICC_bank(item_bank)
print(item_ICCs)
### Checking Lengths of Elements
# The `check_lengths` function checks whether all provided elements have the same length.
# Example: Check if multiple vectors have the same length.
vec1 <- c(1, 2, 3)
vec2 <- c("a", "b", "c")
vec3 <- c(TRUE, FALSE, TRUE)
lengths_equal <- check_lengths(vec1, vec2, vec3)
print(lengths_equal)
### Calculate Test Information Values
# The `test_info` function calculates test information across a range of theta values based on IRT parameters for a set of items.
# Example:
thetas <- seq(-3, 3, length.out = 100)
as <- rlnorm(10, meanlog = 0.1, sdlog = 0.2)
bs <- rnorm(10, mean = 0, sd = 1.5)
cs <- runif(10, min = 0, max = 0.35)
result <- test_info(thetas, as, bs, cs)
print(result)
### Maximum Likelihood Ability Estimation
# The `est_ability_mle` function estimates the most likely ability level of an individual given item parameters and observed responses by maximizing the log-likelihood function.
# Example: Estimate ability level based on responses and item parameters.
responses <- c(1, 0, 1, 1, 0)
as <- c(1.2, 1.0, 0.8, 1.1, 0.9)
bs <- c(-1, 0, 1, 2, -0.5)
cs <- c(0.2, 0.25, 0.15, 0.3, 0.1)
# Estimate without a kludge
ability_estimate <- est_ability_mle(responses, as, bs, cs)
print(ability_estimate)
# Estimate with a kludge
ability_estimate <- est_ability_mle(responses, as, bs, cs, kludge = FALSE)
print(ability_estimate)
### Initial Item Selection
# Selecting an initial item, given an item bank and ability estimate
# Example:
item_bank_df <- data.frame(
item_id = 1:10,
a = rlnorm(10, meanlog = 0.1, sdlog = 0.2),
b = rnorm(10, mean = 0, sd = 1.5),
c = runif(10, min = 0, max = 0.35)
)
result <- initial_item(item_bank_df, initial_ability = 0)
print(result)
### Update Table of Eligible Items
# Select the next item, given a bank of eligible items and a test event dataframe
# Example:
eligible_items_df <- data.frame(
item_id = 1:10,
a = rlnorm(10, meanlog = 0.1, sdlog = 0.2),
b = rnorm(10, mean = 0, sd = 1.5),
c = runif(10, min = 0, max = 0.35)
)
test_event_df <- data.frame(
order = integer(),
item_id = integer(),
a = numeric(),
b = numeric(),
c = numeric(),
response_score = numeric(),
current_ability = numeric(),
current_ability_se = numeric(),
item_selection_ts = as.POSIXct(character()),
response = numeric(),
response_ts = as.POSIXct(character())
)
test_event_df$current_ability <- 0
result <- next_item(eligible_items_df, test_event_df)
print(result)
### Score Responses
# Score a response and update ability estimate, given a test event dataframe, item id, and response.
# Example:
test_event_df <- data.frame(
order = integer(),
item_id = integer(),
a = numeric(),
b = numeric(),
c = numeric(),
response_score = numeric(),
current_ability = numeric(),
current_ability_se = numeric(),
item_selection_ts = as.POSIXct(character()),
response = numeric(),
response_ts = as.POSIXct(character())
)
test_event_df <- rbind(test_event_df, data.frame(
order = 1,
item_id = 1,
a = 1.2,
b = -0.5,
c = 0.2,
response_score = NA,
current_ability = NA,
current_ability_se = NA,
item_selection_ts = Sys.time(),
response = NA,
response_ts = as.POSIXct(NA)
))
test_event_df$current_ability <- 0
result <- score_response(test_event_df, item_id = 1, response = 1)
print(result)
### Stop the CAT
# Determine whether a test should be stopped, given a test event dataframe and stopping criteria
# Example:
test_event_df <- data.frame(
order = integer(),
item_id = integer(),
a = numeric(),
b = numeric(),
c = numeric(),
response_score = numeric(),
current_ability = numeric(),
current_ability_se = numeric(),
item_selection_ts = as.POSIXct(character()),
response = numeric(),
response_ts = as.POSIXct(character())
)
test_event_df <- rbind(test_event_df, data.frame(
order = 1,
item_id = 1,
a = 1.2,
b = -0.5,
c = 0.2,
response_score = 1,
current_ability = 0,
current_ability_se = 0.3,
item_selection_ts = Sys.time(),
response = 1,
response_ts = Sys.time()
))
result <- stop_test(test_event_df, max_items = 10, min_se = 0.3, min_items = 1)
print(result)
### Update Eligible Items
# Update the list of eligible items in a CAT, given an item bank and test event dataframe.
# Example:
item_bank_df <- data.frame(
item_id = 1:10,
a = rlnorm(10, meanlog = 0.1, sdlog = 0.2),
b = rnorm(10, mean = 0, sd = 1.5),
c = runif(10, min = 0, max = 0.35)
)
test_event_df <- data.frame(
item_id = c(1, 3, 5),
order = c(1, 2, 3),
a = c(1.2, 0.8, 1.1),
b = c(-1, 0, 1),
c = c(0.2, 0.25, 0.15),
response_score = c(1, 0, 1),
current_ability = c(NA, NA, NA),
current_ability_se = c(NA, NA, NA),
item_selection_ts = Sys.time(),
response = c(1, 0, 1),
response_ts = Sys.time()
)
result <- update_eligible_items(item_bank_df, test_event_df)
print(result)
### Simluate a CAT
# Given an item bank and vector of abilities, simulate a CAT for all abilities.
# Example usage
item_bank <- data.frame(
item_id = 1:10,
a = rlnorm(10, meanlog = 0.1, sdlog = 0.2),
b = rnorm(10, mean = 0, sd = 1.5),
c = runif(10, min = 0, max = 0.35)
)
abilities <- rnorm(5, mean = 0, sd = 1)
result <- simulate_cat(item_bank, abilities)
print(result)Contributions are welcome!
Please open an issue or submit a pull request.