API

ItemResponseModel

An abstract type representing an item response theory model.

Each implementation T <: ItemResponseModel must define the following traits:

• response_type: A valid ResponseType
• person_dimensionality: A valid Dimensionality
• item_dimensionality: A valid Dimensionality
• estimation_type: A valid EstimationType

Additionally T <: ItemResponseModel must implement the following interface:

• irf: An item response function returning the probability that a person with given ability estimate will answer an item with a particular response.
• iif: An item information function returning the information of answering with a particular response on an item given an ability estimate.
• fit: A function fitting an item response model of type T to observed data.
• getitemlocations: A function returning the item locations for a given item.
• getpersonlocations: A function returning the person locations for a given person.

Dimensionality

The Dimensionality of an ItemResponseModel defines whether or not the person and/or item parameters of the model are unidimensional or multidimensional.

Univariate <: Dimensionality

Defines that an ItemResponseModel has scalar valued parameters.

Multivariate <: Dimensionality

Defines that an ItemResponseModel has vector valued parameters.

item_dimensionality(::T) -> Dimensionality

Return the Dimensionality of the item parameters of an ItemResponseModel.

item_dimensionality(::T) -> Dimensionality

Return the Dimensionality of the person parameters of an ItemResponseModel.

EstimationType

The EstimationType of an ItemResponseModel describes the type of parameter estimation for the model.

PointEstimate <: EstimationType

Defines that the parameters of an ItemResponseModel are estimated by a single point estimate. Thus, parameters for a model with estimation_type(model) == PointEstimate are single real-valued numbers.

SamplingEstimate <: EstimationType

Defines that the parameters of an ItemResponseModel are estimated by a sampling procedure. Thus, parameters for a model with estimation_type(model) == SamplingEstimate are vectors of real-valued numbers where the length of the parameter vector is equal to the number of samples drawn.

estimation_type(::T) -> EstimationType

Return the EstimationType of an [ItemResponseModel].

ResponseType

The ResponseType defines the scale level of item responses for a given ItemResponseModel.

Dichotomous <: ResponseType

Defines that an ItemResponseModel has a binary response variable.

Nominal <: ResponseType

Defines that an ItemResponseModel has an unordered categorical response variable.

Ordinal <: ResponseType

Defines that an ItemResponseModel has an ordered categorical response variable.

Continous <: ResponseType

Defines that an ItemResponseModel has a continous response variable.

response_type(::T) -> ResponseType

Return the ResponseType of an ItemResponseModel.

checkresponsetype(::T, arr) where {T<:ResponseType}

Check if the responses in arr are valid for ResponseType T.

If all responses are valid, nothing is returned.

If any invalid responses are found, a DomainError is thrown.

expected_score(model::ItemResponseModel, theta; scoring_function)::Real
expected_score(model::ItemResponseModel, theta; scoring_function)::AbstractVector{<:Real}
expected_score(model::ItemResponseModel, theta, is; scoring_function)::Real
expected_score(model::ItemResponseModel, theta, is; scoring_function)::AbstractVector{<:Real}

Calculate the expected score of an ItemResponseModel.

Arguments

• model: An ItemResponseModel
• theta: The person parameter value(s)
• is: One or multiple item identifiers. If is is omitted, the expected score for the whole test is returned.

Keyword arguments

• scoring_function: A function mapping all possible response values y to arbitrary values. Must default to identity.

Return values

If estimation_type(model) == PointEstimate then expected_score must return a single scalar value.

If estimation_type(model) == SamplingEstimate then expected_score must return a vector of values with the length equal to the number of samples drawn.

fit(::Type{T}, data::AbstractMatrix, args...; kwargs...)::T where {T<:ItemResponseModel}

Fit an item response model to response data.

Arguments

• data: Observed data. If data is a response matrix, the columns must describe items and rows describe persons.
• args...: Additional arguments required to fit the ItemResponseModel

Keyword arguments

• kwargs...: Additional keyword arguments required to fit the ItemResponseModel

Return values

A fitted ItemResponseModel.

getitemlocations(model::ItemResponseModel, i, y)::Real
getitemlocations(model::ItemResponseModel, i, y)::AbstractVector{<:Real}
getitemlocations(model::ItemResponseModel, i, y)::AbstractMatrix{<:Real}

Get the item locations for an item from an ItemResponseModel.

Arguments

• model: An ItemResponseModel
• i: A unique item identifier
• y: Response value(s)

Return values

If item_dimensionality(model) == Univariate and estimation_type(model) == PointEstimate then getitemlocations must return a single scalar value.

If item_dimensionality(model) == Multivariate and estimation_type(model) == PointEstimate then getitemlocations must return a vector of values corresponding to the dimensionality of the item parameters.

If item_dimensionality(model) == Univariate and estimation_type(model) == SamplingEstimate then getitemlocations must return a vector of values with the length equal to the number of samples drawn.

If item_dimensionality(model) == Multivariate and estimation_type(model) == SamplingEstimate then getitemlocations must return a matrix with rows corresponding to the drawn samples and columns corresponding to the dimension of the item parameter.

getpersonlocations(model::ItemResponseModel, p)::Real
getpersonlocations(model::ItemResponseModel, p)::AbstractVector{<:Real}
getpersonlocations(model::ItemResponseModel, p)::AbstractMatrix{<:Real}

Get the person locations for an person from an ItemResponseModel.

Arguments

• model: An ItemResponseModel
• p: A unique person identifier

Return values

If person_dimensionality(model) == Univariate and estimation_type(model) == PointEstimate then getpersonlocations must return a single scalar value.

If person_dimensionality(model) == Multivariate and estimation_type(model) == PointEstimate then getpersonlocations must return a vector of values corresponding to the dimensionality of the person parameters.

If person_dimensionality(model) == Univariate and estimation_type(model) == SamplingEstimate then getpersonlocations must return a vector of values with the length equal to the number of samples drawn.

If person_dimensionality(model) == Multivariate and estimateion_type(model) == SamplingEstimate then getpersonlocations must return a matrix with rows corresponding to the drawn samples and columns corresponding to the dimension of the person parameter.

iif(model::ItemResponseModel, theta, i, y)::Real
iif(model::ItemResponseModel, theta, i, y)::AbstractVector{<:Real}

Argument

• model: An ItemResponseModel
• theta: The person parameter value(s)
• i: A unique item identifier
• y: Response value(s)

Return values

If estimation_type(model) == PointEstimate then the item information function must return a scalar value.

If estimation_type(model) == SamplingEstimate then the item information function must return a vector of values with the length equal to the number of samples drawn.

information(model::ItemResponseModel, theta; scoring_function)::Real
information(model::ItemResponseModel, theta; scoring_function)::AbstractVector{<:Real}
information(model::ItemResponseModel, theta, is; scoring_function)::Real
information(model::ItemResponseModel, theta, is; scoring_function)::AbstractVector{<:Real}

Calculate the information of an ItemResponseModel.

Arguments

• theta: The person parameter value(s)
• is: One or multiple item identifiers. If is is omitted, the information of the whole test (test information) is returned.

Keyword arguments

• scoring_function: A function mapping all possible response values y to arbitrary values. Must default to identity.

Return values

If estimatione_type(model) == PointEstimate then information must return a single scalar value.

If estimation_type(model) == SamplingEstimate then information must return a vector of values with the length equal to the number of samples drawn.

irf(model::ItemResponseModel, theta, i, y)::Real
irf(model::ItemResponseModel, theta, i, y)::AbstractVector{<:Real}

Evaluate the item response function of an ItemResponseModel.

Argument

• model: An ItemResponseModel
• theta: The person parameter value(s)
• i: A unique item identifier
• y: Response value(s)

Return values

If estimation_type(model) == PointEstimate then the item response function must return a scalar value.

If estimation_type(model) == SamplingEstimate then the item response function must return a vector of values with the length equal to the number of samples.

test_interface(T::Type{<:ItemResponseModel}, data, args...; kwargs...)

Test the implementation of an item response model interface.

Arguments

• T: The implemented model type
• data: observed data
• args...: Additional arguments passed to fit

Keyword arguments

• kwargs...: Additional keyword arguments passed to fit