# Accessor Functions

The sole argument of an accessor function is the output, `model`

, of `fit`

or `obsfit`

.

`LearnAPI.algorithm(model)`

`LearnAPI.extras(model)`

`LearnAPI.coefficients(model)`

`LearnAPI.intercept(model)`

`LearnAPI.tree(model)`

`LearnAPI.trees(model)`

`LearnAPI.feature_importances(model)`

`LearnAPI.training_labels(model)`

`LearnAPI.training_losses(model)`

`LearnAPI.training_scores(model)`

`LearnAPI.components(model)`

## Implementation guide

All new implementations must implement `LearnAPI.algorithm`

. While, all others are optional, any implemented accessor functions must be added to the list returned by `LearnAPI.functions`

.

## Reference

`LearnAPI.algorithm`

— Function```
LearnAPI.algorithm(model)
LearnAPI.algorithm(minimized_model)
```

Recover the algorithm used to train `model`

or the output of `minimize(model)`

.

In other words, if `model = fit(algorithm, data...)`

, for some `algorithm`

and `data`

, then

`LearnAPI.algorithm(model) == algorithm == LearnAPI.algorithm(minimize(model))`

is `true`

.

**New implementations**

Implementation is compulsory for new algorithm types. The behaviour described above is the only contract. If implemented, you must include `algorithm`

in the tuple returned by the `LearnAPI.functions`

trait.

`LearnAPI.extras`

— Function`LearnAPI.extras(model)`

Return miscellaneous byproducts of an algorithm's computation, from the object `model`

returned by a call of the form `fit(algorithm, data)`

.

For "static" algorithms (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.algorithm`

, `LearnAPI.coefficients`

, `LearnAPI.intercept`

, `LearnAPI.tree`

, `LearnAPI.trees`

, `LearnAPI.feature_importances`

, `LearnAPI.training_labels`

, `LearnAPI.training_losses`

, `LearnAPI.training_scores`

and `LearnAPI.components`

.

If implemented, you must include `training_labels`

in the tuple returned by the `LearnAPI.functions`

trait. .

`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.algorithm(model))`

.

See also `LearnAPI.intercept`

.

**New implementations**

Implementation is optional.

If implemented, you must include `coefficients`

in the tuple returned by the `LearnAPI.functions`

trait. .

`LearnAPI.intercept`

— Function`LearnAPI.intercept(model)`

For a linear model, return the learned intercept. The value returned is `Real`

(single target) or an `AbstractVector{<:Real}`

(multi-target).

The `model`

reports intercept if `LearnAPI.intercept in LearnAPI.functions(Learn.algorithm(model))`

.

See also `LearnAPI.coefficients`

.

**New implementations**

Implementation is optional.

If implemented, you must include `intercept`

in the tuple returned by the `LearnAPI.functions`

trait. .

`LearnAPI.tree`

— Function`LearnAPI.tree(model)`

Return a user-friendly tree, in the form of a root object implementing the following interface defined in AbstractTrees.jl:

- subtypes
`AbstractTrees.AbstractNode{T}`

- implements
`AbstractTrees.children()`

- implements
`AbstractTrees.printnode()`

Such a tree can be visualized using the TreeRecipe.jl package, for example.

See also `LearnAPI.trees`

.

**New implementations**

Implementation is optional.

If implemented, you must include `tree`

in the tuple returned by the `LearnAPI.functions`

trait. .

`LearnAPI.trees`

— Function`LearnAPI.trees(model)`

For some ensemble model, return a vector of trees. See `LearnAPI.tree`

for the form of such trees.

See also `LearnAPI.tree`

.

**New implementations**

Implementation is optional.

If implemented, you must include `trees`

in the tuple returned by the `LearnAPI.functions`

trait. .

`LearnAPI.feature_importances`

— Function`LearnAPI.feature_importances(model)`

Return the algorithm-specific feature importances of a `model`

output by `fit`

`(algorithm, ...)`

for some `algorithm`

. 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 `algorithm`

supports feature importances if `LearnAPI.feature_importances in LearnAPI.functions(algorithm)`

.

If an algorithm 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 `feature_importances`

in the tuple returned by the `LearnAPI.functions`

trait. .

`LearnAPI.training_losses`

— Function`LearnAPI.training_losses(model)`

Return the training losses obtained when running `model = fit(algorithm, ...)`

for some `algorithm`

.

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 `training_losses`

in the tuple returned by the `LearnAPI.functions`

trait. .

`LearnAPI.training_scores`

— Function`LearnAPI.training_scores(model)`

Return the training scores obtained when running `model = fit(algorithm, ...)`

for some `algorithm`

.

See also `fit`

.

**New implementations**

Implement for algorithms, 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 `training_scores`

in the tuple returned by the `LearnAPI.functions`

trait. .

`LearnAPI.training_labels`

— Function`LearnAPI.training_labels(model)`

Return the training labels obtained when running `model = fit(algorithm, ...)`

for some `algorithm`

.

See also `fit`

.

**New implementations**

If implemented, you must include `training_labels`

in the tuple returned by the `LearnAPI.functions`

trait. .

`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 algorithm-valued property (hyper-parameter) of `algorithm = LearnAPI.algorithm(model)`

.

A composite model is one for which the corresponding `algorithm`

includes one or more algorithm-valued properties, and for which `LearnAPI.is_composite(algorithm)`

is `true`

.

See also `is_composite`

.

**New implementations**

Implementent if and only if `model`

is a composite model.

If implemented, you must include `components`

in the tuple returned by the `LearnAPI.functions`

trait. .