minor corrections

Author: ablaom

docs/src/anatomy_of_an_implementation.md

@@ -37,8 +37,8 @@ implementation given later.
     If the `data` object consumed by `fit`, `predict`, or `transform` is not
     not a suitable table¹, array³, tuple of tables and arrays, or some
     other object implementing
-    the [MLUtils.jl](https://juliaml.github.io/MLUtils.jl/dev/) 
-	`getobs`/`numobs` interface,
+    the [MLUtils.jl](https://juliaml.github.io/MLUtils.jl/dev/)
+        `getobs`/`numobs` interface,
     then an implementation must: (i) overload [`obs`](@ref) to articulate how
     provided data can be transformed into a form that does support
     this interface, as illustrated below under
@@ -232,7 +232,7 @@ A macro provides a shortcut, convenient when multiple traits are to be defined:
     Ridge,
     constructor = Ridge,
     kinds_of_proxy=(Point(),),
-    tags = (:regression,),
+    tags = ("regression",),
     functions = (
         :(LearnAPI.fit),
         :(LearnAPI.learner),
@@ -295,6 +295,7 @@ nothing # hide
 learner = Ridge(lambda=0.5)
 @functions learner
 ```
+(Exact output may differ here because of way documentation is generated.)
 
 Training and predicting:
 
@@ -353,7 +354,7 @@ LearnAPI.strip(model::RidgeFitted) =
     Ridge,
     constructor = Ridge,
     kinds_of_proxy=(Point(),),
-    tags = (:regression,),
+    tags = ("regression",),
     functions = (
         :(LearnAPI.fit),
         :(LearnAPI.learner),
@@ -381,10 +382,10 @@ or `predict`, such as the matrix version `A` of `X` in the ridge example.  That
 factor out of `fit` (and also `predict`) a data pre-processing step, `obs`, to expose
 its outcomes. These outcomes become alternative user inputs to `fit`/`predict`.
 
-In the default case, the alternative data representations will implement the MLUtils.jl
-`getobs/numobs` interface for observation subsampling, which is generally all a user or
-meta-algorithm will need, before passing the data on to `fit`/`predict` as you would the
-original data.
+In typical case (where [`LearnAPI.data_interface`](@ref) not overloaded) the alternative data
+representations will implement the MLUtils.jl `getobs/numobs` interface for observation
+subsampling, which is generally all a user or meta-algorithm will need, before passing the
+data on to `fit`/`predict` as you would the original data.
 
 So, instead of the pattern
 
@@ -472,7 +473,7 @@ LearnAPI.fit(learner::Ridge, data; kwargs...) =
 Providing `fit` signatures matching the output of [`obs`](@ref), is the first part of the
 `obs` contract. Since `obs(learner, data)` should evidently support all `data` that
 `fit(learner, data)` supports, we must be able to apply `obs(learner, _)` to it's own
-output (`observations` below). This leads to the additional "no-op" declaration
+output (`observations` below). This leads to the additional declaration
 
 ```@example anatomy2
 LearnAPI.obs(::Ridge, observations::RidgeFitObs) = observations
@@ -529,7 +530,7 @@ LearnAPI.features(::Ridge, observations::RidgeFitObs) = observations.A
 
 Since LearnAPI.jl provides fallbacks for `obs` that simply return the unadulterated data
 argument, overloading `obs` is optional. This is provided data in publicized
-`fit`/`predict` signatures consists only of objects implement the
+`fit`/`predict` signatures already consists only of objects implement the
 [`LearnAPI.RandomAccess`](@ref) interface (most tables¹, arrays³, and tuples thereof).
 
 To opt out of supporting the MLUtils.jl interface altogether, an implementation must

docs/src/common_implementation_patterns.md

@@ -10,7 +10,7 @@ which introduces the main interface objects and terminology.
 
 Although an implementation is defined purely by the methods and traits it implements, many
 implementations fall into one (or more) of the following informally understood patterns or
-"tasks":
+tasks:
 
 - [Regression](@ref): Supervised learners for continuous targets
 

docs/src/fit_update.md

@@ -8,7 +8,7 @@ fit(learner; verbosity=LearnAPI.default_verbosity()) -> static_model
 ```
 
 A "static" algorithm is one that does not generalize to new observations (e.g., some
-clustering algorithms); there is no training data and the algorithm is executed by
+clustering algorithms); there is no training data and heavy lifting is carried out by
 `predict` or `transform` which receive the data. See example below.
 
 

docs/src/patterns/transformers.md

@@ -1,7 +1,5 @@
 # [Transformers](@id transformers)
 
-Check out the following examples:
+Check out the following examples from the TestLearnAPI.jl test suite:
 
-- [Truncated
-  SVD]((https://github.com/JuliaAI/LearnTestAPI.jl/blob/dev/test/patterns/dimension_reduction.jl
-  (from the TestLearnAPI.jl test suite)
+- [Truncated SVD](https://github.com/JuliaAI/LearnTestAPI.jl/blob/dev/test/patterns/dimension_reduction.jl)

docs/src/reference.md

@@ -12,7 +12,7 @@ The LearnAPI.jl specification is predicated on a few basic, informally defined n
 
 ### Data and observations
 
-ML/statistical algorithms are typically applied in conjunction with resampling of
+ML/statistical algorithms are frequently applied in conjunction with resampling of
 *observations*, as in
 [cross-validation](https://en.wikipedia.org/wiki/Cross-validation_(statistics)). In this
 document *data* will always refer to objects encapsulating an ordered sequence of
@@ -35,9 +35,14 @@ see [`obs`](@ref) and [`LearnAPI.data_interface`](@ref) for details.
 
 Besides the data it consumes, a machine learning algorithm's behavior is governed by a
 number of user-specified *hyperparameters*, such as the number of trees in a random
-forest. In LearnAPI.jl, 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 dictionary keys, can be specified as a hyperparameter.
+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
+hyperparameters as far as possible. An exception is the compulsory `verbosity` keyword
+argument of `fit`.
 
 
 ### [Targets and target proxies](@id proxy)
@@ -56,16 +61,16 @@ compared with censored ground truth survival times. And so on ...
 
 #### Definitions
 
-More generally, whenever we have a variable (e.g., a class label) that can, at least in
-principle, be paired with a predicted value, or some predicted "proxy" for that variable
-(such as a class probability), then we call the variable a *target* variable, and the
-predicted output a *target proxy*. In this definition, it is immaterial whether or not the
-target appears in training (the algorithm is supervised) or whether or not predictions
-generalize to new input observations (the algorithm "learns").
+More generally, whenever we have a variable that can, at least in principle, be paired
+with a predicted value, or some predicted "proxy" for that variable (such as a class
+probability), then we call the variable a *target* variable, and the predicted output a
+*target proxy*. In this definition, it is immaterial whether or not the target appears in
+training (the algorithm is supervised) or whether or not predictions generalize to new
+input observations (the algorithm "learns").
 
 LearnAPI.jl provides singleton [target proxy types](@ref proxy_types) for prediction
-dispatch. These are also used to distinguish performance metrics provided by the package
-[StatisticalMeasures.jl](https://juliaai.github.io/StatisticalMeasures.jl/dev/).
+dispatch. These are the same types used to distinguish performance metrics provided by the
+package [StatisticalMeasures.jl](https://juliaai.github.io/StatisticalMeasures.jl/dev/).
 
 
 ### [Learners](@id learners)
@@ -149,9 +154,7 @@ interface.)
 	[`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`
-[here](https://github.com/JuliaAI/LearnAPI.jl/blob/dev/test/traits.jl).
+Most learners will also implement [`predict`](@ref) and/or [`transform`](@ref). 
 
 ### List of methods
 
@@ -187,7 +190,7 @@ minimal (but useless) implementation, see the implementation of `SmallLearner`
 - [Accessor functions](@ref accessor_functions): these include functions like
   `LearnAPI.feature_importances` and `LearnAPI.training_losses`, for extracting, from
   training outcomes, information common to many learners. This includes
-  [`LearnAPI.strip(model)`](@ref) for replacing a learning outcome `model` with a
+  [`LearnAPI.strip(model)`](@ref) for replacing a learning outcome, `model`, with a
   serializable version that can still `predict` or `transform`.
 
 - [Learner traits](@ref traits): methods that promise specific learner behavior or

docs/src/traits.md

@@ -78,8 +78,8 @@ requires:
 
 1. *Finiteness:* The value of a trait is the same for all `learner`s with same value of
    [`LearnAPI.constructor(learner)`](@ref). This typically means trait values do not
-   depend on type parameters! For composite models (`LearnAPI.learners(learner)`
-   non-empty) this requirement is dropped.
+   depend on type parameters! For composite models (non-empty
+   `LearnAPI.learners(learner)`) this requirement is dropped.
 
 2. *Low level deserializability:* It should be possible to evaluate the trait *value* when
    `LearnAPI` and `ScientificTypesBase` are the only imported modules. 

src/traits.jl

@@ -136,7 +136,7 @@ argument) are excluded.
 
 ```
 julia> @functions my_feature_selector
-(fit, LearnAPI.learner, strip, obs, transform)
+(fit, LearnAPI.learner, clone, strip, obs, transform)
 
 ```