Utilities

report(mach)

Return the report for a machine mach that has been fit!, for example the coefficients in a linear model.

This is a named tuple and human-readable if possible.

If mach is a machine for a composite model, then the returned value has keys machines and report_given_machine, whose corresponding values are a vector of (nodal) machines appearing in the underlying learning network, and a dictionary of reports keyed on those machines.

using MLJ
X, y = @load_crabs;
pipe = @pipeline MyPipe(
    std = Standardizer(),
    clf = @load LinearBinaryClassifier pkg=GLM
)
mach = machine(MyPipe(), X, y) |> fit!
r = report(mach)
r.machines
2-element Array{Any,1}:
 NodalMachine{LinearBinaryClassifier{LogitLink}} @ 1…57
 NodalMachine{Standardizer} @ 7…33

r.report_given_machine[machs[1]]
(deviance = 3.8893386087844543e-7,
 dof_residual = 195.0,
 stderror = [18954.83496713119, ..., 2111.1294584763386],
 vcov = [3.592857686311793e8 ... .442545425533723e6;
         ...
         5.38856837634321e6 ... 2.1799125705781363e7 4.456867590446599e6],)

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

When called for the first time, call fit(mach.model, verbosity, args...), where args = machine.args, if rows==nothing, or

args = [selectrows(arg, rows) for arg in mach.args]

otherwise, storing the returned fit-result and report in mach. Subsequent calls do nothing unless: (i) force=true, or (ii) the specified rows are different from those used the last time a fit-result was computed, or (iii) mach.model has changed since the last time a fit-result was computed (the machine is stale). In cases (i) or (ii) MLJBase.fit is called again. Otherwise, MLJBase.update is called.

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

When called for the first time, attempt to call fit(mach.model, verbosity, args...), where args = [arg() for arg in mach.args, if rows==nothing, and

args =  [arg(rows=rows) for arg in mach.args]

otherwise. This will fail if an argument of the machine depends ultimately on some other untrained machine for successful calling, but this is resolved by instead calling fit! any node N for which mach in machines(N) is true, which trains all necessary machines in an appropriate order. Subsequent fit! calls do nothing unless: (i) force=true, or (ii) some machine on which mach depends has computed a new fit-result since mach last computed its fit-result, or (iii) the specified rows have changed since the last time a fit-result was last computed, or (iv) mach is stale (see below). In cases (i), (ii) or (iii), MLJBase.fit is called. Otherwise MLJBase.update is called.

A machine mach is stale if mach.model has changed since the last time a fit-result was computed, or if one of its training arguments is stale. A node N is stale if N.machine is stale or one of its arguments is stale. Source nodes are never stale.

Note that a nodal machine obtains its training data by calling its node arguments on the specified rows (rather than indexing its arguments on those rows) and that this calling is a recursive operation on nodes upstream of those arguments.

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

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

Serialize the machine mach to a file with path filename, or to an input/output stream io (at least IOBuffer instances are supported).

The format is JLSO (a wrapper for julia native or BSON serialization) unless a custom format has been implemented for the model type of mach.model. The keyword arguments kwargs are passed to the format-specific serializer, which in the JSLO case include these:

See (see https://github.com/invenia/JLSO.jl for details.

Machines are de-serialized using the machine constructor as shown in the example below. Data (or nodes) may be optionally passed to the constructor for retraining on new data using the saved model.

Example

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)

color_off()

Suppress color and bold output at the REPL for displaying MLJ objects.

color_on()

Enable color and bold output at the REPL, for enhanced display of MLJ objects.

@constant x = value

Equivalent to const x = value but registers the binding thus:

MLJBase.HANDLE_GIVEN_ID[objectid(value)] = :x

Registered objects get displayed using the variable name to which it was bound in calls to show(x), etc.

WARNING: As with any const declaration, binding x to new value of the same type is not prevented and the registration will not be updated.

@more

Entered at the REPL, equivalent to show(ans, 100). Use to get a recursive description of all fields of the last REPL value.

_recursive_show(stream, object, current_depth, depth)

Generate a table of the field values of the MLJType object, dislaying each value by calling the method _show on it. The behaviour of _show(stream, f) is as follows:

1. If f is itself a MLJType object, then its short form is shown

and _recursive_show generates as separate table for each of its field values (and so on, up to a depth of argument depth).

1. Otherwise f is displayed as "(omitted T)" where T = typeof(f),

unless istoobig(f) is false (the istoobig fall-back for arbitrary types being true). In the latter case, the long (ie, MIME"plain/text") form of f is shown. To override this behaviour, overload the _show method for the type in question.

to display abbreviated versions of integers

return abbreviated object id (as string) or it's registered handle (as string) if this exists

flat_values(t::NamedTuple)

View a nested named tuple t as a tree and return, as a tuple, the values at the leaves, in the order they appear in the original tuple.

julia> t = (X = (x = 1, y = 2), Y = 3)
julia> flat_values(t)
(1, 2, 3)

recursive_getproperty(object, nested_name::Expr)

Call getproperty recursively on object to extract the value of some nested property, as in the following example:

julia> object = (X = (x = 1, y = 2), Y = 3)
julia> recursive_getproperty(object, :(X.y))
2

recursively_setproperty!(object, nested_name::Expr, value)

Set a nested property of an object to value, as in the following example:

julia> mutable struct Foo
           X
           Y
       end

julia> mutable struct Bar
           x
           y
       end

julia> object = Foo(Bar(1, 2), 3)
Foo(Bar(1, 2), 3)

julia> recursively_setproperty!(object, :(X.y), 42)
42

julia> object
Foo(Bar(1, 42), 3)

unwind(iterators...)

Represent all possible combinations of values generated by iterators as rows of a matrix A. In more detail, A has one column for each iterator in iterators and one row for each distinct possible combination of values taken on by the iterators. Elements in the first column cycle fastest, those in the last clolumn slowest.

Example

julia> iterators = ([1, 2], ["a","b"], ["x", "y", "z"]);
julia> MLJTuning.unwind(iterators...)
12×3 Array{Any,2}:
 1  "a"  "x"
 2  "a"  "x"
 1  "b"  "x"
 2  "b"  "x"
 1  "a"  "y"
 2  "a"  "y"
 1  "b"  "y"
 2  "b"  "y"
 1  "a"  "z"
 2  "a"  "z"
 1  "b"  "z"
 2  "b"  "z"

@set_defaults ModelType(args...)
@set_defaults ModelType args

Create a keyword constructor for any type ModelType<:MLJBase.Model, using as default values those listed in args. These must include a value for every field, and in the order appearing in fieldnames(ModelType).

The constructor does not call MLJBase.clean!(model) on the instantiated object model. This method is for internal use only (by @from_network macro) as it is depreciated by @mlj_model macro.

Example

mutable struct Foo x::Int y end

@set_defaults Foo(1,2)

julia> Foo() Foo(1, 2)

julia> Foo(x=1, y="house") Foo(1, "house")

@set_defaults Foo [4, 5]

julia> Foo() Foo(4, 5)

permuterows(obj, perm)

Internal function to return a vector or matrix with permuted rows given the permutation perm.

check_dimension(X, Y)

Check that two vectors or matrices have matching dimensions

chunks(range, n)

split a given range into n subranges of approximately equal length.

Example

julia> collect(chunks(1:5, 2))
2-element Array{UnitRange{Int64},1}:
 1:3
 4:5

shuffle_rows(X, Y, ...; rng=)

Return a shuffled view of a vector or matrix X (or set of such) using a random permutation (which can be seeded specifying rng).