add analytic derivatives (#28)

* expose derivatives for theta

* use derivative_theta

* add analytic derivatives

* enable precompile

* fix autodiff second derivative

* cleanup

* fix first derivative

* rm Enzyme dependency

* implement analytic derivative for GPCM

* implement second derivative for GPCM

* try fix tests on julia 1.8

* allow namedtuples in irf

* try fix tests on julia-1.8

* test importing for precompile

* fix doctests

* drop support for julia 1.8

* add unit tests

* add more tests

* add tests for second derivative with beta::Real

* add derivatives to docs

.github/workflows/CI.yml

@@ -20,7 +20,6 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.8'
           - '1.9'
           - '1.10'
         os:

Project.toml

@@ -1,7 +1,7 @@
 name = "ItemResponseFunctions"
 uuid = "18e85bec-f2a0-4122-b3a6-37651333b522"
 authors = ["Philipp Gewessler <[email protected]>"]
-version = "0.1.0"
+version = "0.1.1"
 
 [deps]
 AbstractItemResponseModels = "0ab3451c-659c-47cd-a7a9-a2d579e209dd"
@@ -15,14 +15,14 @@ SimpleUnPack = "ce78b400-467f-4804-87d8-8f486da07d0a"
 
 [compat]
 AbstractItemResponseModels = "0.2"
-DifferentiationInterface = "0.4"
+DifferentiationInterface = "0.5"
 DocStringExtensions = "0.9"
 ForwardDiff = "0.10"
 LogExpFunctions = "0.3"
 PrecompileTools = "1"
 Reexport = "1"
 SimpleUnPack = "1"
-julia = "1.8"
+julia = "1.9"
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

README.md

@@ -8,10 +8,10 @@
 [ItemResponseFunctions.jl](https://github.com/juliapsychometrics/ItemResponseFunctions.jl) implements basic functions for Item Response Theory models. It is built based on the interface designed in [AbstractItemResponseModels.jl](https://github.com/JuliaPsychometrics/AbstractItemResponseModels.jl).
 
 ## Installation
-You can install ItemResponseFunctions.jl from Github
+You can install ItemResponseFunctions.jl from the General package registry:
 
 ```julia
-] add https://github.com/JuliaPsychometrics/ItemResponseFunctions.jl.git
+] add ItemResponseFunctions
 ```
 
 ## Usage

docs/src/api.md

@@ -32,8 +32,16 @@ iif
 expected_score
 information
 ```
-
-### Scoring functions
+### Utilities
+#### Scoring functions
 ```@docs
 partial_credit
-```
+```
+
+#### Derivatives
+```@docs
+derivative_theta
+derivative_theta!
+second_derivative_theta
+second_derivative_theta!
+```

docs/src/index.md

@@ -8,10 +8,10 @@
 [ItemResponseFunctions.jl](https://github.com/juliapsychometrics/ItemResponseFunctions.jl) implements basic functions for Item Response Theory models. It is built based on the interface designed in [AbstractItemResponseModels.jl](https://github.com/JuliaPsychometrics/AbstractItemResponseModels.jl).
 
 ## Installation
-You can install ItemResponseFunctions.jl from Github
+You can install ItemResponseFunctions.jl from the General package registry:
 
 ```julia
-] add https://github.com/JuliaPsychometrics/ItemResponseFunctions.jl.git
+] add ItemResponseFunctions
 ```
 
 ## Usage

src/ItemResponseFunctions.jl

@@ -1,12 +1,13 @@
 module ItemResponseFunctions
 
 using AbstractItemResponseModels: Dichotomous, Nominal, checkresponsetype
+using DifferentiationInterface:
+    AutoForwardDiff, derivative!, value_and_derivative, second_derivative
 using DocStringExtensions: SIGNATURES, TYPEDEF, METHODLIST
 using LogExpFunctions: logistic, cumsum!, softmax!
 using Reexport: @reexport
 using SimpleUnPack: @unpack
 
-using DifferentiationInterface
 import ForwardDiff
 
 # AbstractItemResponseModels interface extensions
@@ -40,7 +41,9 @@ export DichotomousItemResponseModel,
     irf!,
     partial_credit,
     derivative_theta,
-    second_derivative_theta
+    derivative_theta!,
+    second_derivative_theta,
+    second_derivative_theta!
 
 include("model_types.jl")
 include("utils.jl")
@@ -51,6 +54,6 @@ include("information.jl")
 include("scoring_functions.jl")
 include("derivatives.jl")
 
-# include("precompile.jl")
+include("precompile.jl")
 
 end

src/derivatives.jl

@@ -1,24 +1,208 @@
 """
     $(SIGNATURES)
 
-Calculate the derivative of the item response function with respect to theta.
+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.
+"""
+function derivative_theta!(M::Type{<:ItemResponseModel}, probs, derivs, theta, beta)
+    pars = merge_pars(M, beta)
+    return _derivative_theta!(M, probs, derivs, theta, pars)
+end
+
+function _derivative_theta!(M::Type{<:ItemResponseModel}, probs, derivs, theta, beta)
+    derivative!((y, x) -> _irf!(M, y, x, beta), probs, derivs, AutoForwardDiff(), theta)
+    return probs, derivs
+end
+
+# this is implemented for all except 5PL
+const DichModelsWithDeriv = Union{OnePL,TwoPL,ThreePL,FourPL}
+
+function _derivative_theta!(M::Type{<:DichModelsWithDeriv}, probs, derivs, theta, beta)
+    probs[2], derivs[2] = _derivative_theta(M, theta, beta, 1)
+    probs[1] = 1 - probs[2]
+    derivs[1] = -derivs[2]
+    return probs, derivs
+end
+
+const PolyModelsWithDeriv = Union{GPCM,PCM,GRSM,RSM}
+
+function _derivative_theta!(M::Type{<:PolyModelsWithDeriv}, probs, derivs, theta, beta)
+    @unpack a, b, t = beta
+    _irf!(M, probs, theta, beta)
+
+    categories = eachindex(probs)
+    probsum = sum(c * probs[c] for c in categories)
+
+    for c in categories
+        derivs[c] = a * probs[c] * (c - probsum)
+    end
+
+    return probs, derivs
+end
+
+"""
+    $(SIGNATURES)
+
+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!`](@ref)).
 """
-function derivative_theta(M::Type{<:ItemResponseModel}, theta, beta, y)
-    adtype = AutoForwardDiff()
-    prob, deriv = value_and_derivative(x -> irf(M, x, beta, y), adtype, theta)
+function derivative_theta(M::Type{<:ItemResponseModel}, theta, beta)
+    ncat = M <: DichotomousItemResponseModel ? 2 : length(beta.t) + 1
+    probs = zeros(ncat)
+    derivs = similar(probs)
+    return derivative_theta!(M, probs, derivs, theta, beta)
+end
+
+function derivative_theta(M::Type{OnePL}, theta, beta::Real)
+    pars = merge_pars(M, beta)
+    return derivative_theta(M, theta, pars)
+end
+
+function derivative_theta(M::Type{<:PolytomousItemResponseModel}, theta, beta, y)
+    probs, derivs = derivative_theta(M, theta, beta)
+    return probs[y], derivs[y]
+end
+
+function derivative_theta(M::Type{<:DichotomousItemResponseModel}, theta, beta, y)
+    prob, deriv = value_and_derivative(x -> irf(M, x, beta, y), AutoForwardDiff(), theta)
+    return prob, deriv
+end
+
+function derivative_theta(M::Type{<:DichModelsWithDeriv}, theta, beta, y)
+    pars = merge_pars(M, beta)
+    return _derivative_theta(M, theta, pars, y)
+end
+
+# analytic first derivative implementations
+function _derivative_theta(M::Type{<:DichModelsWithDeriv}, theta, beta, y)
+    @unpack a, c, d = beta
+    prob = irf(M, theta, beta, y)
+    pu = irf(TwoPL, theta, beta, 1)  # unconstrained response probability
+    qu = 1 - pu
+    deriv = (d - c) * a * (pu * qu) * ifelse(y == 1, 1, -1)
     return prob, deriv
 end
 
 """
     $(SIGNATURES)
 
-Calculate the second derivative of the item response function with respect to theta.
-Returns the primal value, the first and the second derivative.
+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.
 """
-function second_derivative_theta(M::Type{<:ItemResponseModel}, theta, beta, y)
+function second_derivative_theta!(M, probs, derivs, derivs2, theta, beta)
+    pars = merge_pars(M, beta)
+    return _second_derivative_theta!(M, probs, derivs, derivs2, theta, pars)
+end
+
+function _second_derivative_theta!(
+    M::Type{<:DichotomousItemResponseModel},
+    probs,
+    derivs,
+    derivs2,
+    theta,
+    beta,
+)
+    _derivative_theta!(M, probs, derivs, theta, beta)
+    derivs2[1] = second_derivative(x -> irf(M, x, beta, 0), AutoForwardDiff(), theta)
+    derivs2[2] = second_derivative(x -> irf(M, x, beta, 1), AutoForwardDiff(), theta)
+    return probs, derivs, derivs2
+end
+
+function _second_derivative_theta!(
+    M::Type{<:DichModelsWithDeriv},
+    probs,
+    derivs,
+    derivs2,
+    theta,
+    beta,
+)
+    probs[2], derivs[2], derivs2[2] = _second_derivative_theta(FourPL, theta, beta, 1)
+    probs[1] = 1 - probs[2]
+    derivs[1] = -derivs[2]
+    derivs2[1] = -derivs2[2]
+    return probs, derivs, derivs2
+end
+
+function _second_derivative_theta!(
+    M::Type{<:PolyModelsWithDeriv},
+    probs,
+    derivs,
+    derivs2,
+    theta,
+    beta,
+)
+    @unpack a, b, t = beta
+    _derivative_theta!(M, probs, derivs, theta, beta)
+
+    categories = eachindex(probs)
+    probsum = sum(c * probs[c] for c in categories)
+    probsum2 = sum(c^2 * probs[c] for c in categories)
+
+    for c in categories
+        derivs[c] = a * probs[c] * (c - probsum)
+        derivs2[c] = a^2 * probs[c] * (c^2 - 2 * c * probsum + 2 * probsum^2 - probsum2)
+    end
+
+    return probs, derivs, derivs2
+end
+
+"""
+    $(SIGNATURES)
+
+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!`](@ref)).
+"""
+function second_derivative_theta(M::Type{<:ItemResponseModel}, theta, beta)
+    ncat = M <: DichotomousItemResponseModel ? 2 : length(beta.t) + 1
+    probs = zeros(ncat)
+    derivs = similar(probs)
+    derivs2 = similar(probs)
+    return second_derivative_theta!(M, probs, derivs, derivs2, theta, beta)
+end
+
+function second_derivative_theta(M::Type{OnePL}, theta, beta::Real)
+    pars = merge_pars(M, beta)
+    return second_derivative_theta(M, theta, pars)
+end
+
+function second_derivative_theta(M::Type{<:PolytomousItemResponseModel}, theta, beta, y)
+    probs, derivs, derivs2 = second_derivative_theta(M, theta, beta)
+    return probs[y], derivs[y], derivs2[y]
+end
+
+function second_derivative_theta(M::Type{<:DichotomousItemResponseModel}, theta, beta, y)
     adtype = AutoForwardDiff()
+    f = x -> irf(M, x, beta, y)
+    prob, deriv = value_and_derivative(f, adtype, theta)
+    deriv2 = second_derivative(f, adtype, theta)
+    return prob, deriv, deriv2
+end
+
+function second_derivative_theta(M::Type{<:DichModelsWithDeriv}, theta, beta, y)
+    pars = merge_pars(M, beta)
+    return _second_derivative_theta(M, theta, pars, y)
+end
+
+# analytic implementations of second derivatives
+function _second_derivative_theta(M::Type{<:DichModelsWithDeriv}, theta, beta, y)
+    @unpack a, c, d = beta
     prob, deriv = derivative_theta(M, theta, beta, y)
-    deriv2 = second_derivative(x -> irf(M, x, beta, y), adtype, theta)
+    pu = irf(TwoPL, theta, beta, 1)  # unconstrained probability
+    qu = 1 - pu
+    deriv2 = a^2 * (d - c) * (2 * (qu^2 * pu) - pu * qu) * ifelse(y == 1, 1, -1)
     return prob, deriv, deriv2
 end

src/iif.jl

@@ -37,8 +37,8 @@ julia> iif(ThreePL, 0.0, (a = 1.5, b = 0.5, c = 0.15))
 ```jldoctest
 julia> iif(FourPL, 0.0, (a = 2.1, b = -0.2, c = 0.15, d = 0.9))
 2-element Vector{Float64}:
- 0.19363288880050672
- 0.39951402052782453
+ 0.1936328888005068
+ 0.3995140205278245
 ```
 
 """
@@ -64,10 +64,6 @@ function _iif(M::Type{<:DichotomousItemResponseModel}, theta, beta, y)
     return deriv^2 / prob - deriv2
 end
 
-# special case for 1PL with numeric beta
-iif(M::Type{OnePL}, theta, beta::Real, y) = iif(M, theta, (; b = beta), y)
-iif(M::Type{OnePL}, theta, beta::Real) = iif(M, theta, (; b = beta))
-
 # polytomous models
 function iif(M::Type{GPCM}, theta, beta; scoring_function::F = identity) where {F}
     checkpars(M, beta)

src/information.jl

@@ -25,15 +25,15 @@ julia> information(OnePL, 0.0, betas)
 julia> betas = fill((; a = 1.2, b = 0.4), 4);
 
 julia> information(TwoPL, 0.0, betas)
-1.3601401228069934
+1.3601401228069936
 ```
 
 ### 3 Parameter Logistic Model
 ```jldoctest
 julia> betas = fill((; a = 1.5, b = 0.5, c = 0.2), 4);
 
 julia> information(ThreePL, 0.0, betas)
-1.1021806599852657
+1.1021806599852655
 ```
 
 ### 4 Parameter Logistic Model