Skip to content

Commit 1f0468d

Browse files
authored
Merge pull request #42 from JuliaAI/verbosity
Add a global default verbosity
2 parents c9dbcc7 + b945e73 commit 1f0468d

File tree

7 files changed

+72
-25
lines changed

7 files changed

+72
-25
lines changed

docs/src/anatomy_of_an_implementation.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@ Note that we also include `learner` in the struct, for it must be possible to re
106106
The core implementation of `fit` looks like this:
107107

108108
```@example anatomy
109-
function LearnAPI.fit(learner::Ridge, data; verbosity=1)
109+
function LearnAPI.fit(learner::Ridge, data; verbosity=LearnAPI.default_verbosity())
110110
111111
X, y = data
112112
@@ -397,7 +397,7 @@ methods - one to handle "regular" input, and one to handle the pre-processed dat
397397
(observations) which appears first below:
398398

399399
```@example anatomy2
400-
function LearnAPI.fit(learner::Ridge, observations::RidgeFitObs; verbosity=1)
400+
function LearnAPI.fit(learner::Ridge, observations::RidgeFitObs; verbosity=LearnAPI.default_verbosity())
401401
402402
lambda = learner.lambda
403403

docs/src/fit_update.md

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
### Training
44

55
```julia
6-
fit(learner, data; verbosity=1) -> model
7-
fit(learner; verbosity=1) -> static_model
6+
fit(learner, data; verbosity=LearnAPI.default_verbosity()) -> model
7+
fit(learner; verbosity=LearnAPI.default_verbosity()) -> static_model
88
```
99

1010
A "static" algorithm is one that does not generalize to new observations (e.g., some
@@ -15,8 +15,8 @@ clustering algorithms); there is no training data and the algorithm is executed
1515
### Updating
1616

1717
```
18-
update(model, data; verbosity=1, param1=new_value1, param2=new_value2, ...) -> updated_model
19-
update_observations(model, new_data; verbosity=1, param1=new_value1, ...) -> updated_model
18+
update(model, data; verbosity=..., param1=new_value1, param2=new_value2, ...) -> updated_model
19+
update_observations(model, new_data; verbosity=..., param1=new_value1, ...) -> updated_model
2020
update_features(model, new_data; verbosity=1, param1=new_value1, ...) -> updated_model
2121
```
2222

@@ -101,18 +101,18 @@ See also [Density Estimation](@ref).
101101

102102
Exactly one of the following must be implemented:
103103

104-
| method | fallback |
105-
|:--------------------------------------------|:---------|
106-
| [`fit`](@ref)`(learner, data; verbosity=1)` | none |
107-
| [`fit`](@ref)`(learner; verbosity=1)` | none |
104+
| method | fallback |
105+
|:-----------------------------------------------------------------------|:---------|
106+
| [`fit`](@ref)`(learner, data; verbosity=LearnAPI.default_verbosity())` | none |
107+
| [`fit`](@ref)`(learner; verbosity=LearnAPI.default_verbosity())` | none |
108108

109109
### Updating
110110

111111
| method | fallback | compulsory? |
112112
|:-------------------------------------------------------------------------------------|:---------|-------------|
113-
| [`update`](@ref)`(model, data; verbosity=1, hyperparameter_updates...)` | none | no |
114-
| [`update_observations`](@ref)`(model, data; verbosity=1, hyperparameter_updates...)` | none | no |
115-
| [`update_features`](@ref)`(model, data; verbosity=1, hyperparameter_updates...)` | none | no |
113+
| [`update`](@ref)`(model, data; verbosity=..., hyperparameter_updates...)` | none | no |
114+
| [`update_observations`](@ref)`(model, data; verbosity=..., hyperparameter_updates...)` | none | no |
115+
| [`update_features`](@ref)`(model, data; verbosity=..., hyperparameter_updates...)` | none | no |
116116

117117
There are some contracts governing the behaviour of the update methods, as they relate to
118118
a previous `fit` call. Consult the document strings for details.
@@ -124,4 +124,5 @@ fit
124124
update
125125
update_observations
126126
update_features
127+
LearnAPI.default_verbosity
127128
```

src/LearnAPI.jl

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
module LearnAPI
22

3-
include("tools.jl")
43
include("types.jl")
4+
include("verbosity.jl")
5+
include("tools.jl")
56
include("predict_transform.jl")
67
include("fit_update.jl")
78
include("target_weights_features.jl")

src/fit_update.jl

Lines changed: 22 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# # FIT
22

33
"""
4-
fit(learner, data; verbosity=1)
5-
fit(learner; verbosity=1)
4+
fit(learner, data; verbosity=LearnAPI.default_verbosity())
5+
fit(learner; verbosity=LearnAPI.default_verbosity())
66
77
Execute the machine learning or statistical algorithm with configuration `learner` using
88
the provided training `data`, returning an object, `model`, on which other methods, such
@@ -17,26 +17,27 @@ model = fit(learner, (X, y))
1717
ŷ = predict(model, Xnew)
1818
```
1919
20-
The signature `fit(learner; verbosity=1)` (no `data`) is provided by learners that do not
21-
generalize to new observations (called *static algorithms*). In that case,
20+
The signature `fit(learner; verbosity=...)` (no `data`) is provided by learners that do
21+
not generalize to new observations (called *static algorithms*). In that case,
2222
`transform(model, data)` or `predict(model, ..., data)` carries out the actual algorithm
2323
execution, writing any byproducts of that operation to the mutable object `model` returned
2424
by `fit`.
2525
2626
Use `verbosity=0` for warnings only, and `-1` for silent training.
2727
28-
See also [`predict`](@ref), [`transform`](@ref), [`inverse_transform`](@ref),
29-
[`LearnAPI.functions`](@ref), [`obs`](@ref).
28+
See also [`LearnAPI.default_verbosity`](@ref), [`predict`](@ref), [`transform`](@ref),
29+
[`inverse_transform`](@ref), [`LearnAPI.functions`](@ref), [`obs`](@ref).
3030
3131
# Extended help
3232
3333
# New implementations
3434
3535
Implementation of exactly one of the signatures is compulsory. If `fit(learner;
36-
verbosity=1)` is implemented, then the trait [`LearnAPI.is_static`](@ref) must be
36+
verbosity=...)` is implemented, then the trait [`LearnAPI.is_static`](@ref) must be
3737
overloaded to return `true`.
3838
39-
The signature must include `verbosity`.
39+
The signature must include `verbosity` with [`LearnAPI.default_verbosity()`](@ref) as
40+
default.
4041
4142
If `data` encapsulates a *target* variable, as defined in LearnAPI.jl documentation, then
4243
[`LearnAPI.target(data)`](@ref) must be overloaded to return it. If [`predict`](@ref) or
@@ -59,7 +60,7 @@ function fit end
5960
# # UPDATE AND COUSINS
6061

6162
"""
62-
update(model, data; verbosity=1, hyperparam_replacements...)
63+
update(model, data; verbosity=LearnAPI.default_verbosity(), hyperparam_replacements...)
6364
6465
Return an updated version of the `model` object returned by a previous [`fit`](@ref) or
6566
`update` call, but with the specified hyperparameter replacements, in the form `p1=value1,
@@ -98,7 +99,12 @@ See also [`LearnAPI.clone`](@ref)
9899
function update end
99100

100101
"""
101-
update_observations(model, new_data; verbosity=1, parameter_replacements...)
102+
update_observations(
103+
model,
104+
new_data;
105+
parameter_replacements...,
106+
verbosity=LearnAPI.default_verbosity(),
107+
)
102108
103109
Return an updated version of the `model` object returned by a previous [`fit`](@ref) or
104110
`update` call given the new observations present in `new_data`. One may additionally
@@ -134,7 +140,12 @@ See also [`LearnAPI.clone`](@ref).
134140
function update_observations end
135141

136142
"""
137-
update_features(model, new_data; verbosity=1, parameter_replacements...)
143+
update_features(
144+
model,
145+
new_data;
146+
parameter_replacements...,
147+
verbosity=LearnAPI.default_verbosity(),
148+
)
138149
139150
Return an updated version of the `model` object returned by a previous [`fit`](@ref) or
140151
`update` call given the new features encapsulated in `new_data`. One may additionally

src/verbosity.jl

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
const DEFAULT_VERBOSITY = Ref(1)
2+
3+
"""
4+
LearnAPI.default_verbosity()
5+
LearnAPI.default_verbosity(level::Int)
6+
7+
Respectively return, or set, the default `verbosity` level for LearnAPI.jl methods that
8+
support it, which includes [`fit`](@ref), [`update`](@ref),
9+
[`update_observations`](@ref), and [`update_features`](@ref). The effect in a top-level
10+
call is generally:
11+
12+
13+
14+
| `level` | behaviour |
15+
|:--------|:----------------------------------|
16+
| 1 | informational |
17+
| 0 | warnings only |
18+
| -1 | silent |
19+
20+
21+
Methods consuming `verbosity` generally call other verbosity-supporting methods
22+
at one level lower, so increasing `verbosity` beyond `1` may be useful.
23+
24+
"""
25+
default_verbosity() = DEFAULT_VERBOSITY[]
26+
default_verbosity(level) = (DEFAULT_VERBOSITY[] = level)

test/runtests.jl

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ using Test
22

33
test_files = [
44
"tools.jl",
5+
"verbosity.jl",
56
"traits.jl",
67
"clone.jl",
78
"predict_transform.jl",

test/verbosity.jl

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
using Test
2+
3+
@test LearnAPI.default_verbosity() ==1
4+
LearnAPI.default_verbosity(42)
5+
@test LearnAPI.default_verbosity() == 42
6+
7+
true

0 commit comments

Comments
 (0)