adjust docstrings/docs to reflect verbosity change

Author: ablaom

docs/src/fit_update.md

@@ -4,7 +4,7 @@
 ### Training
 
 ```julia
-fit(learner, data; verbosity=1) -> model
+fit(learner, data; verbosity=...) -> model
 ```
 
 This is the typical `fit` pattern, applying in the case that [`LearnAPI.kind_of(learner)`](@ref)
@@ -25,9 +25,9 @@ Examples appear below.
 ### Updating
 
 ```
-update(model, data; verbosity=..., :param1=new_value1, :param2=new_value2, ...) -> updated_model
-update_observations(model, new_data; verbosity=..., :param1=new_value1, ...) -> updated_model
-update_features(model, new_data; verbosity=..., :param1=new_value1, ...) -> updated_model
+update(model, data, :param1=>new_value1, :param2=>new_value2, ...; verbosity=...) -> updated_model
+update_observations(model, new_data, :param1=>new_value1, ...; verbosity=...) -> updated_model
+update_features(model, new_data, :param1=>new_value1, ...; verbosity=...) -> updated_model
 ```
 
 [`LearnAPI.Static()`](@ref) learners cannot be updated. 
@@ -50,7 +50,7 @@ ŷ = predict(model, Distribution(), Xnew)
 LearnAPI.feature_importances(model)
 
 # Add 50 iterations and predict again:
-model = update(model; n=150)
+model = update(model, n => 150)
 predict(model, Distribution(), X)
 ```
 
@@ -123,21 +123,21 @@ See also [Density Estimation](@ref).
 
 Exactly one of the following must be implemented:
 
-| method                                      | fallback |
-|:--------------------------------------------|:---------|
-| [`fit`](@ref)`(learner, data; verbosity=1)` | none     |
-| [`fit`](@ref)`(learner; verbosity=1)`       | none     |
+| method                                                                 | fallback |
+|:-----------------------------------------------------------------------|:---------|
+| [`fit`](@ref)`(learner, data; verbosity=LearnAPI.default_verbosity())` | none     |
+| [`fit`](@ref)`(learner; verbosity=LearnAPI.default_verbosity())`       | none     |
 
 ### Updating
 
-| method                                                                               | fallback | compulsory? |
-|:-------------------------------------------------------------------------------------|:---------|-------------|
-| [`update`](@ref)`(model, data; verbosity=1, hyperparameter_updates...)`              | none     | no          |
-| [`update_observations`](@ref)`(model, new_data; verbosity=1, hyperparameter_updates...)` | none     | no          |
-| [`update_features`](@ref)`(model, new_data; verbosity=1, hyperparameter_updates...)`     | none     | no          |
+| method                                                                                     | fallback | compulsory? |
+|:-------------------------------------------------------------------------------------------|:---------|-------------|
+| [`update`](@ref)`(model, data, hyperparameter_updates...; verbosity=...)`                  | none     | no          |
+| [`update_observations`](@ref)`(model, new_data, hyperparameter_updates...; verbosity=...)` | none     | no          |
+| [`update_features`](@ref)`(model, new_data, hyperparameter_updates...; verbosity=...)`     | none     | no          |
 
-There are some contracts governing the behaviour of the update methods, as they relate to
-a previous `fit` call. Consult the document strings for details.
+There are contracts governing the behaviour of the update methods, as they relate to a
+previous `fit` call. Consult the document strings for details.
 
 ## Reference
 

src/fit_update.jl

@@ -1,8 +1,8 @@
 # # FIT
 
 """
-    fit(learner, data; verbosity=1)
-    fit(learner; verbosity=1)
+    fit(learner, data; verbosity=LearnAPI.default_verbosity())
+    fit(learner; verbosity=LearnAPI.default_verbosity()))
 
 In the case of the first signature, execute the machine learning or statistical algorithm
 with configuration `learner` using the provided training `data`, returning an object,
@@ -51,7 +51,8 @@ Implementation of exactly one of the signatures is compulsory. Unless implementi
 [`LearnAPI.Descriminative()`](@ref) `fit`/`predict`/`transform` pattern,
 [`LearnAPI.kind_of(learner)`](@ref) will need to be suitably overloaded.
 
-The `fit` signature must include `verbosity` with `1` as default.
+The `fit` signature must include the keyword argument `verbosity` with
+`LearnAPI.default_verbosity()` as default.
 
 The LearnAPI.jl specification has nothing to say regarding `fit` signatures with more than
 two arguments. For convenience, for example, an implementation is free to implement a
@@ -74,7 +75,7 @@ function fit end
 # # UPDATE AND COUSINS
 
 """
-    update(model, data, param_replacements...; verbosity=1)
+    update(model, data, param_replacements...; verbosity=LearnAPI.default_verbosity())
 
 Return an updated version of the `model` object returned by a previous [`fit`](@ref) or
 `update` call, but with the specified hyperparameter replacements, in the form `:p1 =>
@@ -104,9 +105,10 @@ See also [`fit`](@ref), [`update_observations`](@ref), [`update_features`](@ref)
 
 # New implementations
 
-Implementation is optional. The signature must include `verbosity`. It should be true that
-`LearnAPI.learner(newmodel) == newlearner`, where `newmodel` is the return value and
-`newlearner = LearnAPI.clone(learner, replacements...)`.
+Implementation is optional. The signature must include the `verbosity` keyword
+argument. It should be true that `LearnAPI.learner(newmodel) == newlearner`, where
+`newmodel` is the return value and `newlearner = LearnAPI.clone(learner,
+replacements...)`.
 
 Cannot be implemented if [`LearnAPI.kind_of(learner)`](@ref)` == `LearnAPI.Static()`.
 
@@ -118,10 +120,15 @@ See also [`LearnAPI.clone`](@ref)
 function update end
 
 """
-    update_observations(model, new_data, param_replacements...; verbosity=1)
+    update_observations(
+       model,
+       new_data,
+       param_replacements...;
+       verbosity=LearnAPI.default_verbosity(),
+    )
 
 Return an updated version of the `model` object returned by a previous [`fit`](@ref) or
-`update` call given the new observations present in `new_data`. One may additionally
+`update` call, given the new observations present in `new_data`. One may additionally
 specify hyperparameter replacements in the form `:p1 => value1, :p2 => value2, ...`.
 
 ```julia-repl
@@ -145,9 +152,10 @@ See also [`fit`](@ref), [`update`](@ref), [`update_features`](@ref).
 
 # New implementations
 
-Implementation is optional. The signature must include `verbosity`. It should be true that
-`LearnAPI.learner(newmodel) == newlearner`, where `newmodel` is the return value and
-`newlearner = LearnAPI.clone(learner, replacements...)`.
+Implementation is optional. The signature must include the `verbosity` keyword
+argument. It should be true that `LearnAPI.learner(newmodel) == newlearner`, where
+`newmodel` is the return value and `newlearner = LearnAPI.clone(learner,
+replacements...)`.
 
 Cannot be implemented if [`LearnAPI.kind_of(learner)`](@ref)` == `LearnAPI.Static()`.
 
@@ -159,7 +167,11 @@ See also [`LearnAPI.clone`](@ref).
 function update_observations end
 
 """
-    update_features(model, new_data, param_replacements...; verbosity=1)
+    update_features(
+        model,
+        new_data,
+        param_replacements,...;
+        verbosity=LearnAPI.default_verbosity(),
     )
 
 Return an updated version of the `model` object returned by a previous [`fit`](@ref) or
@@ -177,9 +189,10 @@ See also [`fit`](@ref), [`update`](@ref), [`update_features`](@ref).
 
 # New implementations
 
-Implementation is optional. The signature must include `verbosity`. It should be true that
-`LearnAPI.learner(newmodel) == newlearner`, where `newmodel` is the return value and
-`newlearner = LearnAPI.clone(learner, replacements...)`.
+Implementation is optional. The signature must include the `verbosity` keyword
+argument. It should be true that `LearnAPI.learner(newmodel) == newlearner`, where
+`newmodel` is the return value and `newlearner = LearnAPI.clone(learner,
+replacements...)`.
 
 Cannot be implemented if [`LearnAPI.kind_of(learner)`](@ref)` == `LearnAPI.Static()`.
 

src/preferences.jl

@@ -8,11 +8,13 @@ INFO_VERBOSITY_WILL_BE(verbosity) =
 """
     LearnAPI.default_verbosity()
 
-Return the default verbosity for training LearnAPI learners.
+Return the default LearnAPI verbosity level.
 
 The value is determined at compile time by a Preferences.jl-style preference, with key
 "verbosity".
 
+If `verbosity=0`, only warnings are displayed; `verbosity=-1` suppresses warnings.
+
 """
 default_verbosity() = VERBOSITY