API

abstract type OneParameterLogisticModel <: DichotomousItemResponseModel

An abstract representation of a 1 Parameter Logistic Model with an item response function given by

$P(Y_{ij}=1|\theta_i,\boldsymbol{\beta}_j) = \mathrm{logistic}(\theta_i - b_j)$

The item parameter beta can be passed as a number or a destructurable object with the following fields:

• b: the item difficulty (location)

Alias: OnePL

abstract type OneParameterLogisticPlusGuessingModel <: DichotomousItemResponseModel

An abstract representation of the 1 Parameter Logistic + Guessing Model with an item response function given by

$P(Y_{ij}=1|\theta_i,\boldsymbol{\beta}_j) = c + (1 - c) \cdot \mathrm{logistic}(\theta_i - b_j)$

The item parameters beta must be a destructurable object with the following fields:

• b: the item difficulty (location)
• c: the lower asymptote

Alias: OnePLG

abstract type TwoParameterLogisticModel <: DichotomousItemResponseModel

An abstract representation of a 2 Parameter Logistic Model with an item response function given by

$P(Y_{ij}=1|\theta_i,\boldsymbol{\beta}_j) = \mathrm{logistic}(a_j(\theta_i - b_j))$

The item parameters beta must be a destructurable object with the following fields:

• a: the item discrimination
• b: the item difficulty (location)

Alias: TwoPL

abstract type ThreeParameterLogisticModel <: DichotomousItemResponseModel

An abstract representation of a 3 Parameter Logistic Model with an item response function given by

$P(Y_{ij}=1|\theta_i,\boldsymbol{\beta}_j) = c_j + (1 - c_j)\cdot\mathrm{logistic}(a_j(\theta_i - b_j))$

The item parameters beta must be a destructurable object with the following fields:

• a: the item discrimination
• b: the item difficulty (location)
• c: the lower asymptote

Alias: ThreePL

abstract type FourParameterLogisticModel <: DichotomousItemResponseModel

An abstract representation of a 4 Parameter Logistic Model with an item response function given by

$P(Y_{ij}=1|\theta_i,\boldsymbol{\beta}_j) = c_j + (d_j - c_j)\cdot\mathrm{logistic}(a_j(\theta_i - b_j))$

The item parameters beta must be a destructurable object with the following fields:

• a: the item discrimination
• b: the item difficulty (location)
• c: the lower asymptote
• d: the upper asymptote

Alias: FourPL

abstract type FiveParameterLogisticModel <: DichotomousItemResponseModel

An abstract representation of a 5 Parameter Logistic Model with an item response function given by

$P(Y_{ij}=1|\theta_i,\boldsymbol{\beta}_j) = c_j + (d_j - c_j)\cdot\mathrm{logistic}(a_j(\theta_i - b_j))^{e_j}$

The item parameters beta must be a destructurable object with the following fields:

• a: the item discrimination
• b: the item difficulty (location)
• c: the lower asymptote
• d: the upper asymptote
• e: the item stiffness

Alias: FivePL

abstract type PartialCreditModel <: PolytomousItemResponseModel

An abstract type representing a Partial Credit Model with an item category response function given by

$P(Y_{ij} = y,| \theta_i, \boldsymbol{\beta}_j) = \frac{\exp \sum_{s=1}^y (\theta_i - b_j + t_{js})} {1 + \sum_{k=1}^{K_j} \exp \sum_{s=1}^k (\theta_i - b_j + t_{js})}$

The item parameters beta must be a destructurable object with the following fields:

• b: the item difficulty (location)
• t: a vector of threshold parameters

Alias: PCM

abstract type GeneralizedPartialCreditModel <: PolytomousItemResponseModel

An abstract type representing a Generalized Partial Credit Model with an item category response function given by

$P(Y_{ij} = y,| \theta_i, \boldsymbol{\beta}_j) = \frac{\exp \sum_{s=1}^y (a_j (\theta_i - b_j + t_{js}))} {1 + \sum_{k=1}^{K_j} \exp \sum_{s=1}^k (a_j (\theta_i - b_j + t_{js}))}$

The item parameters beta must be a destructurable object with the following fields:

• a: the item discrimination
• b: the item difficulty (location)
• t: a vector of threshold parameters

Alias: GPCM

abstract type RatingScaleModel <: PolytomousItemResponseModel

An abstract type representing a Rating Scale Model with an item category response function given by

$P(Y_{ij} = y,| \theta_i, \boldsymbol{\beta}_j) = \frac{\exp \sum_{s=1}^y (\theta_i - b_j + t_{s})} {1 + \sum_{k=1}^{K_j} \exp \sum_{s=1}^k (\theta_i - b_j + t_{s})}$

The item parameters beta must be a destructurable object with the following fields:

• b: the item difficulty (location)
• t: a vector of threshold parameters

Alias: RSM

abstract type GeneralizedRatingScaleModel <: PolytomousItemResponseModel

An abstract type representing a Generalized Rating ScaleModel with an item category response function given by

$P(Y_{ij} = y,| \theta_i, \boldsymbol{\beta}_j) = \frac{\exp \sum_{s=1}^y (a_j (\theta_i - b_j + t_{s}))} {1 + \sum_{k=1}^{K_j} \exp \sum_{s=1}^k (a_j (\theta_i - b_j + t_{s}))}$

The item parameters beta must be a destructurable object with the following fields:

• a: the item discrimination
• b: the item difficulty (location)
• t: a vector of threshold parameters

Alias: GRSM

irf(M, theta, beta, y)

Evaluate the item response function of an item response model M for response y at the ability value theta given item parameters beta.

If y is omitted, then the item response function is evaluated for all possible responses.

Examples

1 Parameter Logistic Model

julia> irf(OnePL, 0.0, 0.0, 1)
0.5

julia> irf(OnePL, 0.0, (; b = 0.5), 1)
0.37754066879814546

julia> irf(OnePL, 0.0, 0.5)
2-element Vector{Float64}:
 0.6224593312018545
 0.37754066879814546

2 Parameter Logistic Model

julia> beta = (a = 1.5, b = 0.5);

julia> irf(TwoPL, 0.0, beta, 1)
0.32082130082460697

3 Parameter Logistic Model

julia> beta = (a = 1.5, b = 0.5, c = 0.2);

julia> irf(ThreePL, 0.0, beta, 1)
0.4566570406596856

4 Parameter Logistic Model

julia> beta = (a = 1.5, b = 0.5, c = 0.2, d = 0.8);

julia> irf(FourPL, 0.0, beta, 1)
0.3924927804947642

Partial Credit Model

julia> beta = (b = -0.3, t = [-0.5, 1.3, -0.2]);

julia> irf(PCM, 0.0, beta)
4-element Vector{Float64}:
 0.09656592461423529
 0.07906149218108449
 0.3915941342939724
 0.4327784489107078

julia> irf(PCM, 0.0, beta, 3)
0.3915941342939724

Generalized Partial Credit Model

julia> beta = (a = 1.3, b = 0.25, t = [0.0, 1.0]);

julia> irf(GPCM, 0.0, beta)
3-element Vector{Float64}:
 0.27487115408319557
 0.1986019275522736
 0.5265269183645309

julia> irf(GPCM, 0.0, beta, 1)
0.27487115408319557

Rating Scale Model

julia> beta = (b = 0.0, t = zeros(2));

julia> irf(RSM, 0.0, beta)
3-element Vector{Float64}:
 0.3333333333333333
 0.3333333333333333
 0.3333333333333333

julia> irf(RSM, 0.0, beta, 3)
0.3333333333333333

irf!(M, probs, theta, beta; scoring_function)

An in-place version of irf. Provides efficient computation by mutating probs in-place, thus avoiding allocation of an output vector.

Examples

julia> beta = (a = 1.2, b = 0.3, t = zeros(3));

julia> probs = zeros(length(beta.t) + 1);

julia> irf!(GPCM, probs, 0.0, beta)
4-element Vector{Float64}:
 0.3961927292844976
 0.2764142877832629
 0.19284770477416754
 0.13454527815807202

julia> probs
4-element Vector{Float64}:
 0.3961927292844976
 0.2764142877832629
 0.19284770477416754
 0.13454527815807202

iif(M, theta, beta, y)

Evaluate the item information function of an item response model M for response y at the ability value theta given item parameters beta.

If y is omitted, the item category information functions for all categories are returned.

Examples

1 Parameter Logistic Model

julia> iif(OnePL, 0.0, 0.0, 1)
0.125

julia> iif(OnePL, 0.0, (; b = 0.0))
2-element Vector{Float64}:
 0.125
 0.125

2 Parameter Logistic Model

julia> iif(TwoPL, 0.0, (a = 1.3, b = 0.2))
2-element Vector{Float64}:
 0.2345721809921237
 0.1808672521393781

3 Parameter Logistic Model

julia> iif(ThreePL, 0.0, (a = 1.5, b = 0.5, c = 0.15))
2-element Vector{Float64}:
 0.2830301834782102
 0.033256997107963204

4 Parameter Logistic Model

julia> iif(FourPL, 0.0, (a = 2.1, b = -0.2, c = 0.15, d = 0.9))
2-element Vector{Float64}:
 0.1936328888005068
 0.3995140205278245

expected_score(M, theta, betas; scoring_function)

Calculate the expected score of an item response model M at the ability value theta given a vector of item parameters betas. The values of betas are considered item parameters for different items.

Expected scores are calculated from the models irf function. For details on how to pass item parameters to irf, see the respective function documentation.

Response scoring

The expected score is defined as the expected value of an observed response pattern x. Thus, the expected value for an arbitrary function f(x) can also be defined. We call the function f the scoring_function that maps responses to arbitrary values.

Examples

1 Parameter Logistic Model

julia> betas = fill(0.0, 10);

julia> expected_score(OnePL, 0.0, betas)
5.0

julia> expected_score(OnePL, 0.0, betas; scoring_function = x -> 2x)
10.0

2 Parameter Logistic Model

julia> betas = fill((a = 1.5, b = 0.0), 5);

julia> expected_score(TwoPL, 0.0, betas)
2.5

julia> expected_score(TwoPL, 0.0, betas; scoring_function = x -> x + 1)
7.5

3 Parameter Logistic Model

julia> betas = fill((a = 0.4, b = 0.5, c = 0.1), 6);

julia> expected_score(ThreePL, 0.0, betas)
3.030896414512619

4 Parameter Logistic Model

julia> betas = fill((a = 1.4, b = 1.0, c = 0.15, d = 0.9), 7);

julia> expected_score(FourPL, 0.0, betas)
2.0885345850674453

information(M, theta, betas; scoring_function)

Calculate the test information of an item response mode M at the ability value theta given a vector of item parameters betas. The values of betas are considered item parameters for different items.

The test information is calculated from the models iif function. For details on how to pass item parameters to iif, see the respective function documentation.

Examples

1 Parameter Logistic Model

julia> information(OnePL, 0.0, zeros(6))
1.5

julia> betas = fill((; b = 0.0), 6);

julia> information(OnePL, 0.0, betas)
1.5

2 Parameter Logistic Model

julia> betas = fill((; a = 1.2, b = 0.4), 4);

julia> information(TwoPL, 0.0, betas)
1.3601401228069936

3 Parameter Logistic Model

julia> betas = fill((; a = 1.5, b = 0.5, c = 0.2), 4);

julia> information(ThreePL, 0.0, betas)
1.1021806599852655

4 Parameter Logistic Model

julia> betas = fill((; a = 0.5, b = 1.4, c = 0.13, d = 0.94), 6);

julia> information(FourPL, 0.0, betas)
0.20178122985757524

struct ItemParameters{M<:ItemResponseModel, N, T<:Real}

A struct representing item parameters for an item response model.

Fields

• a: the item discrimination

• b: the item difficulty (location)

• c: the lower asymptote

• d: the upper asymptote

• e: the item stiffness

• t: a tuple of threshold parameters

Examples

julia> pars = ItemParameters(TwoPL, a = 1.5, b = 0.0)
ItemParameters{TwoParameterLogisticModel, 0, Float64}(1.5, 0.0, 0.0, 1.0, 1.0, ())

julia> ItemParameters(OnePL, pars)
ItemParameters{OneParameterLogisticModel, 0, Float64}(1.0, 0.0, 0.0, 1.0, 1.0, ())

derivative_theta(M, theta, beta; scoring_function)

Calculate the derivative of the item (category) response function with respect to theta of model M given item parameters beta for response y. Returns the primal value and the first derivative.

If y is omitted, returns probabilities and derivatives for all possible responses (see also derivative_theta!).

derivative_theta!(
    M,
    probs,
    derivs,
    theta,
    beta;
    scoring_function
)

Calculate the derivative of the item (category) response function with respect to theta of model M given item parameters beta for all possible responses. This function overwrites probs and derivs with the item category response probabilities and derivatives respectively.

likelihood(M, theta, betas, responses)

Evaluate the likelihood of an item response model M at theta, given item parameters betas and response pattern responses.

Items are assumed to be independent. Then, the likelihood function is defined as,

$L(\boldsymbol{u} | \theta, \boldsymbol{\beta}) = \prod_{j=1}^J P(Y_j = y | \theta, \boldsymbol{\beta}_j)$

See also loglikelihood.

loglikelihood(M, theta, betas, responses)

Evaluate the log-likelihood of an item response model M at theta, given item parameters betas and response pattern responses,

See also likelihood.

partial_credit(n; max_score)

Return a scoring function that maps n response categories to a score (0, max_score).

Examples

julia> my_partial_credit = partial_credit(4);

julia> my_partial_credit.(1:4)
4-element Vector{Float64}:
 0.0
 0.3333333333333333
 0.6666666666666666
 1.0

julia> my_partial_credit = partial_credit(5, max_score = 3);

julia> my_partial_credit.(1:5)
5-element Vector{Float64}:
 0.0
 0.75
 1.5
 2.25
 3.0

second_derivative_theta(M, theta, beta; scoring_function)

Calculate the second derivative of the item (category) response function with respect to theta of model M given item parameters beta for response y. Returns the primal value, the first derivative and the second derivative.

If y is omitted, returns primals and derivatives for all possible responses (see also second_derivative_theta!).

second_derivative_theta!(
    M,
    probs,
    derivs,
    derivs2,
    theta,
    beta;
    scoring_function
)

Calculate the second derivative of the item (category) response function with respect to theta of model M given item parameters beta for response y. Returns the primal value, the first derivative, and the second derivative

If y is omitted, returns values and derivatives for all possible responses.

This function overwrites probs, derivs and derivs2 with the respective values.