API
Types
AbstractItemResponseModels.ItemResponseModel
— TypeItemResponseModel
An abstract type representing an item response theory model.
Each implementation T <: ItemResponseModel
must define the following traits:
response_type
: A validResponseType
person_dimensionality
: A validDimensionality
item_dimensionality
: A validDimensionality
estimation_type
: A validEstimationType
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 typeT
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.
Traits
Dimensionality
AbstractItemResponseModels.Dimensionality
— TypeDimensionality
The Dimensionality
of an ItemResponseModel
defines whether or not the person and/or item parameters of the model are unidimensional or multidimensional.
AbstractItemResponseModels.Univariate
— TypeUnivariate <: Dimensionality
Defines that an ItemResponseModel
has scalar valued parameters.
AbstractItemResponseModels.Multivariate
— TypeMultivariate <: Dimensionality
Defines that an ItemResponseModel
has vector valued parameters.
AbstractItemResponseModels.item_dimensionality
— Functionitem_dimensionality(::T) -> Dimensionality
Return the Dimensionality
of the item parameters of an ItemResponseModel
.
AbstractItemResponseModels.person_dimensionality
— Functionitem_dimensionality(::T) -> Dimensionality
Return the Dimensionality
of the person parameters of an ItemResponseModel
.
Estimation type
AbstractItemResponseModels.EstimationType
— TypeEstimationType
The EstimationType
of an ItemResponseModel
describes the type of parameter estimation for the model.
AbstractItemResponseModels.PointEstimate
— TypePointEstimate <: 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.
AbstractItemResponseModels.SamplingEstimate
— TypeSamplingEstimate <: 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.
AbstractItemResponseModels.estimation_type
— Functionestimation_type(::T) -> EstimationType
Return the EstimationType
of an [ItemResponseModel
].
Response type
AbstractItemResponseModels.ResponseType
— TypeResponseType
The ResponseType
defines the scale level of item responses for a given ItemResponseModel
.
AbstractItemResponseModels.Dichotomous
— TypeDichotomous <: ResponseType
Defines that an ItemResponseModel
has a binary response variable.
AbstractItemResponseModels.Nominal
— TypeNominal <: ResponseType
Defines that an ItemResponseModel
has an unordered categorical response variable.
AbstractItemResponseModels.Ordinal
— TypeOrdinal <: ResponseType
Defines that an ItemResponseModel
has an ordered categorical response variable.
AbstractItemResponseModels.Continuous
— TypeContinous <: ResponseType
Defines that an ItemResponseModel
has a continous response variable.
AbstractItemResponseModels.response_type
— Functionresponse_type(::T) -> ResponseType
Return the ResponseType
of an ItemResponseModel
.
AbstractItemResponseModels.checkresponsetype
— Functioncheckresponsetype(::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.
Methods
AbstractItemResponseModels.expected_score
— Functionexpected_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
: AnItemResponseModel
theta
: The person parameter value(s)is
: One or multiple item identifiers. Ifis
is omitted, the expected score for the whole test is returned.
Keyword arguments
scoring_function
: A function mapping all possible response valuesy
to arbitrary values. Must default toidentity
.
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.
StatsAPI.fit
— Functionfit(::Type{T}, data::AbstractMatrix, args...; kwargs...)::T where {T<:ItemResponseModel}
Fit an item response model to response data.
Arguments
data
: Observed data. Ifdata
is a response matrix, the columns must describe items and rows describe persons.args...
: Additional arguments required to fit theItemResponseModel
Keyword arguments
kwargs...
: Additional keyword arguments required to fit theItemResponseModel
Return values
A fitted ItemResponseModel
.
AbstractItemResponseModels.getitemlocations
— Functiongetitemlocations(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
: AnItemResponseModel
i
: A unique item identifiery
: 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.
AbstractItemResponseModels.getpersonlocations
— Functiongetpersonlocations(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
: AnItemResponseModel
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.
AbstractItemResponseModels.iif
— Functioniif(model::ItemResponseModel, theta, i, y)::Real
iif(model::ItemResponseModel, theta, i, y)::AbstractVector{<:Real}
Argument
model
: AnItemResponseModel
theta
: The person parameter value(s)i
: A unique item identifiery
: 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.
AbstractItemResponseModels.information
— Functioninformation(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. Ifis
is omitted, the information of the whole test (test information) is returned.
Keyword arguments
scoring_function
: A function mapping all possible response valuesy
to arbitrary values. Must default toidentity
.
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.
AbstractItemResponseModels.irf
— Functionirf(model::ItemResponseModel, theta, i, y)::Real
irf(model::ItemResponseModel, theta, i, y)::AbstractVector{<:Real}
Evaluate the item response function of an ItemResponseModel
.
Argument
model
: AnItemResponseModel
theta
: The person parameter value(s)i
: A unique item identifiery
: 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.
Tests
Interface tests are provided in the AbstractItemResponseModels.Tests
module.
AbstractItemResponseModels.Tests.test_interface
— Functiontest_interface(T::Type{<:ItemResponseModel}, data, args...; kwargs...)
Test the implementation of an item response model interface.
Arguments
T
: The implemented model typedata
: observed dataargs...
: Additional arguments passed tofit
Keyword arguments
kwargs...
: Additional keyword arguments passed tofit