Merge pull request #36 from JuliaAI/tweaks

doc and test tweaks

Author: ablaom

.github/codecov.yml

@@ -6,4 +6,4 @@ coverage:
         removed_code_behavior: fully_covered_patch
     patch:
       default:
-        target: 80%coverage:
+        target: 80

docs/src/fit_update.md

@@ -45,7 +45,7 @@ predict(model, Distribution(), X)
 
 See also [Classification](@ref) and [Regression](@ref).
 
-### Tranformers
+### Transformers
 
 A dimension-reducing transformer, `algorithm`  might be used in this way:
 

src/fit_update.jl

@@ -9,18 +9,19 @@ returning an object, `model`, on which other methods, such as [`predict`](@ref)
 [`transform`](@ref), can be dispatched.  [`LearnAPI.functions(algorithm)`](@ref) returns a
 list of methods that can be applied to either `algorithm` or `model`.
 
-The second signature is provided by algorithms that do not generalize to new observations
-(called *static algorithms*). In that case, `transform(model, data)` or `predict(model,
-..., data)` carries out the actual algorithm execution, writing any byproducts of that
-operation to the mutable object `model` returned by `fit`.
-
 For example, a supervised classifier might have a workflow like this:
 
 ```julia
 model = fit(algorithm, (X, y))
 ŷ = predict(model, Xnew)
 ```
 
+The second signature, with `data` omitted, is provided by algorithms that do not
+generalize to new observations (called *static algorithms*). In that case,
+`transform(model, data)` or `predict(model, ..., data)` carries out the actual algorithm
+execution, writing any byproducts of that operation to the mutable object `model` returned
+by `fit`.
+
 Use `verbosity=0` for warnings only, and `-1` for silent training.
 
 See also [`predict`](@ref), [`transform`](@ref), [`inverse_transform`](@ref),
@@ -41,7 +42,7 @@ If `data` encapsulates a *target* variable, as defined in LearnAPI.jl documentat
 [`transform`](@ref) are implemented and consume data, then
 [`LearnAPI.features(data)`](@ref) must return something that can be passed as data to
 these methods. A fallback returns `first(data)` if `data` is a tuple, and `data`
-otherwise`.
+otherwise.
 
 The LearnAPI.jl specification has nothing to say regarding `fit` signatures with more than
 two arguments. For convenience, for example, an algorithm is free to implement a slurping
@@ -63,16 +64,6 @@ Return an updated version of the `model` object returned by a previous [`fit`](@
 `update` call, but with the specified hyperparameter replacements, in the form `p1=value1,
 p2=value2, ...`.
 
-Provided that `data` is identical with the data presented in a preceding `fit` call *and*
-there is at most one hyperparameter replacement, as in the example below, execution is
-semantically equivalent to the call `fit(algorithm, data)`, where `algorithm` is
-`LearnAPI.algorithm(model)` with the specified replacements. In some cases (typically,
-when changing an iteration parameter) there may be a performance benefit to using `update`
-instead of retraining ab initio.
-
-If `data` differs from that in the preceding `fit` or `update` call, or there is more than
-one hyperparameter replacement, then behaviour is algorithm-specific.
-
 ```julia
 algorithm = MyForest(ntrees=100)
 
@@ -83,6 +74,16 @@ model = fit(algorithm, data)
 model = update(model, data; ntrees=150)
 ```
 
+Provided that `data` is identical with the data presented in a preceding `fit` call *and*
+there is at most one hyperparameter replacement, as in the above example, execution is
+semantically equivalent to the call `fit(algorithm, data)`, where `algorithm` is
+`LearnAPI.algorithm(model)` with the specified replacements. In some cases (typically,
+when changing an iteration parameter) there may be a performance benefit to using `update`
+instead of retraining ab initio.
+
+If `data` differs from that in the preceding `fit` or `update` call, or there is more than
+one hyperparameter replacement, then behaviour is algorithm-specific.
+
 See also [`fit`](@ref), [`update_observations`](@ref), [`update_features`](@ref).
 
 # New implementations
@@ -102,11 +103,6 @@ Return an updated version of the `model` object returned by a previous [`fit`](@
 `update` call given the new observations present in `new_data`. One may additionally
 specify hyperparameter replacements in the form `p1=value1, p2=value2, ...`.
 
-When following the call `fit(algorithm, data)`, the `update` call is semantically
-equivalent to retraining ab initio using a concatenation of `data` and `new_data`,
-*provided there are no hyperparameter replacements.* Behaviour is otherwise
-algorithm-specific.
-
 ```julia-repl
 algorithm = MyNeuralNetwork(epochs=10, learning_rate=0.01)
 
@@ -117,6 +113,11 @@ model = fit(algorithm, data)
 model = update_observations(model, new_data; epochs=2, learning_rate=0.1)
 ```
 
+When following the call `fit(algorithm, data)`, the `update` call is semantically
+equivalent to retraining ab initio using a concatenation of `data` and `new_data`,
+*provided there are no hyperparameter replacements* (which rules out the example
+above). Behaviour is otherwise algorithm-specific.
+
 See also [`fit`](@ref), [`update`](@ref), [`update_features`](@ref).
 
 # Extended help

src/predict_transform.jl

@@ -64,6 +64,11 @@ and probability density/mass functions if `kind_of_proxy = Distribution()`. List
 options with [`LearnAPI.kinds_of_proxy(algorithm)`](@ref), where `algorithm =
 LearnAPI.algorithm(model)`.
 
+```julia
+model = fit(algorithm, (X, y))
+predict(model, Point(), Xnew)
+```
+
 The shortcut `predict(model, data)` calls the first method with an algorithm-specific
 `kind_of_proxy`, namely the first element of [`LearnAPI.kinds_of_proxy(algorithm)`](@ref),
 which lists all supported target proxies.
@@ -73,16 +78,6 @@ The argument `model` is anything returned by a call of the form `fit(algorithm,
 If `LearnAPI.features(LearnAPI.algorithm(model)) == nothing`, then argument `data` is
 omitted in both signatures. An example is density estimators.
 
-# Example
-
-In the following, `algorithm` is some supervised learning algorithm with
-training features `X`, training target `y`, and test features `Xnew`:
-
-```julia
-model = fit(algorithm, (X, y)) # or `fit(algorithm, X, y)`
-predict(model, Point(), Xnew)
-```
-
 See also [`fit`](@ref), [`transform`](@ref), [`inverse_transform`](@ref).
 
 # Extended help

test/accessor_functions.jl

@@ -1,4 +1,6 @@
 using Test
 using LearnAPI
 
-@test strip("junk") == "junk"
+@test LearnAPI.strip("junk") == "junk"
+
+true