diff --git a/.github/codecov.yml b/.github/codecov.yml index 914690d9..c62bedf5 100644 --- a/.github/codecov.yml +++ b/.github/codecov.yml @@ -6,4 +6,4 @@ coverage: removed_code_behavior: fully_covered_patch patch: default: - target: 80%coverage: + target: 80 diff --git a/docs/src/fit_update.md b/docs/src/fit_update.md index 1a87fc9d..a0486bdb 100644 --- a/docs/src/fit_update.md +++ b/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: diff --git a/src/fit_update.jl b/src/fit_update.jl index d91bc4e9..96407651 100644 --- a/src/fit_update.jl +++ b/src/fit_update.jl @@ -9,11 +9,6 @@ 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 @@ -21,6 +16,12 @@ 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 diff --git a/src/predict_transform.jl b/src/predict_transform.jl index 9e773192..726f263f 100644 --- a/src/predict_transform.jl +++ b/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 diff --git a/test/accessor_functions.jl b/test/accessor_functions.jl index f22e73bb..0ee61e55 100644 --- a/test/accessor_functions.jl +++ b/test/accessor_functions.jl @@ -1,4 +1,6 @@ using Test using LearnAPI -@test strip("junk") == "junk" +@test LearnAPI.strip("junk") == "junk" + +true