adapt to LearnAPI v2.0 API changes

Author: ablaom

src/learners/ensembling.jl

@@ -490,8 +490,9 @@ function LearnAPI.update(
 
 end
 
-# needed, because model is supervised:
-LearnAPI.target(learner::StumpRegressor, observations) = last(observations)
+# training data deconstructors:
+LearnAPI.features(learner::StumpRegressor, data) = first(data)
+LearnAPI.target(learner::StumpRegressor, data) = last(data)
 
 LearnAPI.predict(model::StumpRegressorFitted, ::Point, x) =
     _predict(model.forest, x)

src/learners/gradient_descent.jl

@@ -1,5 +1,8 @@
 # THIS FILE IS NOT INCLUDED BUT EXISTS AS AN IMPLEMENTATION EXEMPLAR
 
+# TODO: This file should be updated after release of CategoricalDistributions 0.2 as
+# `classes` is deprecated there.
+
 # This file defines:
 # - `PerceptronClassifier(; epochs=50, optimiser=Optimisers.Adam(), rng=Random.default_rng())
 

src/learners/incremental_algorithms.jl

@@ -67,28 +67,28 @@ function LearnAPI.update_observations(model::NormalEstimatorFitted, ynew; verbos
     return NormalEstimatorFitted(Σy, ȳ, ss, n)
 end
 
-LearnAPI.features(::NormalEstimator, y) = nothing
 LearnAPI.target(::NormalEstimator, y) = y
 
-LearnAPI.predict(model::NormalEstimatorFitted, ::SingleDistribution) =
+LearnAPI.predict(model::NormalEstimatorFitted, ::Distribution) =
     Distributions.Normal(model.ȳ, sqrt(model.ss/model.n))
 LearnAPI.predict(model::NormalEstimatorFitted, ::Point) = model.ȳ
 function LearnAPI.predict(model::NormalEstimatorFitted, ::ConfidenceInterval)
-    d = predict(model, SingleDistribution())
+    d = predict(model, Distribution())
     return (quantile(d, 0.025), quantile(d, 0.975))
 end
 
 # for fit and predict in one line:
 LearnAPI.predict(::NormalEstimator, k::LearnAPI.KindOfProxy, y)  =
     predict(fit(NormalEstimator(), y), k)
-LearnAPI.predict(::NormalEstimator, y) = predict(NormalEstimator(), SingleDistribution(), y)
+LearnAPI.predict(::NormalEstimator, y) = predict(NormalEstimator(), Distribution(), y)
 
 LearnAPI.extras(model::NormalEstimatorFitted) = (μ=model.ȳ, σ=sqrt(model.ss/model.n))
 
 @trait(
     NormalEstimator,
     constructor = NormalEstimator,
-    kinds_of_proxy = (SingleDistribution(), Point(), ConfidenceInterval()),
+    kind_of = LearnAPI.Generative(),
+    kinds_of_proxy = (Distribution(), Point(), ConfidenceInterval()),
     tags = ("density estimation", "incremental algorithms"),
     is_pure_julia = true,
     human_name = "normal distribution estimator",
@@ -98,7 +98,6 @@ LearnAPI.extras(model::NormalEstimatorFitted) = (μ=model.ȳ, σ=sqrt(model.ss/
         :(LearnAPI.clone),
         :(LearnAPI.strip),
         :(LearnAPI.obs),
-        :(LearnAPI.features),
         :(LearnAPI.target),
         :(LearnAPI.predict),
         :(LearnAPI.update_observations),

src/learners/regression.jl

@@ -1,7 +1,7 @@
 # This file defines:
 
-# - `Ridge(; lambda=0.1)`
-# - `BabyRidge(; lambda=0.1)`
+# - `Ridge(; lambda=0.1)` (uses canned data front end)
+# - `BabyRidge(; lambda=0.1)` (no data front end)
 
 using LearnAPI
 using Tables
@@ -150,12 +150,17 @@ end
 
 LearnAPI.learner(model::BabyRidgeFitted) = model.learner
 
+# training data deconstructors:
+LearnAPI.features(learner::BabyRidge, (X, y)) = X
+LearnAPI.target(learner::BabyRidge, (X, y)) = y
+
 LearnAPI.predict(model::BabyRidgeFitted, ::Point, Xnew) =
     Tables.matrix(Xnew)*model.coefficients
 
 LearnAPI.strip(model::BabyRidgeFitted) =
     BabyRidgeFitted(model.learner, model.coefficients, nothing)
 
+
 @trait(
     BabyRidge,
     constructor = BabyRidge,

src/learners/static_algorithms.jl

@@ -55,12 +55,12 @@ function LearnAPI.transform(learner::Selector, X)
     transform(model, X)
 end
 
-# note the necessity of overloading `is_static` (`fit` consumes no data):
+# note the necessity of overloading `kind_of` (because `fit` consumes no data):
 @trait(
     Selector,
     constructor = Selector,
+    kind_of = LearnAPI.Static(),
     tags = ("feature engineering",),
-    is_static = true,
     functions = (
         :(LearnAPI.fit),
         :(LearnAPI.learner),
@@ -127,11 +127,11 @@ function LearnAPI.transform(learner::FancySelector, X)
     transform(model, X)
 end
 
-# note the necessity of overloading `is_static` (`fit` consumes no data):
+# note the necessity of overloading `kind_of` (because `fit` consumes no data):
 @trait(
     FancySelector,
     constructor = FancySelector,
-    is_static = true,
+    kind_of = LearnAPI.Static(),
     tags = ("feature engineering",),
     functions = (
         :(LearnAPI.fit),

src/logging.jl

@@ -8,7 +8,7 @@ const QUIET = "- specify `verbosity=1` if debugging"
 
 const CONSTRUCTOR = """
 
-    Testing that learner can be reconstructed from its constructors.
+    Testing that learner can be reconstructed from its constructor.
     [Reference](https://juliaai.github.io/LearnAPI.jl/dev/reference/#learners).
 
   """
@@ -34,23 +34,53 @@ const FUNCTIONS = """
   """
 const ERR_MISSINNG_OBLIGATORIES =
     "These obligatory functions are missing from the return value of "*
-    "`LearnAPI.functions(learner)`; "
+    "`LearnAPI.functions(learner)`: "
+
+
+
+const DECONSTRUCTORS = """
+
+    Checking that the data deconsructors (`features`, `target` and `weights`) have only
+    been implemented where appropriate, and looking for clues that some desirable
+    implementations have been forgotten.
+
+  """
+const WARN_GENERATIVE_NO_TARGET = """
+
+    Typically, when `LearnAPI.kind_of(learner)==LearnAPI.Generative()`, we expect
+    `LearnAPI.target` to be implemented. If you have implemented it, check you added
+    `:(LearnAPI.target)` to the tuple returned by `LearnAPI.functions(learner)`. If you
+    intentionally left it unimplemented, ignore this warning.
+
+  """
+const NO_DECONSTRUCTORS_FOR_STATIC = """
+
+    Since `LearnAPI.kind_of(learner)==LearnAPI.Static()`, we are checking that none of the
+    following are in the tuple returned by `LearnAPI.functions(learner)`:
+    `:(LearnAPI.features)`, `:(LearnAPI.target)`, `:(LearnAPI.weights)`, because there
+    is never training data to deconstruct.
 
-const FUNCTIONS3 = """
+  """
+const WARN_DESCRIMINATIVE_NO_FEATURES = """
 
-    Testing that `LearnAPI.functions(learner)` includes `:(LearnAPI.features).`
+    Typically, when `LearnAPI.kind_of(learner)==LearnAPI.Descriminative()`, we expect
+    `LearnAPI.features` to be implemented. If you have implemented it, check you added
+    `:(LearnAPI.features)` to the tuple returned by `LearnAPI.functions(learner)`. If you
+    intentionally left it unimplemented, ignore this warning.
 
   """
-const FUNCTIONS4 = """
+const WARN_DESCRIMINATIVE_NO_TARGET = """
 
-    Testing that `LearnAPI.functions(learner)` excludes `:(LearnAPI.features)`, as
-    `LearnAPI.is_static(learner)` is `true`.
+    Frequently, when `LearnAPI.kind_of(learner)==LearnAPI.Descriminative()`,
+    `LearnAPI.target` is also implemented. If you have implemented it, check you added
+    `:(LearnAPI.features)` to the tuple returned by `LearnAPI.functions(learner)`. If you
+    intentionally left it unimplemented, ignore this warning.
 
   """
 const TAGS = """
 
     Testing that `LearnAPI.tags(learner)` has correct form. List allowed tags with
-    `LearnAPII.tags()`.
+    `LearnAPI.tags()`.
 
   """
 const KINDS_OF_PROXY = """
@@ -62,14 +92,14 @@ const KINDS_OF_PROXY = """
   """
 const FIT_IS_STATIC = """
 
-    `LearnAPI.is_static(learner)` is `true`. Therefore attempting to call
-    `fit(learner)`.
+    `LearnAPI.kind_of(learner)==LearnAPI.Static()`. Therefore attempting to define
+    `model = fit(learner)`.
 
   """
 const FIT_IS_NOT_STATIC = """
 
-    Attempting to call `fit(learner, data)`. If you implemented `fit(learner)` instead,
-    then you need to arrange `LearnAPI.is_static(learner) == true`.
+    Attempting to define `model = fit(learner, data)`. If you implemented `fit(learner)`
+    instead, then you need to arrange `LearnAPI.kind_of(learner)==LearnAPI.Static()`.
 
   """
 const LEARNER = """
@@ -86,7 +116,7 @@ const FUNCTIONS2 = """
 
   """
 const ERR_MISSING_FUNCTIONS =
-    "The following overloaded functions are missing from the return value of"*
+    "The following implemented/overloaded functions are missing from the return value of"*
     "`LearnAPI.functions(learner)`: "
 
 const OBS = """
@@ -118,7 +148,9 @@ const PREDICT_HAS_NO_FEATURES = """
 
     Attempting to call `predict(model, kind)` for each `kind` in
     `LearnAPI.kinds_of_proxy(learner)`. (We are not providing `predict` with a data
-    argument because `features(obs(learner, data)) == nothing`).
+    argument because either `LearnAPI.kind_of(learner)==LearnAPI.Generative()`, or because
+    we presume `LearnAPI.features` is not implemented, as `:(LearnAPI.features)` is not in
+    the return value of LearnAPI.functions(learner)`.)
 
 
   """
@@ -256,14 +288,12 @@ const TRANSFORM_ON_SELECTIONS2 = """
   """
 const TARGET0 = """
 
-    Attempting to call `LearnAPI.target(learner, data)` (fallback returns
-    `last(data)`).
+    Attempting to call `LearnAPI.target(learner, data)`.
 
   """
 const TARGET = """
 
-    Attempting to call `LearnAPI.target(learner, observations)` (fallback returns
-    `last(observations)`).
+    Attempting to call `LearnAPI.target(learner, observations)`
 
   """
 const TARGET_SELECTIONS = """
@@ -311,7 +341,7 @@ const UPDATE = """
   """
 const ERR_STATIC_UPDATE = ErrorException(
     "`(LearnAPI.update)` is in `LearnAPI.functions(learner)` but "*
-        "`LearnAPI.is_static(learner)` is `true`. You cannot implement `update` "*
+        "`LearnAPI.kind_of(learner)==LearnAPI.Static()`. You cannot implement `update` "*
         "for static learners. "
 )
 const UPDATE_ITERATIONS = """

src/testapi.jl

@@ -60,14 +60,17 @@ hyperparameter settings, are explicitly tested.
 
 Each `dataset` is used as follows.
 
-If `LearnAPI.is_static(learner) == false`, then:
+Assuming [`LearnAPI.kind_of(learner)`](@ref) returns [`LearnAPI.Descriminative()`](@ref)
+or [`LearnAPI.Generative()`](@ref):
 
 - `dataset` is passed to `fit` and, if necessary, its `update` cousins
 
-- If `X = LearnAPI.features(learner, dataset) == nothing`, then `predict` and/or
-  `transform` are called with no data. Otherwise, they are called with `X`.
+- In the `Generative()` case, `predict` and/or `transform` are called without a data
+  argument; in the `Descriminative()` case these methods are called with the data argument
+  ` X = LearnAPI.features(learner, dataset)`, assuming `:features in
+  LearnAPI.functions(learner)`, and are otherwise not called.
 
-If instead `LearnAPI.is_static(learner) == true`, then `fit` and its cousins are called
+If instead `LearnAPI.kind_of(learner) == Static()`, then `fit` and its cousins are called
 without any data, and `dataset` is passed directly to `predict` and/or `transform`.
 
 """
@@ -87,7 +90,8 @@ macro testapi(learner, data...)
         verbosity=$verbosity
         _human_name = LearnAPI.human_name(learner)
         _data_interface = LearnAPI.data_interface(learner)
-        _is_static = LearnAPI.is_static(learner)
+        _is_static = LearnAPI.kind_of(learner) == LearnAPI.Static()
+        _is_generative = LearnAPI.kind_of(learner) == LearnAPI.Generative()
 
         if isnothing(verbosity) || verbosity > 0
             @info "------ running @testapi - $_human_name "*$LOUD
@@ -124,13 +128,21 @@ macro testapi(learner, data...)
             end
         end
 
-        if !_is_static
-            @logged_testset $FUNCTIONS3 verbosity begin
-                Test.@test :(LearnAPI.features) in _functions
-            end
-        else
-            @logged_testset $FUNCTIONS4 verbosity begin
-                Test.@test !(:(LearnAPI.features) in _functions)
+        _has_features = :(LearnAPI.features) in _functions
+        _has_target = :(LearnAPI.target) in _functions
+        _has_weights = :(LearnAPI.weights) in _functions
+
+        @logged_testset $DECONSTRUCTORS verbosity begin
+             if _is_generative
+                !_has_target && verbosity > 0 && @warn $WARN_GENERATIVE_NO_TARGET
+                Test.@test !_has_features
+            elseif _is_static
+                @logged_testset $NO_DECONSTRUCTORS_FOR_STATIC verbosity begin
+                    Test.@test !_has_target && !_has_features && !_has_weights
+                end
+            else
+                !_has_features && verbosity > 0 && @warn $WARN_DESCRIMINATIVE_NO_FEATURES
+                !_has_features && verbosity > 0 && @warn $WARN_DESCRIMINATIVE_NO_TARGET
             end
         end
 
@@ -199,13 +211,15 @@ macro testapi(learner, data...)
 
             X = if _is_static
                 data
-            else
+            elseif _has_features
                 @logged_testset $FEATURES0 verbosity begin
                     LearnAPI.features(learner, data)
                 end
                 @logged_testset $FEATURES verbosity begin
                     LearnAPI.features(learner, observations)
                 end
+            else
+                nothing
             end
 
             if !(isnothing(X))
@@ -467,25 +481,18 @@ macro testapi(learner, data...)
 
             # weights
 
-            _w = @logged_testset $WEIGHTS verbosity begin
-                LearnAPI.weights(learner, observations)
-            end
-
-            if !(isnothing(_w))
-                @logged_testset $WEIGHTS_IN_FUNCTIONS verbosity begin
-                    Test.@test :(LearnAPI.weights) in _functions
+            if :(LearnAPI.weights) in _functions
+                _w = @logged_testset $WEIGHTS verbosity begin
+                    LearnAPI.weights(learner, observations)
                 end
+
                 w = @logged_testset $WEIGHTS_SELECTIONS verbosity begin
                     LearnTestAPI.learner_get(
                         learner,
                         data,
                         data->LearnAPI.weights(learner, data),
                     )
                 end
-            else
-                @logged_testset $WEIGHTS_NOT_IN_FUNCTIONS verbosity begin
-                    Test.@test !(:(LearnAPI.weights) in _functions)
-                end
             end
 
             # update
@@ -612,7 +619,7 @@ macro testapi(learner, data...)
 
             # traits
             # `constructor`,  `functions`, `kinds_of_proxy`, `tags`, `nonlearners`,
-            # `iteration_parameter`, `data_interface`, `is_static` tested already above
+            # `iteration_parameter`, `data_interface`, `kind_of` tested already above
 
             @logged_testset $PKG_NAME verbosity begin
                 pkg_name = LearnAPI.pkg_name(learner)
@@ -686,3 +693,4 @@ macro testapi(learner, data...)
         nothing
     end # quote
 end # macro
+

test/learners/classification.jl

@@ -45,7 +45,7 @@ f = @formula(t ~ c + a)
 # # TESTS
 
 learner = LearnTestAPI.ConstantClassifier()
-@testapi learner (X1, y)
+@testapi learner (X1, y) verbosity=0
 @testapi learner (X2, y) (X3, y) (X4, y) (T1, :t) (T2, :t) (T3, f) (T4, f) verbosity=0
 
 @testset "extra tests for constant classifier" begin

test/learners/dimension_reduction.jl

@@ -12,7 +12,7 @@ U, Vt = r.U, r.Vt
 X = U*diagm([1, 2, 3, 0.01, 0.01])*Vt
 
 learner = LearnTestAPI.TruncatedSVD(codim=2)
-@testapi learner X verbosity=1
+@testapi learner X verbosity=0
 
 @testset "extra test for truncated SVD" begin
     model = @test_logs(