doc tweaks

Author: ablaom

docs/src/index.md

@@ -9,12 +9,13 @@ A base Julia interface for machine learning and statistics </span>
 <br>
 ```
 
-LearnAPI.jl is a lightweight, functional-style interface, providing a
-collection of [methods](@ref Methods), such as `fit` and `predict`, to be implemented by
-algorithms from machine learning and statistics. Through such implementations, these
-algorithms buy into functionality, such as hyperparameter optimization and model
-composition, as provided by ML/statistics toolboxes and other packages. LearnAPI.jl also
-provides a number of Julia [traits](@ref traits) for promising specific behavior.
+LearnAPI.jl is a lightweight, functional-style interface, providing a collection of
+[methods](@ref Methods), such as `fit` and `predict`, to be implemented by algorithms from
+machine learning and statistics. Its careful design ensures algorithms implementing
+LearnAPI.jl can buy into functionality, such as external performance estimates,
+hyperparameter optimization and model composition, provided by ML/statistics toolboxes and
+other packages. LearnAPI.jl includes a number of Julia [traits](@ref traits) for promising
+specific behavior.
 
 LearnAPI.jl's only dependency is the standard library `InteractiveUtils`. 
 
@@ -91,6 +92,18 @@ then overloading `obs` is completely optional. Plain iteration interfaces, with
 knowledge of the number of observations, can also be specified (to support, e.g., data
 loaders reading images from disk).
 
+## Hooks for adding functionality
+
+A key to enabling toolboxes to enhance LearnAPI.jl algorithm functionality is the
+implementation of two key additional methods, beyond the usual `fit` and
+`predict`/`transform`. Given any training `data` consumed by `fit` (such as `data = (X,
+y)` in the example above) [`LearnAPI.features(algorithm, data)`](@ref input) tells us what
+part of `data` comprises *features*, which is something that can be passsed onto to
+`predict` or `transform` (`X` in the example) while [`LearnAPI.target(algorithm,
+data)`](@ref), if implemented, tells us what part comprises the target (`y` in the
+example). By explicitly requiring such methods, we free algorithms to consume data in
+multiple forms, including optimised, algorithm-specific forms, as described above.
+
 ## Learning more
 
 - [Anatomy of an Implementation](@ref): informal introduction to the main actors in a new

docs/src/obs.md

@@ -77,10 +77,11 @@ end
 
 ## Implementation guide
 
-| method                                  | compulsory? | fallback       |
-|:----------------------------------------|:-----------:|:--------------:|
-| [`obs(algorithm_or_model, data)`](@ref) | depends     | returns `data` |
-|                                         |             |                |
+| method                         | comment                             | compulsory?   | fallback       |
+|:-------------------------------|:------------------------------------|:-------------:|:---------------|
+| [`obs(algorithm, data)`](@ref) | here `data` is `fit`-consumable     | not typically | returns `data` |
+| [`obs(model, data)`](@ref)     | here `data` is `predict`-consumable | not typically | returns `data` |
+
 
 A sample implementation is given in [Providing an advanced data interface](@ref). 
 

docs/src/predict_transform.md

@@ -72,6 +72,10 @@ instead, which does not dispatch on [`LearnAPI.KindOfProxy`](@ref), but can be o
 paired with an implementation of [`inverse_transform`](@ref), for returning (approximate)
 right inverses to `transform`.
 
+Of course, the one algorithm can implement both a `predict` and `transform` method. For
+example a K-means clustering algorithm can `predict` labels and `transform` to reduce
+dimension using distances from the cluster centres.
+
 
 ### [One-liners combining fit and transform/predict](@id one_liners)
 

src/obs.jl

@@ -8,8 +8,8 @@ Return an algorithm-specific representation of `data`, suitable for passing to `
 algorithm, `algorithm`.
 
 The returned object is guaranteed to implement observation access as indicated by
-[`LearnAPI.data_interface(algorithm)`](@ref) (typically
-[`LearnAPI.RandomAccess()`](@ref)).
+[`LearnAPI.data_interface(algorithm)`](@ref), typically
+[`LearnAPI.RandomAccess()`](@ref).
 
 Calling `fit`/`predict`/`transform` on the returned objects may have performance
 advantages over calling directly on `data` in some contexts. And resampling the returned