The BetaML.Api Module

Api

The Api Module (currently v2)

This module includes the shared api through the various BetaML submodules, i.e. names used by more than one submodule.

Modules are free to use other functions but these are defined here to avoid name conflicts and instead allow Multiple Dispatch to handle them. For a user-perspective overall description of the BetaML API see the page API V2 → Introduction for users, while for the implementation of the API see the page API V2 → For developers

Fixed RNG to allow reproducible results

Use it with:

• myAlgorithm(;rng=FIXEDRNG) # always produce the same sequence of results on each run of the script ("pulling" from the same rng object on different calls)
• myAlgorithm(;rng=copy(FIXEDRNG)) # always produce the same result (new rng object on each function call)

const FIXEDSEED

Fixed seed to allow reproducible results. This is the seed used to obtain the same results under unit tests.

Use it with:

• myAlgorithm(;rng=MyChoosenRNG(FIXEDSEED)) # always produce the same sequence of results on each run of the script ("pulling" from the same rng object on different calls)
• myAlgorithm(;rng=copy(MyChoosenRNG(FIXEDSEED))) # always produce the same result (new rng object on each call)

mutable struct BML_options <: BetaMLOptionsSet

A struct defining the options used by default by the algorithms that do not override it with their own option sets.

Fields:

• cache::Bool: Cache the results of the fitting stage, as to allow predict(mod) [default: true]. Set it to false to save memory for large data.

• descr::String: An optional title and/or description for this model

• autotune::Bool: Option for hyper-parameters autotuning [def: false, i.e. no autotuning performed]. If activated, autotuning is performed on the first fit!() call. Control auto-tuning through the option tunemethod (see the model hyper-parameters)

• verbosity::Verbosity: The verbosity level to be used in training or prediction: NONE, LOW, STD [default], HIGH or FULL

• onfail::String: The strategy to apply in case of failure during the fitting (loss not decreasing) [def: "tryagain"]. The default is to try again with a new random initialization of the weights and the batch ("tryagain"). Other valid values are "continue", "stop" and "error". The first one ignores the issue, the second one stops the training (but without generating an error) and the last one stops the fitting and generates an error. Note that this is currently supported only by the NeuralNetworkEstimator.

• fail_epoch::Int64: The epoch at which to try the onfail strategy [def: 5]

• fail_threshold::Float64: The (relative) threshold to use for the onfail strategy [def: 0.01]. If the loss doesn't decrease by at least this value, the onfail strategy is applied. Note that this is computed in relation to the loss on the second epoch, so it is not an absolute value.

• fail_attempts::Int64: The maximum number of attempts to use for the tryagain strategy [def: 10]

• rng::Random.AbstractRNG: Random Number Generator (see ?FIXEDSEED) [default: Random.GLOBAL_RNG]

Notes:

• even if a model doesn't override BML_options, it may not use all its options, for example deterministic models would not make use of the rng parameter. Passing such parameters in these cases would simply have no influence.

Example:

julia> options = BML_options(cache=false,descr="My model")

primitive type Verbosity <: Enum{Int32} 32

Many models and functions accept a verbosity parameter.

Choose between: NONE, LOW, STD [default], HIGH and FULL.

fit!(m::BetaMLModel,X,[y])

Fit ("train") a BetaMLModel (i.e. learn the algorithm's parameters) based on data, either only features or features and labels.

Each specific model implements its own version of fit!(m,X,[Y]), but the usage is consistent across models.

Notes:

• For online algorithms, i.e. models that support updating of the learned parameters with new data, fit! can be repeated as new data arrive, although not all algorithms guarantee that training each record at a time is equivalent to training all the records at once.
• If the model has been trained while having the cache option set to true (by default) fit! returns ŷ instead of nothing effectively making it behave like a fit-and-transform function.
• In Python and other languages that don't allow the exclamation mark within the function name, use fit_ex(⋅) instead of fit!(⋅)

hyperparameters(m::BetaMLModel)

Returns the hyperparameters of a BetaML model. See also ?options for the parameters that do not directly affect learning.

info(m::BetaMLModel) -> Any

Return a string-keyed dictionary of "additional" information stored during model fitting.

inverse_predict(m::BetaMLModel,X)

Given a model m that fitted on x produces xnew, it takes xnew to return (possibly an approximation of) x.

For example, when OneHotEncoder is fitted with a subset of the possible categories and the handle_unknown option is set to infrequent, inverse_transform will aggregate all the other categories as specified in other_categories_name.

Notes:

• Implemented only in a few models.

model_load(filename::AbstractString)
model_load(filename::AbstractString,args::AbstractString...)

Load from file one or more BetaML models (whether fitted or not).

Notes:

• If no model names to retrieve are specified it returns a dictionary keyed with the model names
• If multiple models are requested, a tuple is returned
• For further options see the documentation of the function load of the JLD2 package

Examples:

julia> models = model_load("fittedModels.jld2")
julia> mod1 = model_load("fittedModels.jld2","mod1")
julia> (mod1,mod2) = model_load("fittedModels.jld2","mod1", "mod2")

model_save(filename::AbstractString,overwrite_file::Bool=false;kwargs...)

Allows saving one or more BetaML models (whether fitted or not), optionally specifying a name for each of them.

Parameters:

• filename: Name of the destination file
• overwrite_file: Whether to overwrite the file if it already exists or preserve it (for the objects different from the ones that are going to be saved) [def: false, i.e. preserve the file]
• kwargs: model objects to be saved, optionally associated with a different name to save them with (e.g. mod1Name=mod1,mod2)

Notes:

• If an object with the given name already exists in the destination JLD2 file it will be overwritten.
• Models whose parameters are on a GPU are saved with their parameters moved to the CPU. Neural networks with the option device=:auto are moved back to the same kind of GPU when used for predictions, if its package is loaded (see the device option of NeuralNetworkEstimator).
• If the file exists, but it is not a JLD2 file and the option overwrite_file is set to false, an error will be raised.
• Use the semicolon ; to separate the filename from the model(s) to save
• For further options see the documentation of the JLD2 package

Examples

julia> model_save("fittedModels.jld2"; mod1Name=mod1,mod2)

options(m::BetaMLModel)

Returns the non-learning related options of a BetaML model. See also ?hyperparameters for the parameters that directly affect learning.

parameters(m::BetaMLModel)

Returns the learned parameters of a BetaML model.

predict(m::BetaMLModel,[X])

Predict new information (including transformation) based on a fitted BetaMLModel, optionally applied to new features when the algorithm generalises to new data.

Notes:

• As a convenience, if the model has been trained while having the cache option set to true (by default) the predictions associated with the last training of the model are retained in the model object and can be retrieved simply with predict(m).

reset!(m::BetaMLModel)

Reset the parameters of a trained model.

Notes:

• In Python and other languages that don't allow the exclamation mark within the function name, use reset_ex(⋅) instead of reset!(⋅)

sethp!(m::BetaMLModel, hp::Dict)

Set the hyperparameters of model m as specified in the hp dictionary.