Accessor Functions

The sole argument of an accessor function is the output, model, of fit. Learners are free to implement any number of these, or none of them. Only LearnAPI.strip has a fallback, namely the identity.

LearnAPI.learner(model)
LearnAPI.extras(model)
LearnAPI.strip(model)
LearnAPI.coefficients(model)
LearnAPI.intercept(model)
LearnAPI.tree(model)
LearnAPI.trees(model)
LearnAPI.feature_names(model)
LearnAPI.feature_importances(model)
LearnAPI.training_labels(model)
LearnAPI.training_losses(model)
LearnAPI.training_predictions(model)
LearnAPI.training_scores(model)
LearnAPI.components(model)

Learner-specific accessor functions may also be implemented. The names of all accessor functions are included in the list returned by LearnAPI.functions(learner).

Implementation guide

All new implementations must implement LearnAPI.learner. While, all others are optional, any implemented accessor functions must be added to the list returned by LearnAPI.functions.

Reference

LearnAPI.learner — Function

LearnAPI.learner(model)
LearnAPI.learner(stripped_model)

Recover the learner used to train model or the output, stripped_model, of LearnAPI.strip(model).

In other words, if model = fit(learner, data...), for some learner and data, then

LearnAPI.learner(model) == learner == LearnAPI.learner(LearnAPI.strip(model))

is true.

New implementations

Implementation is compulsory for new learner types. The behaviour described above is the only contract. You must include :(LearnAPI.learner) in the return value of LearnAPI.functions(learner).

source

LearnAPI.extras — Function

LearnAPI.extras(model)

Return miscellaneous byproducts of a learning algorithm's execution, from the object model returned by a call of the form fit(learner, data).

For "static" learners (those without training data) it may be necessary to first call transform or predict on model.

See also fit.

New implementations

Implementation is discouraged for byproducts already covered by other LearnAPI.jl accessor functions: LearnAPI.learner, LearnAPI.coefficients, LearnAPI.intercept, LearnAPI.tree, LearnAPI.trees, LearnAPI.feature_names, LearnAPI.feature_importances, LearnAPI.training_labels, LearnAPI.training_losses, LearnAPI.training_predictions, LearnAPI.training_scores and LearnAPI.components.

If implemented, you must include :(LearnAPI.extras) in the tuple returned by the LearnAPI.functions trait. .

source

Base.strip — Function

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. Accessor functions that can be called on model may not work on LearnAPI.strip(model), but predict, transform and inverse_transform will work, if implemented. Check LearnAPI.functions(LearnAPI.learner(model)) to view see what the original model implements.

Implementations may provide learner-specific keyword options to control how much of the original functionality is preserved by LearnAPI.strip.

Typical workflow

model = fit(learner, (X, y)) # or `fit(learner, X, y)`
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) == ŷ

Extended help

New implementations

Overloading LearnAPI.strip for new learners is optional. The fallback is the identity.

New implementations must enforce the following identities, whenever the right-hand side is defined:

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:

LearnAPI.strip(LearnAPI.strip(model)) == LearnAPI.strip(model)

source

LearnAPI.coefficients — Function

LearnAPI.coefficients(model)

For a linear model, return the learned coefficients. The value returned has the form of an abstract vector of feature_or_class::Symbol => coefficient::Real pairs (e.g [:gender => 0.23, :height => 0.7, :weight => 0.1]) or, in the case of multi-targets, feature::Symbol => coefficients::AbstractVector{<:Real} pairs.

The model reports coefficients if :(LearnAPI.coefficients) in LearnAPI.functions(Learn.learner(model)).

See also fit.

New implementations

If implemented, you must include :(LearnAPI.feature_names) in the tuple returned by the LearnAPI.functions trait. .

source

LearnAPI.feature_importances — Function

LearnAPI.feature_importances(model)

Return the learner-specific feature importances of a model output by fit(learner, ...) for some learner. The value returned has the form of an abstract vector of feature::Symbol => importance::Real pairs (e.g [:gender => 0.23, :height => 0.7, :weight => 0.1]).

The learner supports feature importances if :(LearnAPI.feature_importances) in LearnAPI.functions(learner).

If a learner is sometimes unable to report feature importances then LearnAPI.feature_importances will return all importances as 0.0, as in [:gender => 0.0, :height => 0.0, :weight => 0.0].

New implementations

Implementation is optional.

If implemented, you must include :(LearnAPI.feature_importances) in the tuple returned by the LearnAPI.functions trait. .

source

LearnAPI.training_losses — Function

LearnAPI.training_losses(model)

Return the training losses obtained when running model = fit(learner, ...) for some learner.

See also fit.

New implementations

Implement for iterative algorithms that compute and record training losses as part of training (e.g. neural networks).

If implemented, you must include :(LearnAPI.training_losses) in the tuple returned by the LearnAPI.functions trait. .

source

LearnAPI.training_predictions — Function

LearnAPI.training_predictions(model)

Return internally computed training predictions when running model = fit(learner, ...) for some learner.

See also fit.

New implementations

Implement for iterative algorithms that compute and record training losses as part of training (e.g. neural networks). Return value should be AbstractVector.

If implemented, you must include :(LearnAPI.training_predictions) in the tuple returned by the LearnAPI.functions trait. .

source

LearnAPI.training_scores — Function

LearnAPI.training_scores(model)

Return the training scores obtained when running model = fit(learner, ...) for some learner.

See also fit.

New implementations

Implement for learners, such as outlier detection algorithms, which associate a score with each observation during training, where these scores are of interest in later processes (e.g, in defining normalized scores for new data).

If implemented, you must include :(LearnAPI.training_scores) in the tuple returned by the LearnAPI.functions trait. .

source

LearnAPI.training_labels — Function

LearnAPI.training_labels(model)

Return the training labels obtained when running model = fit(learner, ...) for some learner.

See also fit.

New implementations

If implemented, you must include :(LearnAPI.training_labels) in the tuple returned by the LearnAPI.functions trait. .

source

LearnAPI.components — Function

LearnAPI.components(model)

For a composite model, return the component models (fit outputs). These will be in the form of a vector of named pairs, property_name::Symbol => component_model. Here property_name is the name of some learner-valued property (hyper-parameter) of learner = LearnAPI.learner(model).

A composite model is one for which the corresponding learner includes one or more learner-valued properties, and for which LearnAPI.is_composite(learner) is true.