From 289193f5cf07a31012c87bfd889e380827d65867 Mon Sep 17 00:00:00 2001 From: "Anthony D. Blaom" Date: Mon, 20 Oct 2025 11:37:49 +1300 Subject: [PATCH 1/9] add default_verbosity to list of public names --- docs/src/list_of_public_names.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/src/list_of_public_names.md b/docs/src/list_of_public_names.md index f0359508..71069abd 100644 --- a/docs/src/list_of_public_names.md +++ b/docs/src/list_of_public_names.md @@ -55,4 +55,6 @@ See [here](@ref proxy_types). - [`@trait`](@ref): for simultaneously declaring multiple traits -- [`@functions`](@ref): for listing functions available for use with a learner +- [`@functions`](@ref): for listing functions available for use with a learner + +- [`LearnAPI.default_verbosity`](@ref): setter/getter for the default verbosity level From 8be6e3ac56c189b7e5e13a6bcc74236895faed32 Mon Sep 17 00:00:00 2001 From: "Anthony D. Blaom" Date: Mon, 20 Oct 2025 14:18:28 +1300 Subject: [PATCH 2/9] doc tweak --- docs/src/anatomy_of_an_implementation.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/src/anatomy_of_an_implementation.md b/docs/src/anatomy_of_an_implementation.md index 3c4bb757..25233a3b 100644 --- a/docs/src/anatomy_of_an_implementation.md +++ b/docs/src/anatomy_of_an_implementation.md @@ -1,5 +1,8 @@ # Anatomy of an Implementation +This section is a tutorial for developers wanting to write implementations of the +LearnAPI.jl interface for their machine learning / statistical algorithms. + LearnAPI.jl supports three core patterns. The default pattern, known as the [`LearnAPI.Descriminative`](@ref) pattern, looks like this: From 25f639a9679d101359c565c8539d5e2e9ac5adad Mon Sep 17 00:00:00 2001 From: "Anthony D. Blaom" Date: Mon, 20 Oct 2025 14:19:21 +1300 Subject: [PATCH 3/9] doc tweak --- docs/src/anatomy_of_an_implementation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/anatomy_of_an_implementation.md b/docs/src/anatomy_of_an_implementation.md index 25233a3b..d9ef3e68 100644 --- a/docs/src/anatomy_of_an_implementation.md +++ b/docs/src/anatomy_of_an_implementation.md @@ -1,7 +1,7 @@ # Anatomy of an Implementation -This section is a tutorial for developers wanting to write implementations of the -LearnAPI.jl interface for their machine learning / statistical algorithms. +This section is a tutorial for developers wanting to implement the LearnAPI.jl interface +for their machine learning / statistical algorithms. LearnAPI.jl supports three core patterns. The default pattern, known as the [`LearnAPI.Descriminative`](@ref) pattern, looks like this: From f6487d248b9e910ccfd6e00d335dd202d6073687 Mon Sep 17 00:00:00 2001 From: "Anthony D. Blaom" Date: Wed, 10 Dec 2025 08:50:15 +1300 Subject: [PATCH 4/9] fix manual --- docs/src/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/reference.md b/docs/src/reference.md index 6cf6285d..281f13bd 100644 --- a/docs/src/reference.md +++ b/docs/src/reference.md @@ -112,8 +112,8 @@ generally requires overloading `Base.==` for the struct. As previewed in [Anatomy of an Implementation](@ref), different `fit`/`predict`/`transform` patterns lead to a division of learners into three distinct -kinds, [`LearnAPI.Descriminative()`](@ref), [`LearnAPI.Generative`](@ref), and -[`LearnAPI.Static`](@ref), which is detailed [here](@ref kinds_of_learner). See also +kinds, [`LearnAPI.Descriminative()`](@ref), [`LearnAPI.Generative()`](@ref), and +[`LearnAPI.Static()`](@ref), which is detailed [here](@ref kinds_of_learner). See also [these workflows](@ref fit_workflows) for concrete examples. From 45e5fae6e074d70f2fe383431b15a4f737264fe7 Mon Sep 17 00:00:00 2001 From: "Anthony D. Blaom" Date: Sat, 20 Dec 2025 13:24:35 +1300 Subject: [PATCH 5/9] fix a typo and add a clarification to docstrings --- src/fit_update.jl | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/fit_update.jl b/src/fit_update.jl index ab7f3ff8..8cbeecca 100644 --- a/src/fit_update.jl +++ b/src/fit_update.jl @@ -141,8 +141,8 @@ model = fit(learner, data) model = update_observations(model, new_data, epochs => 12, learning_rate => 0.1) ``` -When following the call `fit(learner, data)`, the `update` call is semantically -equivalent to retraining ab initio using a concatenation of `data` and `new_data`, +When following the call `fit(learner, data)`, the `update` call is semantically equivalent +to retraining ab initio using an observation-wise concatenation of `data` and `new_data`, *provided there are no hyperparameter replacements* (which rules out the example above). Behaviour is otherwise learner-specific. @@ -178,9 +178,9 @@ Return an updated version of the `model` object returned by a previous [`fit`](@ `update` call given the new features encapsulated in `new_data`. One may additionally specify hyperparameter replacements in the form `:p1 => value1, :p2 => value2, ...`. -When following the call `fit(learner, 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 +When following the call `fit(learner, data)`, the `update_features` call is semantically +equivalent to retraining ab initio using a feature-wise concatenation of `data` and +`new_data`, *provided there are no hyperparameter replacements.* Behaviour is otherwise learner-specific. See also [`fit`](@ref), [`update`](@ref), [`update_features`](@ref). From 8dc86ae8c2b7abb69db76378d262ae92c2fe4836 Mon Sep 17 00:00:00 2001 From: "Anthony Blaom, PhD" Date: Thu, 30 Apr 2026 19:47:16 +1200 Subject: [PATCH 6/9] Update warning about RNG hyperparameter copies Clarify that deep copies of RNG hyperparameters should not be made. --- docs/src/reference.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/src/reference.md b/docs/src/reference.md index 281f13bd..ed495b2a 100644 --- a/docs/src/reference.md +++ b/docs/src/reference.md @@ -104,8 +104,10 @@ generally requires overloading `Base.==` for the struct. !!! important No LearnAPI.jl method is permitted to mutate a learner. In particular, one should make - deep copies of RNG hyperparameters before using them in an implementation of - [`fit`](@ref). + copies of RNG hyperparameters before using them in an implementation of + [`fit`](@ref). (Do not make *deep* copies as this leads to wrong behavior in the case + of `Random.default_rng()`, which not an actual RNG but only a pointer to the task-local + default RNG.) #### Kinds of learner From 37ea2bae7ade3f453a2d3462e71d879be29422a1 Mon Sep 17 00:00:00 2001 From: "Anthony D. Blaom" Date: Thu, 30 Apr 2026 19:50:33 +1200 Subject: [PATCH 7/9] spelling --- docs/src/predict_transform.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/predict_transform.md b/docs/src/predict_transform.md index a7db8251..1f336767 100644 --- a/docs/src/predict_transform.md +++ b/docs/src/predict_transform.md @@ -23,7 +23,7 @@ The above signatures apply in the case that [`LearnAPI.kind_of(learner)`](@ref) returns [`LearnAPI.Generative()`](@ref), as in [density estimation](@ref density_estimation). -## [Typical worklows](@id predict_workflow) +## [Typical workflows](@id predict_workflow) Train some supervised `learner`: From d7028e002f2d01003253c12842d23c5dfad8d6fa Mon Sep 17 00:00:00 2001 From: "Anthony Blaom, PhD" Date: Fri, 1 May 2026 07:48:26 +1200 Subject: [PATCH 8/9] Update reference for transform method description Clarified optional pairing of inverse_transform with transform. --- docs/src/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/reference.md b/docs/src/reference.md index ed495b2a..acc5cd27 100644 --- a/docs/src/reference.md +++ b/docs/src/reference.md @@ -192,7 +192,7 @@ Most learners will also implement [`predict`](@ref) and/or [`transform`](@ref). proxies](@ref proxy) (such as probability density functions) - [`transform`](@ref operations): similar to `predict`, but for arbitrary kinds of output, - and which can be paired with an `inverse_transform` method + and which can be optionally paired with an `inverse_transform` method - [`inverse_transform`](@ref operations): for inverting the output of `transform` ("inverting" broadly understood) From 6367d71ae17b000bafad990ced9d4bb41e56e6ea Mon Sep 17 00:00:00 2001 From: "Anthony Blaom, PhD" Date: Mon, 4 May 2026 08:50:14 +1200 Subject: [PATCH 9/9] Fix markdown reference for fallback value --- src/traits.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/traits.jl b/src/traits.jl index 4fefee7a..848b821f 100644 --- a/src/traits.jl +++ b/src/traits.jl @@ -160,7 +160,7 @@ Return the `fit`/`predict`/`transform` signature pattern used by `learner`. See # New implementations -The fallback value is [`LearnAPI.Descriminative()`]. +The fallback value is [`LearnAPI.Descriminative()`](@ref). """ kind_of(learner) = Descriminative()