GitHub

Generic interface

This page details the operations which should be supported by different ItemResponse elements, as well as traits for categorisation which can be used to dispatch to different operations.

Basic types

AbstractItemBank traits

Domain

FittedItemBanks.DomainType — Type
abstract type DomainType
DomainType(::AbstractItemBank) -> DomainType

Domain type for a item banks' item response functions. Used as a trait.

source
FittedItemBanks.DiscreteDomain — Type
abstract type DiscreteDomain <: DomainType

A discrete domain. Typically this is a sampled version of a continuous domain item bank.

Item response functions with discrete domains tend to support less operations than those with continuous domains.

source

Response

AbstractItemBank methods

Base.length — Method
length(item_bank::AbstractItemBank)

Returns the number of items in the item bank.

source
FittedItemBanks.subset — Function
function subset(item_bank::AbstractItemBank, idxs)

Return a new item bank of the same type, with the items at the given indices.

source
FittedItemBanks.item_bank_domain — Function
item_bank_domain(
    item_bank::AbstractItemBank;
    zero_symmetric,
    items,
    thresh
) -> Tuple{Any, Any}

Given an item bank, this function returns the domain of the item bank, i.e. the range (lo, hi) which includes for each item the range in which the the item response function is changing.

source
Base.eachindex — Method
eachindex(item_bank::AbstractItemBank) -> Base.OneTo

Returns an AbstractUnitRange of item indices for the item bank.

source
FittedItemBanks.item_params — Method
item_params(
    item_bank::AbstractItemBank,
    idx
) -> NamedTuple{(:difficulty, :discrimination), <:Tuple{Any, Any}}

Returns the raw parameters for the item at idx as a named tuple. This may return nothing for some item banks. This is debugging/informational use only. Use (ItemResponse)[@ref] for actual item response functions.

source

ItemResponse methods

FittedItemBanks.resp — Function
resp(ir::ItemResponse, θ) -> Float64  # For BooleanResponse item banks only
resp(ir::ItemResponse, outcome, θ) -> Float64

Return the value of the item response outcome function for the item response ir, the outcome outcome and the ability values θ. For BooleanResponse item banks, outcome can be omitted in which case the outcome is assumed to be true.

source
FittedItemBanks.resp_vec — Function
resp_vec(ir::ItemResponse, θ) -> AbstractVector{Float64}

Return the vector value of the item response function for the item response ir, the outcome outcome and the ability values θ.

The outcome at each index corresponds with the indices returned by the responses function.

source
FittedItemBanks.log_resp — Function
log_resp(ir::ItemResponse, θ) -> Float64  # For BooleanResponse item banks only
log_resp(ir::ItemResponse, outcome, θ) -> Float64

Return the logarithm of the value of the item response outcome function for the item response ir, the outcome outcome and the ability values θ.

This is the numerically stable counterpart of resp: implementations must not compute log(resp(ir, outcome, θ)), which underflows to -Inf in the tails. For BooleanResponse item banks, outcome can be omitted in which case the outcome is assumed to be true.

source
FittedItemBanks.log_resp_vec — Function
log_resp_vec(ir::ItemResponse, θ) -> AbstractVector{Float64}

Return the vector of logarithms of the item response function for the item response ir and the ability values θ.

The outcome at each index corresponds with the indices returned by the responses function. See log_resp.

source
FittedItemBanks.responses — Function
responses(ir::ItemResponse) -> Any

Returns an AbstractVector of possible outcomes for a given (ItemResponse)[@ref].

source

Logarithmic probabilities

FittedItemBanks.LogItemBank — Type
struct LogItemBank{ItemBankT<:AbstractItemBank} <: AbstractItemBank

Wraps inner, an item bank implementing log_resp and log_resp_vec, so that resp and resp_vec return LogarithmicNumbers.ULogarithmic probabilities. These retain small probabilities that would underflow in ordinary floating-point arithmetic. Log responses are forwarded directly to the inner bank.

source

Testing an item bank

When implementing an AbstractItemBank, either in another package or for inclusion here, use the Test extension to check the response interface:

using Test, FittedItemBanks

bank_tests = Base.get_extension(FittedItemBanks, :TestExt)
@testset "MyItemBank" begin
    # bank is an instance of your implementation.
    bank_tests.test_item_bank(bank, [-40.0, -0.7, 0.0, 0.9, 40.0];
        strictly_positive=true)
end

The helper checks metadata, category ordering, probability bounds and normalization, and agreement between scalar, vector, and log responses. Supply valid abilities for your bank: scalars for scalar domains, or vectors of length domdims(bank) for vector domains. Include ordinary and extreme finite abilities to exercise numerical stability.

Ordinary probability comparisons allow small absolute errors near zero, such as those from computing a complement as 1 - p; adjust rtol and atol if needed. Log normalization and scalar/vector log agreement are checked separately.

Set strictly_positive=true only if every category has mathematically positive probability at every supplied ability. This requires finite log probabilities even when ordinary probabilities underflow. Otherwise, leave it at its default false, which allows -Inf for exact zero probabilities.

For a raw PointsItemBank, use bank_tests.test_points_item_bank(bank) to check its item_xs/item_ys interface; use test_item_bank for continuous smoothed wrappers. Add model-specific tests for numerical accuracy, derivatives, and other operations beyond the response contract. If contributing a bank here, also add a fixture to test/invariants.jl.