make multi changes to accssr fnctns; add clone to functions()

Author: ablaom

docs/src/accessor_functions.md

@@ -13,9 +13,10 @@ The sole argument of an accessor function is the output, `model`, of
 - [`LearnAPI.trees(model)`](@ref)
 - [`LearnAPI.feature_names(model)`](@ref)
 - [`LearnAPI.feature_importances(model)`](@ref)
-- [`LearnAPI.training_labels(model)`](@ref)
 - [`LearnAPI.training_losses(model)`](@ref)
-- [`LearnAPI.training_predictions(model)`](@ref)
+- [`LearnAPI.out_of_sample_losses(model)`](@ref)
+- [`LearnAPI.predictions(model)`](@ref)
+- [`LearnAPI.out_of_sample_indices(model)`](@ref)
 - [`LearnAPI.training_scores(model)`](@ref)
 - [`LearnAPI.components(model)`](@ref)
 
@@ -42,9 +43,10 @@ LearnAPI.trees
 LearnAPI.feature_names
 LearnAPI.feature_importances
 LearnAPI.training_losses
-LearnAPI.training_predictions
+LearnAPI.out_of_sample_losses
+LearnAPI.predictions
+LearnAPI.out_of_sample_indices
 LearnAPI.training_scores
-LearnAPI.training_labels
 LearnAPI.components
 ```
 

docs/src/anatomy_of_an_implementation.md

@@ -50,7 +50,7 @@ nothing # hide
 
 ## Defining learners
 
-Here's a new type whose instances specify ridge regression hyperparameters:
+Here's a new type whose instances specify the single ridge regression hyperparameter:
 
 ```@example anatomy
 struct Ridge{T<:Real}
@@ -280,7 +280,7 @@ nothing # hide
 
 ```@example anatomy
 learner = Ridge(lambda=0.5)
-foreach(println, LearnAPI.functions(learner))
+@functions learner
 ```
 
 Training and predicting:
@@ -344,6 +344,7 @@ LearnAPI.strip(model::RidgeFitted) =
     functions = (
         :(LearnAPI.fit),
         :(LearnAPI.learner),
+        :(LearnAPI.clone),
         :(LearnAPI.strip),
         :(LearnAPI.obs),
         :(LearnAPI.features),

docs/src/fit_update.md

@@ -111,8 +111,8 @@ Exactly one of the following must be implemented:
 | method                                                                               | fallback | compulsory? |
 |:-------------------------------------------------------------------------------------|:---------|-------------|
 | [`update`](@ref)`(model, data; verbosity=..., hyperparameter_updates...)`              | none     | no          |
-| [`update_observations`](@ref)`(model, data; verbosity=..., hyperparameter_updates...)` | none     | no          |
-| [`update_features`](@ref)`(model, data; verbosity=..., hyperparameter_updates...)`     | none     | no          |
+| [`update_observations`](@ref)`(model, new_data; verbosity=..., hyperparameter_updates...)` | none     | no          |
+| [`update_features`](@ref)`(model, new_data; verbosity=..., hyperparameter_updates...)`     | none     | no          |
 
 There are some contracts governing the behaviour of the update methods, as they relate to
 a previous `fit` call. Consult the document strings for details.

docs/src/index.md

@@ -50,9 +50,9 @@ 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.
 
 ```julia
-X = <some training features>
-y = <some training target>
-Xnew = <some test or production features>
+# `X` is some training features
+# `y` is some training target
+# `Xnew` is some test or production features
 
 # List LearnaAPI functions implemented for `forest`:
 @functions forest
@@ -72,11 +72,6 @@ LearnAPI.feature_importances(model)
 # Slim down and otherwise prepare model for serialization:
 small_model = LearnAPI.strip(model)
 serialize("my_random_forest.jls", small_model)
-
-# Recover saved model and algorithm configuration ("learner"):
-recovered_model = deserialize("my_random_forest.jls")
-@assert LearnAPI.learner(recovered_model) == forest
-@assert predict(recovered_model, Point(), Xnew) == ŷ
 ```
 
 `Distribution` and `Point` are singleton types owned by LearnAPI.jl. They allow

docs/src/patterns/ensembling.md

@@ -4,3 +4,4 @@ See these examples from the JuliaTestAPI.jl test suite:
 
 - [bagged ensembling of a regression model](https://github.com/JuliaAI/LearnTestAPI.jl/blob/dev/test/patterns/ensembling.jl)
 
+- [extremely randomized ensemble of decision stumps (regression)](https://github.com/JuliaAI/LearnTestAPI.jl/blob/dev/test/patterns/ensembling.jl)

docs/src/patterns/iterative_algorithms.md

@@ -5,3 +5,5 @@ See these examples from the JuliaTestAI.jl test suite:
 - [bagged ensembling](https://github.com/JuliaAI/LearnTestAPI.jl/blob/dev/test/patterns/ensembling.jl)
 
 - [perceptron classifier](https://github.com/JuliaAI/LearnTestAPI.jl/blob/dev/test/patterns/gradient_descent.jl)
+
+- [extremely randomized ensemble of decision stumps (regression)](https://github.com/JuliaAI/LearnTestAPI.jl/blob/dev/test/patterns/ensembling.jl)

docs/src/patterns/regression.md

@@ -4,3 +4,4 @@ See these examples from the JuliaTestAPI.jl test suite:
 
 - [ridge regression](https://github.com/JuliaAI/LearnTestAPI.jl/blob/dev/test/patterns/regression.jl)
 
+- [extremely randomized ensemble of decision stumps](https://github.com/JuliaAI/LearnTestAPI.jl/blob/dev/test/patterns/ensembling.jl)

docs/src/reference.md

@@ -27,9 +27,9 @@ see [`obs`](@ref) and [`LearnAPI.data_interface`](@ref) for details.
 
 !!! note
 
-    In the MLUtils.jl
-    convention, observations in tables are the rows but observations in a matrix are the
-    columns.
+	In the MLUtils.jl
+	convention, observations in tables are the rows but observations in a matrix are the
+	columns.
 
 ### [Hyperparameters](@id hyperparameters)
 
@@ -96,9 +96,9 @@ 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
-    [`fit`](@ref).
+	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
+	[`fit`](@ref).
 
 #### Composite learners (wrappers)
 
@@ -119,19 +119,19 @@ Below is an example of a learner type with a valid constructor:
 
 ```julia
 struct GradientRidgeRegressor{T<:Real}
-    learning_rate::T
-    epochs::Int
-    l2_regularization::T
+	learning_rate::T
+	epochs::Int
+	l2_regularization::T
 end
 
 """
-    GradientRidgeRegressor(; learning_rate=0.01, epochs=10, l2_regularization=0.01)
-	
+	GradientRidgeRegressor(; learning_rate=0.01, epochs=10, l2_regularization=0.01)
+
 Instantiate a gradient ridge regressor with the specified hyperparameters.
 
 """
 GradientRidgeRegressor(; learning_rate=0.01, epochs=10, l2_regularization=0.01) =
-    GradientRidgeRegressor(learning_rate, epochs, l2_regularization)
+	GradientRidgeRegressor(learning_rate, epochs, l2_regularization)
 LearnAPI.constructor(::GradientRidgeRegressor) = GradientRidgeRegressor
 ```
 
@@ -146,9 +146,9 @@ interface.)
 
 !!! note "Compulsory methods"
 
-    All new learner types must implement [`fit`](@ref),
-    [`LearnAPI.learner`](@ref), [`LearnAPI.constructor`](@ref) and
-    [`LearnAPI.functions`](@ref).
+	All new learner types must implement [`fit`](@ref),
+	[`LearnAPI.learner`](@ref), [`LearnAPI.constructor`](@ref) and
+	[`LearnAPI.functions`](@ref).
 
 Most learners will also implement [`predict`](@ref) and/or [`transform`](@ref). For a
 minimal (but useless) implementation, see the implementation of `SmallLearner`
@@ -198,10 +198,14 @@ minimal (but useless) implementation, see the implementation of `SmallLearner`
 
 ## Utilities
 
+- [`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
-@functions
-LearnAPI.clone
+clone
 @trait
+@functions
 ```
 
 ---

src/LearnAPI.jl

@@ -11,7 +11,7 @@ include("accessor_functions.jl")
 include("traits.jl")
 include("clone.jl")
 
-export @trait, @functions
+export @trait, @functions, clone
 export fit, update, update_observations, update_features
 export predict, transform, inverse_transform, obs