Machines

Under the hood, calling fit! on a machine calls either MLJBase.fit or MLJBase.update, depending on the machine's internal state, as recorded in additional fields previous_model and previous_rows. These lower-level fit and update methods dispatch on the model and a view of the data defined by the optional rows keyword argument of fit! (all rows by default). In this way, if a model update method is implemented, calls to fit! can avoid redundant calculations for certain kinds of model mutations (eg, increasing the number of epochs in a neural network).

The interested reader can learn more on machine internals by examining the simplified code excerpt in Internals.

forest = EnsembleModel(atom=(@load DecisionTreeClassifier), n=10);
X, y = @load_iris;
mach = machine(forest, X, y)
fit!(mach, verbosity=2);

Machine{ProbabilisticEnsembleModel{DecisionTreeClassifier}} @ 1…24

Generally, changing a hyperparameter triggers retraining on calls to subsequent fit!:

julia> forest.bagging_fraction=0.5
0.5

julia> fit!(mach, verbosity=2);
[ Info: Updating Machine{ProbabilisticEnsembleModel{DecisionTreeClassifier}} @ 1…24.
[ Info: Truncating existing ensemble.

However, for this iterative model, increasing the iteration parameter only adds models to the existing ensemble:

julia> forest.n=15
15

julia> fit!(mach, verbosity=2);
[ Info: Updating Machine{ProbabilisticEnsembleModel{DecisionTreeClassifier}} @ 1…24.
[ Info: Building on existing ensemble of length 10
[ Info: One hash per new atom trained: 
#####

Call fit! again without making a change and no retraining occurs:

julia> fit!(mach);
┌ Info: Not retraining Machine{ProbabilisticEnsembleModel{DecisionTreeClassifier}} @ 1…24.
└  It appears up-to-date. Use `force=true` to force retraining.

However, retraining can be forced:

julia> fit!(mach, force=true);
[ Info: Training Machine{ProbabilisticEnsembleModel{DecisionTreeClassifier}} @ 1…24.

And is re-triggered if the view of the data changes:

julia> fit!(mach, rows=1:100);
[ Info: Training Machine{ProbabilisticEnsembleModel{DecisionTreeClassifier}} @ 1…24.

julia> fit!(mach, rows=1:100);
┌ Info: Not retraining Machine{ProbabilisticEnsembleModel{DecisionTreeClassifier}} @ 1…24.
└  It appears up-to-date. Use `force=true` to force retraining.

Inspecting machines

There are two methods for inspecting the outcomes of training in MLJ. To obtain a named-tuple describing the learned parameters (in a user-friendly way where possible) use fitted_params(mach). All other training-related outcomes are inspected with report(mach).

X, y = @load_iris
pca = @load PCA
mach = machine(pca, X)
fit!(mach)

Machine{PCA} @ 1…80

julia> fitted_params(mach)
(projection = PCA(indim = 4, outdim = 3, principalratio = 0.99481691454981),)

julia> report(mach)
(indim = 4,
 outdim = 3,
 mean = [5.8433333333333355, 3.054000000000001, 3.7586666666666697, 1.1986666666666674],
 principalvars = [4.224840768320109, 0.24224357162751542, 0.07852390809415459],
 tprincipalvar = 4.545608248041779,
 tresidualvar = 0.02368302712600201,
 tvar = 4.569291275167781,)

Saving machines

To save a machine to file, use the MLJ.save command:

tree = @load DecisionTreeClassifier
mach = fit!(machine(tree, X, y))
MLJ.save("my_machine.jlso", mach)

To de-serialize, one uses the machine constructor:

mach2 = machine("my_machine.jlso")
predict(mach2, Xnew);

The machine mach2 cannot be retrained; however, by providing data to the constructor one can enable retraining using the saved model hyperparameters (which overwrites the saved learned parameters):

mach3 = machine("my_machine.jlso", Xnew, ynew)
fit!(mach3)

Internals

For a supervised machine the predict method calls a lower-level MLJBase.predict method, dispatched on the underlying model and the fitresult (see below). To see predict in action, as well as its unsupervised cousins transform and inverse_transform, see Getting Started.

The fields of a Machine instance (which should not generally be accessed byt the user) are:

• model - the struct containing the hyperparameters to be used in calls to fit!

• fitresult - the learned parameters in a raw form, initially undefined

• args - a tuple of the data (in the supervised learning example above, args = (X, y))

• report - outputs of training not encoded in fitresult (eg, feature rankings)

• previous_model - a deep copy of the model used in the last call to fit!

• previous_rows - a copy of the row indices used in last call to fit!

• cache

Instead of data X and y, the machine constructor can be provided Node or Source objects ("dynamic data") to obtain a NodalMachine, rather than a regular Machine object, which has the fields listed above and some others. See Composing Models for more on this advanced feature.

API Reference

fit!(mach::Machine; rows=nothing, verbosity=1, force=false)

fit(mach.model, verbosity, mach.args...)

fit!(mach::NodalMachine; rows=nothing, verbosity=1, force=false)

fit(mach.model, verbosity, mach.args...)

fit!(N::Node; rows=nothing, verbosity::Int=1, force::Bool=false)

MLJ.save(filename, mach::AbstractMachine; kwargs...)
MLJ.save(io, mach::Machine; kwargs...)

MLJBase.save(filename, mach::AbstractMachine; kwargs...)
MLJBase.save(io, mach::Machine; kwargs...)

using MLJ
tree = @load DecisionTreeClassifier
X, y = @load_iris
mach = fit!(machine(tree, X, y))

MLJ.save("tree.jlso", mach, compression=:none)
mach_predict_only = machine("tree.jlso")
predict(mach_predict_only, X)

mach2 = machine("tree.jlso", selectrows(X, 1:100), y[1:100])
predict(mach2, X) # same as above

fit!(mach2) # saved learned parameters are over-written
predict(mach2, X) # not same as above

# using a buffer:
io = IOBuffer()
MLJ.save(io, mach)
seekstart(io)
predict_only_mach = machine(io)
predict(predict_only_mach, X)