Merge pull request #91 from alan-turing-institute/iteration

Add support for iterative models

Author: ablaom

Project.toml

@@ -1,7 +1,7 @@
 name = "MLJModelInterface"
 uuid = "e80e1ace-859a-464e-9ed9-23947d8ae3ea"
 authors = ["Thibaut Lienart and Anthony Blaom"]
-version = "0.4.0"
+version = "0.4.1"
 
 [deps]
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
@@ -10,7 +10,7 @@ StatisticalTraits = "64bff920-2084-43da-a3e6-9bb72801c0c9"
 
 [compat]
 ScientificTypes = "^1"
-StatisticalTraits = "^0.1"
+StatisticalTraits = "^0.1.1"
 julia = "^1"
 
 [extras]

src/MLJModelInterface.jl

@@ -21,7 +21,9 @@ const MODEL_TRAITS = [
     :implemented_methods,
     :hyperparameters,
     :hyperparameter_types,
-    :hyperparameter_ranges]
+    :hyperparameter_ranges,
+    :iteration_parameter,
+    :supports_training_losses]
 
 # ------------------------------------------------------------------------
 # Dependencies (ScientificTypes and StatisticalTraits have none)
@@ -49,7 +51,7 @@ export @mlj_model, metadata_pkg, metadata_model
 # model api
 export fit, update, update_data, transform, inverse_transform,
     fitted_params, predict, predict_mode, predict_mean, predict_median,
-    predict_joint, evaluate, clean!, reformat
+    predict_joint, evaluate, clean!, reformat, training_losses
 
 # model traits
 for trait in MODEL_TRAITS

src/model_api.jl

@@ -1,5 +1,5 @@
 """
-    fit(model, verbosity, data...) -> fitresult, cache, report
+    MLJModelInterface.fit(model, verbosity, data...) -> fitresult, cache, report
 
 All models must implement a `fit` method. Here `data` is the
 output of `reformat` on user-provided data, or some some resampling
@@ -16,7 +16,7 @@ fit(::Static, ::Integer, data...) = (nothing, nothing, nothing)
 fit(m::Supervised, verbosity, X, y, w) = fit(m, verbosity, X, y)
 
 """
-    update(model, verbosity, fitresult, cache, data...)
+    MLJModelInterface.update(model, verbosity, fitresult, cache, data...)
 
 Models may optionally implement an `update` method. The fallback calls
 `fit`.
@@ -25,6 +25,20 @@ Models may optionally implement an `update` method. The fallback calls
 update(m::Model, verbosity, fitresult, cache, data...) =
     fit(m, verbosity, data...)
 
+"""
+    MLJModelInterface.training_losses(model::M, report)
+
+If `M` is an iterative model type which calculates training losses,
+implement this method to return an `AbstractVector` of the losses
+in historical order. If the model calculates scores instead, then the
+sign of the scores should be reversed.
+
+The following trait overload is alse required:
+`supports_training_losses(::Type{<:M}) = true`
+
+"""
+training_losses(model, report) = nothing
+
 # to support online learning in the future:
 # https://github.com/alan-turing-institute/MLJ.jl/issues/60 :
 function update_data end
@@ -53,7 +67,7 @@ manual](https://alan-turing-institute.github.io/MLJ.jl/dev/adding_models_for_gen
 reformat(model::Model, args...) = args
 
 """
-    selectrows(::Model, I, data...) -> sampled_data
+    MLJModelInterface.selectrows(::Model, I, data...) -> sampled_data
 
 A model overloads `selectrows` whenever it buys into the optional
 `reformat` front-end for data preprocessing. See [`reformat`](@ref)

test/model_api.jl

@@ -24,12 +24,18 @@ end
     @test fit(m1, 1, randn(2), randn(2), 5) == (7, nothing, nothing)
     # default fitted params
     @test M.fitted_params(m1, 7) == (fitresult=7,)
+    # default iteration_parameter
+    @test M.training_losses(m0, nothing) === nothing
     # static
     s1 = APIx1()
     @test fit(s1, 1, 0) == (nothing, nothing, nothing)
 
     #update fallback = fit
     @test update(m0, 1, 5, nothing, randn(2), 5) == (5, nothing, nothing)
+
+    # training losses:
+    f, c, r = MLJModelInterface.fit(m0, 1, rand(2), rand(2))
+    @test M.training_losses(m0, r) === nothing
 end
 
 struct DummyUnivariateFinite end

test/model_traits.jl

@@ -39,6 +39,7 @@ bar(::P1) = nothing
     @test is_wrapper(ms)       == false
     @test supports_online(ms)  == false
     @test supports_weights(ms) == false
+    @test iteration_parameter(ms) === nothing
 
     @test hyperparameter_ranges(md) == (nothing,)