Performance Measures

In MLJ loss functions, scoring rules, sensitivities, and so on, are collectively referred to as measures. These include re-exported loss functions from the LossFunctions.jl library, overloaded to behave the same way as the built-in measures.

To see list all measures, run measures(). Further measures for probabilistic predictors, such as proper scoring rules, and for constructing multi-target product measures, are planned. If you'd like to see measure added to MLJ, post a comment here

Note for developers: The measures interface and the built-in measures described here are defined in MLJBase, but will ultimately live in a separate package.

Using built-in measures

These measures all have the common calling syntax

measure(ŷ, y)

or

measure(ŷ, y, w)

where y iterates over observations of some target variable, and ŷ iterates over predictions (Distribution or Sampler objects in the probabilistic case). Here w is an optional vector of sample weights, or a dictionary of class weights, when these are supported by the measure.

julia> using MLJ

julia> y = [1, 2, 3, 4];

julia> ŷ = [2, 3, 3, 3];

julia> w = [1, 2, 2, 1];

julia> rms(ŷ, y) # reports an aggregrate loss
0.8660254037844386

julia> l2(ŷ, y, w) # reports per observation losses
4-element Array{Int64,1}:
 1
 2
 0
 1

julia> y = coerce(["male", "female", "female"], Multiclass)
3-element CategoricalArray{String,1,UInt32}:
 "male"
 "female"
 "female"

julia> d = UnivariateFinite(["male", "female"], [0.55, 0.45], pool=y);

julia> ŷ = [d, d, d];

julia> log_loss(ŷ, y)
3-element Array{Float64,1}:
 0.7985076962177716
 0.5978370007556204
 0.5978370007556204

The measures rms, l2 and log_loss illustrated here are actually instances of measure types. For, example, l2 = LPLoss(p=2) and log_loss = LogLoss() = LogLoss(tol=eps()). Common aliases are provided:

julia> cross_entropy
LogLoss(
    tol = 2.220446049250313e-16) @362

Traits and custom measures

Notice that l1 reports per-sample evaluations, while rms only reports an aggregated result. This and other behavior can be gleaned from measure traits which are summarized by the info method:

julia> info(l1)
`LPLoss` - lp loss type with instances `l1`, `l2`.
(name = "LPLoss",
 instances = ["l1", "l2"],
 human_name = "lp loss",
 target_scitype = Union{AbstractArray{Continuous,1}, AbstractArray{Count,1}},
 supports_weights = true,
 prediction_type = :deterministic,
 orientation = :loss,
 reports_each_observation = true,
 aggregation = MLJBase.Mean(),
 is_feature_dependent = false,
 docstring = "`LPLoss` - lp loss type with instances `l1`, `l2`. ",
 distribution_type = missing,
 supports_class_weights = false,)

Query the doc-string for a measure using the name of its type:

julia> rms
RootMeanSquaredError() @221

julia> @doc RootMeanSquaredError # same as `?RootMeanSqauredError
  MLJBase.RootMeanSquaredError

  A measure type for root mean squared error, which includes the instance(s),
  rms, rmse, root_mean_squared_error.

  RootMeanSquaredError()(ŷ, y)
  RootMeanSquaredError()(ŷ, y, w)

  Evaluate the root mean squared error on observations ŷ, given ground truth
  values y. Optionally specify per-sample weights, w.

  \text{root mean squared error} = \sqrt{n^{-1}∑ᵢ|yᵢ-ŷᵢ|^2} or \text{root
  mean squared error} = \sqrt{\frac{∑ᵢwᵢ|yᵢ-ŷᵢ|^2}{∑ᵢwᵢ}}

  Requires scitype(y) to be a subtype of
  Union{AbstractArray{ScientificTypes.Continuous,1},
  AbstractArray{ScientificTypes.Count,1}}; ŷ must be a deterministic
  prediction.

  For more information, run info(RootMeanSquaredError).

Use measures() to list all measures, and measures(conditions...) to search for measures with given traits (as you would query models). The trait instances list the actual callable instances of a given measure type (typically aliases for the default instance).

measures()

measures(filters...)

measures(matching(y))

measures(needle::Union{AbstractString,Regex}

measures(m -> m.target_scitype <: AbstractVector{<:Finite} &&
              m.supports_weights)

y  = categorical(1:3)
measures(matching(y))

measures("rms")

A user-defined measure in MLJ can be passed to the evaluate! method, and elsewhere in MLJ, provided it is a function or callable object conforming to the above syntactic conventions. By default, a custom measure is understood to:

• be a loss function (rather than a score)

• report an aggregated value (rather than per-sample evaluations)

• be feature-independent

To override this behaviour one simply overloads the appropriate trait, as shown in the following examples:

julia> y = [1, 2, 3, 4];

julia> ŷ = [2, 3, 3, 3];

julia> w = [1, 2, 2, 1];

julia> my_loss(ŷ, y) = maximum((ŷ - y).^2);

julia> my_loss(ŷ, y)
1

julia> my_per_sample_loss(ŷ, y) = abs.(ŷ - y);

julia> MLJ.reports_each_observation(::typeof(my_per_sample_loss)) = true;

julia> my_per_sample_loss(ŷ, y)
4-element Array{Int64,1}:
 1
 1
 0
 1

julia> my_weighted_score(ŷ, y) = 1/mean(abs.(ŷ - y));

julia> my_weighted_score(ŷ, y, w) = 1/mean(abs.((ŷ - y).^w));

julia> MLJ.supports_weights(::typeof(my_weighted_score)) = true;

julia> MLJ.orientation(::typeof(my_weighted_score)) = :score;

julia> my_weighted_score(ŷ, y)
1.3333333333333333

julia> X = (x=rand(4), penalty=[1, 2, 3, 4]);

julia> my_feature_dependent_loss(ŷ, X, y) = sum(abs.(ŷ - y) .* X.penalty)/sum(X.penalty);

julia> MLJ.is_feature_dependent(::typeof(my_feature_dependent_loss)) = true

julia> my_feature_dependent_loss(ŷ, X, y)
0.7

The possible signatures for custom measures are: measure(ŷ, y), measure(ŷ, y, w), measure(ŷ, X, y) and measure(ŷ, X, y, w), each measure implementing one non-weighted version, and possibly a second weighted version.

Implementation detail: Internally, every measure is evaluated using the syntax

MLJ.value(measure, ŷ, X, y, w)

and the traits determine what can be ignored and how measure is actually called. If w=nothing then the non-weighted form of measure is dispatched.

Using measures from LossFunctions.jl

The LossFunctions.jl package includes "distance loss" functions for Continuous targets, and "marginal loss" functions for Finite{2} (binary) targets. While the LossFunctions.jl interface differs from the present one (for, example binary observations must be +1 or -1), MLJ has overloaded instances of the LossFunctions.jl types to behave the same as the built-in types.

Note that the "distance losses" in the package apply to deterministic predictions, while the "marginal losses" apply to probabilistic predictions.

List of measures

ms = measures()
types = map(ms) do m m.name end
instance = map(ms) do m m.instances end
t = (type=types, instances=instance)
DataFrame(t)

59 rows × 2 columns

Other performance related tools

In MLJ one computes a confusion matrix by calling an instance of the ConfusionMatrix measure type on the data:

MLJBase.ConfusionMatrix

ConfusionMatrix()(ŷ, y)

fprs, tprs, ts = roc_curve(ŷ, y) = roc(ŷ, y)