add more doc improvements

Author: ablaom

README.md

@@ -6,8 +6,7 @@ A base Julia interface for machine learning and statistics
 [![Build Status](https://github.com/JuliaAI/LearnAPI.jl/workflows/CI/badge.svg)](https://github.com/JuliaAI/LearnAPI.jl/actions)
 [![codecov](https://codecov.io/gh/JuliaAI/LearnAPI.jl/graph/badge.svg?token=9IWT9KYINZ)](https://codecov.io/gh/JuliaAI/LearnAPI.jl?branch=dev)
 [![Docs](https://img.shields.io/badge/docs-dev-blue.svg)](https://juliaai.github.io/LearnAPI.jl/dev/)
-
-Comprehensive documentation is [here](https://juliaai.github.io/LearnAPI.jl/dev/).
+[![Docs](https://img.shields.io/badge/docs-stable-blue.svg)](https://juliaai.github.io/LearnAPI.jl/stable/)
 
 New contributions welcome. See the [road map](ROADMAP.md).
 
@@ -24,13 +23,40 @@ predict(model, newdata)
 Here `learner` specifies the configuration the algorithm (the hyperparameters) while
 `model` stores learned parameters and any byproducts of algorithm execution.
 
+LearnAPI.jl mostly a few method stubs and lots of documentation. It does not provide
+meta-algorithms, such as cross-validation or hyperparameter optimization, but does aim to
+support such algorithms.
+
 ## Related packages
 
-- [MLCore.jl](https://github.com/JuliaML/MLCore.jl) ([docs](https://juliaml.github.io/MLCore.jl/stable/api/#Core-API))
+- [MLCore.jl](https://github.com/JuliaML/MLCore.jl): The default sub-sampling API (`getobs`/`numbobs`) for LearnAPI.jl implementations, which supports tables and arrays.
 
 - [LearnTestAPI.jl](https://github.com/JuliaAI/LearnTestAPI.jl): Package to test implementations of LearnAPI.jl (but documented here)
 
-- [LearnDataFrontEnds.jl](https://github.com/JuliaAI/LearnDataFrontEnds.jl): for including flexible, user-friendly, data front ends for LearnAPI.jl implementations ([docs](https://juliaai.github.io/stable/))
+- [LearnDataFrontEnds.jl](https://github.com/JuliaAI/LearnDataFrontEnds.jl): For including flexible, user-friendly, data front ends for LearnAPI.jl implementations ([docs](https://juliaai.github.io/stable/))
+
+- [StatisticalMeasures.jl](https://github.com/JuliaAI/StatisticalMeasures.jl): Package providing metrics, compatible with LearnAPI.jl
+
+### Selected packages providing alternative API's
+
+The following alphabetical list of packages provide public base API's.  Some provide
+additional functionality. PR's to add missing items very welcome.
+
+- [AutoMLPipeline.jl](https://github.com/IBM/AutoMLPipeline.jl)
+
+- [BetaML.jl](https://github.com/sylvaticus/BetaML.jl)
+
+- [FastAI.jl](https://github.com/FluxML/FastAI.jl) (focused on deep learning)
+
+- [LearnBase.jl](https://github.com/JuliaML/LearnBase.jl) (now archived but of historical interest)
+
+- [MLJModelInterface.jl](https://github.com/JuliaAI/MLJModelInterface.jl)
+
+- [ScikitLearn.jl](https://github.com/cstjean/ScikitLearn.jl) (an API in addition to being a wrapper for [scikit-learn](https://scikit-learn.org/stable/)
+
+- [StatsAPI.jl](https://github.com/JuliaStats/StatsAPI.jl/blob/main/src/regressionmodel.jl) (specialized to needs of traditional statistical models)
+
+- [MLUtils.jl](https://github.com/JuliaML/MLUtils.jl) (more than a base API, and focused on deep learning)
 
 
 ## Credits

docs/make.jl

@@ -17,6 +17,7 @@ makedocs(
         "Anatomy of an Implementation" => "anatomy_of_an_implementation.md",
         "Reference" => [
             "Overview" => "reference.md",
+            "Public Names" => "list_of_public_names.md",
             "fit/update" => "fit_update.md",
             "predict/transform" => "predict_transform.md",
             "Kinds of Target Proxy" => "kinds_of_target_proxy.md",

docs/src/anatomy_of_an_implementation.md

@@ -555,8 +555,8 @@ above. Here we must explicitly overload them, so that they also handle the outpu
 
 ```@example anatomy2
 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(::Ridge, observations::RidgeFitObs) = observations.y
 LearnAPI.target(learner::Ridge, data) = LearnAPI.target(learner, obs(learner, data))
 ```
 

docs/src/examples.md

@@ -4,7 +4,8 @@ Below is the complete source code for the ridge implementations described in the
 [Anatomy of an Implementation](@ref).
 
 - [Basic implementation](@ref)
-- [Implementation with data front end](@ref)
+- [Implementation with a data front end](@ref)
+- [Implementation with a canned data front end](@ref) 
 
 
 ## Basic implementation
@@ -85,7 +86,7 @@ LearnAPI.strip(model::RidgeFitted) =
 LearnAPI.fit(learner::Ridge, X, y; kwargs...) = fit(learner, (X, y); kwargs...)
 ```
 
-# Implementation with data front end
+# Implementation with a data front end
 
 ```julia
 using LearnAPI
@@ -190,3 +191,91 @@ LearnAPI.strip(model::RidgeFitted) =
 )
 
 ```
+
+# Implementation with a canned data front end
+
+The following implements the `Saffron` data front end from
+[LearnDataFrontEnds.jl](https://juliaai.github.io/LearnDataFrontEnds.jl/stable/), which
+allows for a greater variety of forms of input to `fit` and `predict`.  Refer to that
+package's [documentation](https://juliaai.github.io/LearnDataFrontEnds.jl/stable/) for details.
+    
+```julia
+using LearnAPI
+import LearnDataFrontEnds as FrontEnds
+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
+
+frontend = FrontEnds.Saffron()
+
+# these will return objects of type `FrontEnds.Obs`:
+LearnAPI.obs(learner::Ridge, data) = FrontEnds.fitobs(learner, data, frontend)
+LearnAPI.obs(model::RidgeFitted, data) = obs(model, data, frontend)
+
+function LearnAPI.fit(learner::Ridge, observations::FrontEnds.Obs; verbosity=1)
+
+    lambda = learner.lambda
+
+    A = observations.features
+    names = observations.names
+    y = observations.target
+
+    # 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...)
+
+LearnAPI.predict(model::RidgeFitted, ::Point, observations::FrontEnds.Obs) =
+    (observations.features)'*model.coefficients
+LearnAPI.predict(model::RidgeFitted, ::Point, Xnew) =
+    predict(model, Point(), obs(model, Xnew))
+
+# training data deconstructors:
+LearnAPI.features(learner::Ridge, data) = LearnAPI.features(learner, data, frontend)
+LearnAPI.target(learner::Ridge, data) = LearnAPI.target(learner, data, frontend)
+
+# 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

@@ -29,25 +29,14 @@ includes a number of Julia [traits](@ref traits) for promising specific behavior
 
 LearnAPI.jl's has no package dependencies.
 
-```@raw html
-🚧
-```
-
-!!! warning
-
-	The API described here is under active development and not ready for adoption.
-	Join an ongoing design discussion at
-	[this](https://discourse.julialang.org/t/ann-learnapi-jl-proposal-for-a-basement-level-machine-learning-api/93048)
-	Julia Discourse thread.
-
 
 ## Sample workflow
 
 Suppose `forest` is some object encapsulating the hyperparameters of the [random forest
 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 data pattern.
+"scikit-learn" `X, y` pattern, although LearnAPI.jl supports other data patterns.
 
 ```julia
 # `X` is some training features
@@ -58,7 +47,7 @@ enable the basic workflow below. In this case data is presented following the
 @functions forest
 
 # Train:
-model = fit(forest, X, y)
+model = fit(forest, (X, y))
 
 # Generate point predictions:
 ŷ = predict(model, Xnew) # or `predict(model, Point(), Xnew)`
@@ -81,16 +70,16 @@ on the usual supervised/unsupervised learning dichotomy. From this point of view
 supervised learner is simply one in which a target variable exists, and happens to
 appear as an input to training but not to prediction.
 
-## Data interfaces
+## Data interfaces and front ends
 
 Algorithms are free to consume data in any format. However, a method called [`obs`](@ref
 data_interface) (read as "observations") gives developers the option of providing a
 separate data front end for their algorithms. In this case `obs` gives users and
 meta-algorithms access to an algorithm-specific representation of input data, which is
-additionally guaranteed to implement a standard interface for accessing individual observations,
-unless the algorithm explicitly opts out. Moreover, the `fit` and `predict` methods will
-also be able to consume these alternative data representations, for performance benefits
-in some situations.
+additionally guaranteed to implement a standard interface for accessing individual
+observations, unless the algorithm explicitly opts out. Moreover, the `fit` and `predict`
+methods can directly consume these alternative data representations, for performance
+benefits in some situations, such as cross-validation.
 
 The fallback data interface is the [MLCore.jl](https://github.com/JuliaML/MLCore.jl)
 `getobs/numobs` interface (previously provided by MLUtils.jl) here tagged as

docs/src/list_of_public_names.md

@@ -0,0 +1,49 @@
+# List of Public Names
+
+## Core methods
+
+- [`fit`](@ref)
+
+- [`update`](@ref)
+
+- [`update_observations`](@ref)
+
+- [`predict`](@ref)
+
+- [`transform`](@ref)
+
+- [`inverse_transform`](@ref)
+
+- [`obs`](@ref)
+
+## Training data deconstructors
+
+- [`LearnAPI.features`](@ref)
+
+- [`LearnAPI.target`](@ref)
+  
+- [`LearnAPI.weights`](@ref)
+  
+
+## Accessor functions
+
+See [here](@ref accessor_functions).
+
+
+## Learner traits
+
+See [here](@ref traits).
+
+
+## Kinds of target proxy
+
+See [here](@ref proxy_types).
+
+
+## Utilities (never overloaded)
+
+- [`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/src/reference.md

@@ -1,8 +1,10 @@
 # [Reference](@id reference)
 
 Here we give the definitive specification of the LearnAPI.jl interface. For informal
-guides see [Anatomy of an Implementation](@ref) and [Common Implementation
-Patterns](@ref patterns).
+guides see [Anatomy of an Implementation](@ref) and [Common Implementation Patterns](@ref
+patterns).
+
+ - [List of Public Names](@ref)
 
 
 ## [Important terms and concepts](@id scope)
@@ -190,7 +192,7 @@ Most learners will also implement [`predict`](@ref) and/or [`transform`](@ref).
 
 - [`LearnAPI.features`](@ref input), [`LearnAPI.target`](@ref input),
   [`LearnAPI.weights`](@ref input): for extracting relevant parts of training data, where
-  defined.
+  defined. Also called *training data deconstructors*. 
 
 - [Accessor functions](@ref accessor_functions): these include functions like
   `LearnAPI.feature_importances` and `LearnAPI.training_losses`, for extracting, from

docs/src/testing_an_implementation.md

@@ -1,22 +1,20 @@
 # Testing an Implementation
 
-Testing is provided by the LearnTestAPI.jl package documented below. 
+Testing is provided by the LearnTestAPI.jl package documented below.
 
 ## Quick start
 
 ```@docs
 LearnTestAPI
 ```
 
-LearnAPI.jl and LearnTestAPI.jl have synchronized releases. For example, LearnTestAPI.jl
-version 0.2.3 will generally support all LearnAPI.jl versions 0.2.*.
-
 !!! warning
 
-    New releases of LearnTestAPI.jl may add tests to `@testapi`, and this may result in
-    new failures in client package test suites. Nevertheless, adding a test to `@testapi`
-    is not considered a breaking change to LearnTestAPI, unless the addition supports a
-    breaking release of LearnAPI.jl.
+	New releases of LearnTestAPI.jl may add tests to `@testapi`, and
+	this may result in new failures in client package test suites, because
+	of previously undetected broken contracts. Adding a test to `@testapi`
+	is not considered a breaking change
+	to LearnTestAPI, unless it supports a breaking change to LearnAPI.jl.
 
 
 ## The @testapi macro
@@ -28,7 +26,7 @@ LearnTestAPI.@testapi
 ## Learners for testing
 
 LearnTestAPI.jl provides some simple, tested, LearnAPI.jl implementations, which may be
-useful for testing learner wrappers and meta-algorithms. 
+useful for testing learner wrappers and meta-algorithms.
 
 ```@docs
 LearnTestAPI.Ridge
@@ -44,7 +42,7 @@ LearnTestAPI.StumpRegressor
 
 ## Private methods
 
-For LearnTestAPI.jl developers only, and subject to breaking changes:
+For LearnTestAPI.jl developers only, and subject to breaking changes at any time:
 
 ```@docs
 LearnTestAPI.@logged_testset

src/traits.jl

@@ -65,7 +65,7 @@ Return a tuple of expressions representing functions that can be meaningfully ap
 argument. Learner traits (methods for which `learner` is the *only* argument) are
 excluded.
 
-To return actual functions, instead of symbols, use [`@functions`](@ref)` learner`
+To return actual functions, instead of symbols, use [`@functions`](@ref)  `learner`
 instead.
 
 The returned tuple may include expressions like `:(DecisionTree.print_tree)`, which