Add ConvergenceException from StatsBase

I've added the folks who contributed the type and improvements to it and
its documentation as coauthors of the commit. (Apologies if I missed
anyone.)

Co-authored-by: Roger Herikstad <[email protected]>
Co-authored-by: Galen Lynch <[email protected]>
Co-authored-by: Alexander Morley <[email protected]>

Author: 4 people

src/statisticalmodel.jl

@@ -314,3 +314,41 @@ function adjr2(model::StatisticalModel, variant::Symbol)
 end
 
 const adjr² = adjr2
+
+"""
+    ConvergenceException(iterations::Int, lastchange::Real=NaN, tolerance::Real=NaN,
+                         message::String="")
+
+The fitting procedure failed to converge in `iterations` number of iterations. Typically
+this is because the `lastchange` between the objective in the final and penultimate
+iterations was greater than the specified `tolerance`. Further information can be provided
+by `message`.
+"""
+struct ConvergenceException{T<:Real} <: Exception
+    iterations::Int
+    lastchange::T
+    tolerance::T
+    message::String
+
+    function ConvergenceException(iterations, lastchange=NaN, tolerance=NaN, message="")
+        if tolerance > lastchange
+            throw(ArgumentError("can't construct `ConvergenceException` with change " *
+                                "less than tolerance; got $lastchange and $tolerance"))
+        end
+        T = promote_type(typeof(lastchange), typeof(tolerance))
+        return new{T}(iterations, lastchange, tolerance, message)
+    end
+end
+
+function Base.showerror(io::IO, ce::ConvergenceException)
+    print(io, "failure to converge after ", ce.iterations, " iterations")
+    if !isnan(ce.lastchange)
+        print(io, "; last change between iterations (", ce.lastchange, ") was greater ",
+              "than tolerance (", ce.tolerance, ")")
+    end
+    print(io, '.')
+    if !isempty(ce.message)
+        print(io, ' ', ce.message)
+    end
+    return nothing
+end

test/statisticalmodel.jl

@@ -1,7 +1,8 @@
 module TestStatisticalModel
 
 using Test, StatsAPI
-using StatsAPI: StatisticalModel, stderror, aic, aicc, bic, r2, r², adjr2, adjr²
+using StatsAPI: ConvergenceException, StatisticalModel, stderror, aic, aicc, bic,
+                r2, r², adjr2, adjr²
 
 struct MyStatisticalModel <: StatisticalModel
 end
@@ -36,4 +37,16 @@ StatsAPI.nobs(::MyStatisticalModel) = 100
     @test adjr2 === adjr²
 end
 
-end # module TestStatisticalModel
+@testset "ConvergenceException" begin
+    fail = "failure to converge after 10 iterations"
+    chgtol = "last change between iterations (0.2) was greater than tolerance (0.1)"
+    msg = "Try changing maxiter."
+    @test sprint(showerror, ConvergenceException(10)) == "$fail."
+    @test sprint(showerror, ConvergenceException(10, 0.2, 0.1)) == "$fail; $chgtol."
+    @test sprint(showerror, ConvergenceException(10, 0.2, 0.1, msg)) == "$fail; $chgtol. $msg"
+    err = @test_throws ArgumentError ConvergenceException(10, 0.1, 0.2)
+    @test err.value.msg == string("can't construct `ConvergenceException` with change ",
+                                  "less than tolerance; got 0.1 and 0.2")
+end
+
+end # module TestStatisticalModel