replace minimize -> LearnAPI.strip

oops

oops

tweak

Author: ablaom

README.md

@@ -18,7 +18,7 @@ Configure a learning algorithm, and inspect available functionality:
 ```julia
 julia> algorithm = Ridge(lambda=0.1)
 julia> LearnAPI.functions(algorithm)
-(:(LearnAPI.fit), :(LearnAPI.algorithm), :(LearnAPI.minimize), :(LearnAPI.obs), 
+(:(LearnAPI.fit), :(LearnAPI.algorithm), :(LearnAPI.strip), :(LearnAPI.obs), 
 :(LearnAPI.features), :(LearnAPI.target), :(LearnAPI.predict), :(LearnAPI.coefficients))
 ```
 

docs/make.jl

@@ -18,7 +18,6 @@ makedocs(
             "fit/update" => "fit_update.md",
             "predict/transform" => "predict_transform.md",
             "Kinds of Target Proxy" => "kinds_of_target_proxy.md",
-            "minimize" => "minimize.md",
             "target/weights/features" => "target_weights_features.md",
             "obs" => "obs.md",
             "Accessor Functions" => "accessor_functions.md",

docs/src/accessor_functions.md

@@ -1,10 +1,12 @@
 # [Accessor Functions](@id accessor_functions)
 
 The sole argument of an accessor function is the output, `model`, of
-[`fit`](@ref). Algorithms are free to implement any number of these, or none of them.
+[`fit`](@ref). Algorithms are free to implement any number of these, or none of them. Only
+`LearnAPI.strip` has a fallback, namely the identity.
 
 - [`LearnAPI.algorithm(model)`](@ref)
 - [`LearnAPI.extras(model)`](@ref)
+- [`LearnAPI.strip(model)`](@ref)
 - [`LearnAPI.coefficients(model)`](@ref)
 - [`LearnAPI.intercept(model)`](@ref)
 - [`LearnAPI.tree(model)`](@ref)
@@ -31,6 +33,7 @@ optional, any implemented accessor functions must be added to the list returned
 ```@docs
 LearnAPI.algorithm
 LearnAPI.extras
+LearnAPI.strip
 LearnAPI.coefficients
 LearnAPI.intercept
 LearnAPI.tree

docs/src/anatomy_of_an_implementation.md

@@ -183,15 +183,15 @@ nothing #hide
 
 ## Tearing a model down for serialization
 
-The `minimize` method falls back to the identity. Here, for the sake of illustration, we
+The `LearnAPI.strip` method falls back to the identity. Here, for the sake of illustration, we
 overload it to dump the named version of the coefficients:
 
 ```@example anatomy
-LearnAPI.minimize(model::RidgeFitted) =
+LearnAPI.strip(model::RidgeFitted) =
     RidgeFitted(model.algorithm, model.coefficients, nothing)
 ```
 
-Crucially, we can still use `LearnAPI.minimize(model)` in place of `model` to make new
+Crucially, we can still use `LearnAPI.strip(model)` in place of `model` to make new
 predictions.
 
 
@@ -220,7 +220,7 @@ A macro provides a shortcut, convenient when multiple traits are to be defined:
     functions = (
         :(LearnAPI.fit),
         :(LearnAPI.algorithm),
-        :(LearnAPI.minimize),
+        :(LearnAPI.strip),
         :(LearnAPI.obs),
         :(LearnAPI.features),
         :(LearnAPI.target),
@@ -285,7 +285,7 @@ Serialization/deserialization:
 
 ```@example anatomy
 using Serialization
-small_model = minimize(model)
+small_model = LearnAPI.strip(model)
 filename = tempname()
 serialize(filename, small_model)
 ```
@@ -316,7 +316,7 @@ end
 
 LearnAPI.algorithm(model::RidgeFitted) = model.algorithm
 LearnAPI.coefficients(model::RidgeFitted) = model.named_coefficients
-LearnAPI.minimize(model::RidgeFitted) =
+LearnAPI.strip(model::RidgeFitted) =
     RidgeFitted(model.algorithm, model.coefficients, nothing)
 
 @trait(
@@ -327,7 +327,7 @@ LearnAPI.minimize(model::RidgeFitted) =
     functions = (
         :(LearnAPI.fit),
         :(LearnAPI.algorithm),
-        :(LearnAPI.minimize),
+        :(LearnAPI.strip),
         :(LearnAPI.obs),
         :(LearnAPI.features),
         :(LearnAPI.target),

docs/src/index.md

@@ -60,7 +60,7 @@ predict(model, Distribution(), Xnew)
 LearnAPI.feature_importances(model)
 
 # Slim down and otherwise prepare model for serialization:
-small_model = minimize(model)
+small_model = LearnAPI.strip(model)
 serialize("my_random_forest.jls", small_model)
 
 # Recover saved model and algorithm configuration:

docs/src/minimize.md

@@ -138,9 +138,9 @@ for each.
 
 !!! note "Compulsory methods"
 
-    All new algorithm types must implement [`fit`](@ref),
-    [`LearnAPI.algorithm`](@ref algorithm_minimize), [`LearnAPI.constructor`](@ref) and
-    [`LearnAPI.functions`](@ref).
+	All new algorithm types must implement [`fit`](@ref),
+	[`LearnAPI.algorithm`](@ref), [`LearnAPI.constructor`](@ref) and
+	[`LearnAPI.functions`](@ref).
 
 Most algorithms will also implement [`predict`](@ref) and/or [`transform`](@ref). For a
 bare minimum implementation, see the implementation of `SmallAlgorithm`
@@ -152,10 +152,10 @@ bare minimum implementation, see the implementation of `SmallAlgorithm`
   for non-generalizing algorithms (see [here](@ref static_algorithms) and [Static
   Algorithms](@ref)), for wrapping `algorithm` in a mutable struct that can be mutated by
   `predict`/`transform` to record byproducts of those operations.
-  
+
 - [`update`](@ref fit): for updating learning outcomes after hyperparameter changes, such
   as increasing an iteration parameter.
-  
+
 - [`update_observations`](@ref fit), [`update_features`](@ref fit): update learning
   outcomes by presenting additional training data.
 
@@ -168,9 +168,6 @@ bare minimum implementation, see the implementation of `SmallAlgorithm`
 - [`inverse_transform`](@ref operations): for inverting the output of
   `transform` ("inverting" broadly understood)
 
-- [`minimize`](@ref algorithm_minimize): for stripping the `model` output by `fit` of
-  inessential content, for purposes of serialization.
-
 - [`LearnAPI.target`](@ref input), [`LearnAPI.weights`](@ref input),
   [`LearnAPI.features`](@ref): for extracting relevant parts of training data, where
   defined.
@@ -181,8 +178,10 @@ bare minimum implementation, see the implementation of `SmallAlgorithm`
   [`LearnAPI.data_interface(algorithm)`](@ref).
 
 - [Accessor functions](@ref accessor_functions): these include functions like
-  `feature_importances` and `training_losses`, for extracting, from training outcomes,
-  information common to many algorithms.
+  `LearnAPI.feature_importances` and `LearnAPI.training_losses`, for extracting, from
+  training outcomes, information common to many algorithms. This includes
+  [`LearnAPI.strip(model)`](@ref) for replacing a learning outcome `model` with a
+  serializable version that can still `predict` or `transform`.
 
 - [Algorithm traits](@ref traits): methods that promise specific algorithm behavior or
   record general information about the algorithm. Only [`LearnAPI.constructor`](@ref) and

docs/src/reference.md

@@ -16,7 +16,7 @@ In the examples column of the table below, `Continuous` is a name owned the pack
 | trait                                                      | return value                                                                                                             | fallback value                                        | example                                                    |
 |:-----------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------|:-----------------------------------------------------------|
 | [`LearnAPI.constructor`](@ref)`(algorithm)`                | constructor for generating new or modified versions of `algorithm`                                                       | (no fallback)                                         | `RidgeRegressor`                                           |
-| [`LearnAPI.functions`](@ref)`(algorithm)`                  | functions you can apply to `algorithm` or associated model (traits excluded)                                             | `()`                                                  | `(:fit, :predict, :minimize, :(LearnAPI.algorithm), :obs)` |
+| [`LearnAPI.functions`](@ref)`(algorithm)`                  | functions you can apply to `algorithm` or associated model (traits excluded)                                             | `()`                                                  | `(:fit, :predict, :LearnAPI.strip, :(LearnAPI.algorithm), :obs)` |
 | [`LearnAPI.kinds_of_proxy`](@ref)`(algorithm)`             | instances `kind` of `KindOfProxy` for which an implementation of `LearnAPI.predict(algorithm, kind, ...)` is guaranteed. | `()`                                                  | `(Distribution(), Interval())`                             |
 | [`LearnAPI.tags`](@ref)`(algorithm)`                       | lists one or more suggestive algorithm tags from `LearnAPI.tags()`                                                       | `()`                                                  | (:regression, :probabilistic)                              |
 | [`LearnAPI.is_pure_julia`](@ref)`(algorithm)`              | `true` if implementation is 100% Julia code                                                                              | `false`                                               | `true`                                                     |

docs/src/traits.md

@@ -6,7 +6,6 @@ include("tools.jl")
 include("types.jl")
 include("predict_transform.jl")
 include("fit_update.jl")
-include("minimize.jl")
 include("target_weights_features.jl")
 include("obs.jl")
 include("accessor_functions.jl")
@@ -15,7 +14,7 @@ include("clone.jl")
 
 export @trait
 export fit, update, update_observations, update_features
-export predict, transform, inverse_transform, minimize, obs
+export predict, transform, inverse_transform, obs
 
 for name in Symbol.(CONCRETE_TARGET_PROXY_TYPES_SYMBOLS)
     @eval export $name

src/LearnAPI.jl

@@ -16,15 +16,15 @@ const DOC_STATIC =
 
 """
     LearnAPI.algorithm(model)
-    LearnAPI.algorithm(minimized_model)
+    LearnAPI.algorithm(LearnAPI.stripd_model)
 
-Recover the algorithm used to train `model` or the output of [`minimize(model)`](@ref).
+Recover the algorithm used to train `model` or the output of [`LearnAPI.strip(model)`](@ref).
 
 In other words, if `model = fit(algorithm, data...)`, for some `algorithm` and `data`,
 then
 
 ```julia
-LearnAPI.algorithm(model) == algorithm == LearnAPI.algorithm(minimize(model))
+LearnAPI.algorithm(model) == algorithm == LearnAPI.algorithm(LearnAPI.strip(model))
 ```
 is `true`.
 
@@ -36,6 +36,61 @@ only contract. $(DOC_IMPLEMENTED_METHODS(":(LearnAPI.algorithm)"))
 """
 function algorithm end
 
+"""
+    LearnAPI.strip(model; options...)
+
+Return a version of `model` that will generally have a smaller memory allocation than
+`model`, suitable for serialization. Here `model` is any object returned by
+[`fit`](@ref). Accessor functions that can be called on `model` may not work on
+`LearnAPI.strip(model)`, but [`predict`](@ref), [`transform`](@ref) and
+[`inverse_transform`](@ref) will work, if implemented. Check
+`LearnAPI.functions(LearnAPI.algorithm(model))` to view see what the original `model`
+implements.
+
+Specific algorithms may provide keyword `options` to control how much of the original
+functionality is preserved by `LearnAPI.strip`.
+
+# Typical workflow
+
+```julia
+model = fit(algorithm, (X, y)) # or `fit(algorithm, X, y)`
+ŷ = predict(model, Point(), Xnew)
+
+small_model = LearnAPI.strip(model)
+serialize("my_model.jls", small_model)
+
+recovered_model = deserialize("my_random_forest.jls")
+@assert predict(recovered_model, Point(), Xnew) == ŷ
+```
+
+# Extended help
+
+# New implementations
+
+Overloading `LearnAPI.strip` for new algorithms is optional. The fallback is the
+identity.
+
+New implementations must enforce the following identities, whenever the right-hand side is
+defined:
+
+```julia
+predict(LearnAPI.strip(model; options...), args...; kwargs...) ==
+    predict(model, args...; kwargs...)
+transform(LearnAPI.strip(model; options...), args...; kwargs...) ==
+    transform(model, args...; kwargs...)
+inverse_transform(LearnAPI.strip(model; options), args...; kwargs...) ==
+    inverse_transform(model, args...; kwargs...)
+```
+
+Additionally:
+
+```julia
+LearnAPI.strip(LearnAPI.strip(model)) == LearnAPI.strip(model)
+```
+
+"""
+LearnAPI.strip(model) = model
+
 """
     LearnAPI.feature_importances(model)