add missing examples.md file; plus some tweaks

Author: ablaom

docs/src/anatomy_of_an_implementation.md

@@ -324,12 +324,12 @@ using LearnTestAPI
 
 ## [Other data patterns](@id di)
 
-Here are some important remarks for implementations wanting to deviate in their
+Here are some important remarks for implementations deviating in their
 assumptions about data from those made above.
 
 - New implementations of `fit`, `predict`, etc, always have a *single* `data` argument as
-  above.  For convenience, a signature such as `fit(learner, X, y)`, calling `fit(learner,
-  (X, y))`, can be added, but the LearnAPI.jl specification is silent on the meaning or
+  above.  For convenience, a signature such as `fit(learner, table, formula)`, calling `fit(learner,
+  (table, formula))`, can be added, but the LearnAPI.jl specification is silent on the meaning or
   existence of signatures with extra arguments.
 
 - If the `data` object consumed by `fit`, `predict`, or `transform` is not not a suitable
@@ -415,7 +415,7 @@ The [`obs`](@ref) methods exist to:
 !!! important
 
     While many new learner implementations will want to adopt a canned data front end, such as those provided by [LearnDataFrontEnds.jl](https://juliaai.github.io/LearnAPI.jl/dev/), we
-    focus here on a self-contained implemementation of `obs` for the ridge example above, to show
+    focus here on a self-contained implementation of `obs` for the ridge example above, to show
     how it works.
 
 In the typical case, where [`LearnAPI.data_interface`](@ref) is not overloaded, the

docs/src/examples.md

@@ -0,0 +1,192 @@
+# [Code for ridge example](@id code)
+
+Below is the complete source code for the ridge implementations described in the tutorial,
+[Anatomy of an Implementation](@ref).
+
+- [Basic implementation](@ref)
+- [Implementation with data front end](@ref)
+
+
+## Basic implementation
+
+```julia
+using LearnAPI
+using LinearAlgebra, Tables
+
+struct Ridge{T<:Real}
+    lambda::T
+end
+
+"""
+    Ridge(; lambda=0.1)
+
+Instantiate a ridge regression learner, with regularization of `lambda`.
+"""
+Ridge(; lambda=0.1) = Ridge(lambda)
+LearnAPI.constructor(::Ridge) = Ridge
+
+# struct for output of `fit`
+struct RidgeFitted{T,F}
+    learner::Ridge
+    coefficients::Vector{T}
+    named_coefficients::F
+end
+
+function LearnAPI.fit(learner::Ridge, data; verbosity=1)
+    X, y = data
+
+    # data preprocessing:
+    table = Tables.columntable(X)
+    names = Tables.columnnames(table) |> collect
+    A = Tables.matrix(table, transpose=true)
+
+    lambda = learner.lambda
+
+    # apply core algorithm:
+    coefficients = (A*A' + learner.lambda*I)\(A*y) # vector
+
+    # determine named coefficients:
+    named_coefficients = [names[j] => coefficients[j] for j in eachindex(names)]
+
+    # make some noise, if allowed:
+    verbosity > 0 && @info "Coefficients: $named_coefficients"
+
+    return RidgeFitted(learner, coefficients, named_coefficients)
+end
+
+LearnAPI.predict(model::RidgeFitted, ::Point, Xnew) =
+    Tables.matrix(Xnew)*model.coefficients
+
+# accessor functions:
+LearnAPI.learner(model::RidgeFitted) = model.learner
+LearnAPI.coefficients(model::RidgeFitted) = model.named_coefficients
+LearnAPI.strip(model::RidgeFitted) =
+    RidgeFitted(model.learner, model.coefficients, nothing)
+
+@trait(
+    Ridge,
+    constructor = Ridge,
+    kinds_of_proxy=(Point(),),
+    tags = ("regression",),
+    functions = (
+        :(LearnAPI.fit),
+        :(LearnAPI.learner),
+        :(LearnAPI.clone),
+        :(LearnAPI.strip),
+        :(LearnAPI.obs),
+        :(LearnAPI.features),
+        :(LearnAPI.target),
+        :(LearnAPI.predict),
+        :(LearnAPI.coefficients),
+   )
+)
+
+# convenience method:
+LearnAPI.fit(learner::Ridge, X, y; kwargs...) = fit(learner, (X, y); kwargs...)
+```
+
+# Implementation with data front end
+
+```julia
+using LearnAPI
+using LinearAlgebra, Tables
+
+struct Ridge{T<:Real}
+   lambda::T
+end
+
+Ridge(; lambda=0.1) = Ridge(lambda)
+
+# struct for output of `fit`:
+struct RidgeFitted{T,F}
+    learner::Ridge
+    coefficients::Vector{T}
+    named_coefficients::F
+end
+
+# struct for internal representation of training data:
+struct RidgeFitObs{T,M<:AbstractMatrix{T}}
+    A::M                  # `p` x `n` matrix
+    names::Vector{Symbol} # features
+    y::Vector{T}          # target
+end
+
+# implementation of `RandomAccess()` data interface for such representation:
+Base.getindex(data::RidgeFitObs, I) =
+    RidgeFitObs(data.A[:,I], data.names, y[I])
+Base.length(data::RidgeFitObs) = length(data.y)
+
+# data front end for `fit`:
+function LearnAPI.obs(::Ridge, data)
+    X, y = data
+    table = Tables.columntable(X)
+    names = Tables.columnnames(table) |> collect
+    return RidgeFitObs(Tables.matrix(table)', names, y)
+end
+LearnAPI.obs(::Ridge, observations::RidgeFitObs) = observations
+
+function LearnAPI.fit(learner::Ridge, observations::RidgeFitObs; verbosity=1)
+
+    lambda = learner.lambda
+
+    A = observations.A
+    names = observations.names
+    y = observations.y
+
+    # apply core learner:
+    coefficients = (A*A' + learner.lambda*I)\(A*y) # 1 x p matrix
+
+    # determine named coefficients:
+    named_coefficients = [names[j] => coefficients[j] for j in eachindex(names)]
+
+    # make some noise, if allowed:
+    verbosity > 0 && @info "Coefficients: $named_coefficients"
+
+    return RidgeFitted(learner, coefficients, named_coefficients)
+
+end
+
+LearnAPI.fit(learner::Ridge, data; kwargs...) =
+    fit(learner, obs(learner, data); kwargs...)
+
+# data front end for `predict`:
+LearnAPI.obs(::RidgeFitted, Xnew) = Tables.matrix(Xnew)'
+LearnAPI.obs(::RidgeFitted, observations::AbstractArray) = observations # involutivity
+
+LearnAPI.predict(model::RidgeFitted, ::Point, observations::AbstractMatrix) =
+    observations'*model.coefficients
+
+LearnAPI.predict(model::RidgeFitted, ::Point, Xnew) =
+    predict(model, Point(), obs(model, Xnew))
+
+# methods to deconstruct training data:
+LearnAPI.features(::Ridge, observations::RidgeFitObs) = observations.A
+LearnAPI.target(::Ridge, observations::RidgeFitObs) = observations.y
+LearnAPI.features(learner::Ridge, data) = LearnAPI.features(learner, obs(learner, data))
+LearnAPI.target(learner::Ridge, data) = LearnAPI.target(learner, obs(learner, data))
+
+# accessor functions:
+LearnAPI.learner(model::RidgeFitted) = model.learner
+LearnAPI.coefficients(model::RidgeFitted) = model.named_coefficients
+LearnAPI.strip(model::RidgeFitted) =
+    RidgeFitted(model.learner, model.coefficients, nothing)
+
+@trait(
+    Ridge,
+    constructor = Ridge,
+    kinds_of_proxy=(Point(),),
+    tags = ("regression",),
+    functions = (
+        :(LearnAPI.fit),
+        :(LearnAPI.learner),
+        :(LearnAPI.clone),
+        :(LearnAPI.strip),
+        :(LearnAPI.obs),
+        :(LearnAPI.features),
+        :(LearnAPI.target),
+        :(LearnAPI.predict),
+        :(LearnAPI.coefficients),
+   )
+)
+
+```

docs/src/index.md

@@ -47,7 +47,7 @@ Suppose `forest` is some object encapsulating the hyperparameters of the [random
 algorithm](https://en.wikipedia.org/wiki/Random_forest) (the number of trees, etc.). Then,
 a LearnAPI.jl interface can be implemented, for objects with the type of `forest`, to
 enable the basic workflow below. In this case data is presented following the
-"scikit-learn" `X, y` pattern, although LearnAPI.jl supports other patterns as well.
+"scikit-learn" `X, y` pattern, although LearnAPI.jl supports other data pattern.
 
 ```julia
 # `X` is some training features

docs/src/reference.md

@@ -38,9 +38,9 @@ number of user-specified *hyperparameters*, such as the number of trees in a ran
 forest. Hyperparameters are understood in a rather broad sense. For example, one is
 allowed to have hyperparameters that are not data-generic.  For example, a class weight
 dictionary, which will only make sense for a target taking values in the set of specified
-dictionary keys, should be given as a hyperparameter. For simplicity, LearnAPI.jl
-discourages "run time" parameters (extra arguments to `fit`) such as acceleration
-options (cpu/gpu/multithreading/multiprocessing). These should be included as
+dictionary keys, should be given as a hyperparameter. For simplicity and composability,
+LearnAPI.jl discourages "run time" parameters (extra arguments to `fit`) such as
+acceleration options (cpu/gpu/multithreading/multiprocessing). These should be included as
 hyperparameters as far as possible. An exception is the compulsory `verbosity` keyword
 argument of `fit`.
 
@@ -102,7 +102,7 @@ generally requires overloading `Base.==` for the struct.
 !!! important
 
 	No LearnAPI.jl method is permitted to mutate a learner. In particular, one should make
-	deep copies of RNG hyperparameters before using them in a new implementation of
+	deep copies of RNG hyperparameters before using them in an implementation of
 	[`fit`](@ref).
 
 #### Composite learners (wrappers)
@@ -114,9 +114,6 @@ properties that are not in [`LearnAPI.learners(learner)`](@ref). Instead, these
 learner-valued properties can have a `nothing` default, with the constructor throwing an
 error if the constructor call does not explicitly specify a new value.
 
-Any object `learner` for which [`LearnAPI.functions(learner)`](@ref) is non-empty is
-understood to have a valid implementation of the LearnAPI.jl interface.
-
 #### Example
 
 Below is an example of a learner type with a valid constructor:
@@ -139,6 +136,14 @@ GradientRidgeRegressor(; learning_rate=0.01, epochs=10, l2_regularization=0.01)
 LearnAPI.constructor(::GradientRidgeRegressor) = GradientRidgeRegressor
 ```
 
+#### Testing something is a learner
+
+Any object `object` for which [`LearnAPI.functions(object)`](@ref) is non-empty is
+understood to have a valid implementation of the LearnAPI.jl interface. You can test this
+with the convenience method [`LearnAPI.is_learner(object)`](@ref) but this is never explicitly
+overloaded.
+
+
 ## Documentation
 
 Attach public LearnAPI.jl-related documentation for a learner to it's *constructor*,
@@ -200,11 +205,14 @@ Most learners will also implement [`predict`](@ref) and/or [`transform`](@ref).
 
 ## Utilities
 
+
+- [`LearnAPI.is_learner`](@ref)
 - [`clone`](@ref): for cloning a learner with specified hyperparameter replacements.
 - [`@trait`](@ref): for simultaneously declaring multiple traits
 - [`@functions`](@ref): for listing functions available for use with a learner 
 
 ```@docs
+LearnAPI.is_learner
 clone
 @trait
 @functions

src/traits.jl

@@ -74,8 +74,8 @@ reference functions not owned by LearnAPI.jl.
 The understanding is that `learner` is a LearnAPI-compliant object whenever the return
 value is non-empty.
 
-Do `LearnAPI.functions()` to list all possible elements of the return value owned by
-LearnAPI.jl.
+Do `LearnAPI.functions()` to list all possible elements of the return value representing
+functions owned by LearnAPI.jl.
 
 # Extended help
 
@@ -513,6 +513,16 @@ This trait should not be overloaded. Instead overload [`LearnAPI.nonlearners`](@
 
 """
 learners(learner) = setdiff(propertynames(learner), nonlearners(learner))
+
+"""
+    LearnAPI.is_learner(object)
+
+Returns `true` if `object` has a valid implementation of the LearnAPI.jl
+interface. Equivalent to non-emptiness of [`LearnAPI.functions(object)`](@ref).
+
+This trait should never be overloaded explicitly.
+
+"""
 is_learner(learner) = !isempty(functions(learner))
 preferred_kind_of_proxy(learner) = first(kinds_of_proxy(learner))
 target(learner) = :(LearnAPI.target) in functions(learner)