Implementing a logging interface for MLFlow

docs/make.jl

@@ -13,7 +13,7 @@ makedocs(;
         "Composition" => "composition.md",
         "Datasets" => "datasets.md",
         "Distributions" => "distributions.md",
-        "Utilities" => "utilities.md"
+        "Utilities" => "utilities.md",
     ],
     repo="https://$REPO/blob/{commit}{path}#L{line}",
     sitename="MLJBase.jl"

src/composition/models/stacking.jl

@@ -388,6 +388,7 @@ function internal_stack_report(
     # For each model we record the results mimicking the fields PerformanceEvaluation
     results = NamedTuple{modelnames}(
         [(
+            model = model,
             measure = stack.measures,
             measurement = Vector{Any}(undef, n_measures),
             operation = _actual_operations(nothing, stack.measures, model, verbosity),

src/resampling.jl

@@ -474,6 +474,9 @@ be interpreted with caution. See, for example, Bates et al.
 These fields are part of the public API of the `PerformanceEvaluation`
 struct.
 
+- `model`: model used to create the performance evaluation. In the case a
+    tuning model, this is the best model found.
+
 - `measure`: vector of measures (metrics) used to evaluate performance
 
 - `measurement`: vector of measurements - one for each element of
@@ -509,13 +512,15 @@ struct.
   training and evaluation respectively.
 """
 struct PerformanceEvaluation{M,
+                             Measure,
                              Measurement,
                              Operation,
                              PerFold,
                              PerObservation,
                              FittedParamsPerFold,
                              ReportPerFold} <: MLJType
-    measure::M
+    model::M
+    measure::Measure
     measurement::Measurement
     operation::Operation
     per_fold::PerFold
@@ -568,7 +573,7 @@ function Base.show(io::IO, ::MIME"text/plain", e::PerformanceEvaluation)
 
     println(io, "PerformanceEvaluation object "*
             "with these fields:")
-    println(io, "  measure, operation, measurement, per_fold,\n"*
+    println(io, "  model, measure, operation, measurement, per_fold,\n"*
             "  per_observation, fitted_params_per_fold,\n"*
             "  report_per_fold, train_test_rows")
     println(io, "Extract:")
@@ -807,6 +812,24 @@ _process_accel_settings(accel) =  throw(ArgumentError("unsupported" *
 
 # --------------------------------------------------------------
 # User interface points: `evaluate!` and `evaluate`
+#
+"""
+    log_evaluation(logger, performance_evaluation)
+
+Log a performance evaluation to `logger`, an object specific to some logging
+platform, such as mlflow. If `logger=nothing` then no logging is performed.
+The method is called at the end of every call to `evaluate/evaluate!` using
+the logger provided by the `logger` keyword argument.
+
+# Implementations for new logging platforms
+#
+Julia interfaces to workflow logging platforms, such as mlflow (provided by
+the MLFlowClient.jl interface) should overload
+`log_evaluation(logger::LoggerType, performance_evaluation)`,
+where `LoggerType` is a platform-specific type for logger objects. For an
+example, see the implementation provided by the MLJFlow.jl package.
+"""
+log_evaluation(logger, performance_evaluation) = nothing
 
 """
     evaluate!(mach,
@@ -820,7 +843,8 @@ _process_accel_settings(accel) =  throw(ArgumentError("unsupported" *
               acceleration=default_resource(),
               force=false,
               verbosity=1,
-              check_measure=true)
+              check_measure=true,
+              logger=nothing)
 
 Estimate the performance of a machine `mach` wrapping a supervised
 model in data, using the specified `resampling` strategy (defaulting
@@ -919,6 +943,7 @@ untouched.
 
 - `check_measure` - default is `true`
 
+- `logger` - a logger object (see [`MLJBase.log_evaluation`](@ref))
 
 ### Return value
 
@@ -939,7 +964,8 @@ function evaluate!(mach::Machine{<:Measurable};
                    repeats=1,
                    force=false,
                    check_measure=true,
-                   verbosity=1)
+                   verbosity=1,
+                   logger=nothing)
 
     # this method just checks validity of options, preprocess the
     # weights, measures, operations, and dispatches a
@@ -980,9 +1006,12 @@ function evaluate!(mach::Machine{<:Measurable};
 
     _acceleration= _process_accel_settings(acceleration)
 
-    evaluate!(mach, resampling, weights, class_weights, rows, verbosity,
-              repeats, _measures, _operations, _acceleration, force)
+    evaluation = evaluate!(mach, resampling, weights, class_weights, rows,
+                           verbosity, repeats, _measures, _operations,
+                           _acceleration, force)
+    log_evaluation(logger, evaluation)
 
+    evaluation
 end
 
 """
@@ -1265,6 +1294,7 @@ function evaluate!(mach::Machine, resampling, weights,
     end
 
     return PerformanceEvaluation(
+        mach.model,
         measures,
         per_measure,
         operations,

src/utilities.jl

@@ -469,3 +469,66 @@ end
 
 generate_name!(model, existing_names; kwargs...) =
     generate_name!(typeof(model), existing_names; kwargs...)
+
+isamodel(::Any) = false
+isamodel(::Model) = true
+
+"""
+    deep_params(m::Model)
+
+Recursively convert any object subtyping `Model` into a named tuple,
+keyed on the property names of `m`. The named tuple is possibly nested
+because `deep_params` is recursively applied to the property values, which
+themselves might subtype `Model`.
+
+For most `Model` objects, properties are synonymous with fields, but
+this is not a hard requirement.
+
+    julia> deep_params(EnsembleModel(atom=ConstantClassifier()))
+    (atom = (target_type = Bool,),
+     weights = Float64[],
+     bagging_fraction = 0.8,
+     rng_seed = 0,
+     n = 100,
+     parallel = true,)
+
+"""
+deep_params(m) = deep_params(m, Val(isamodel(m)))
+deep_params(m, ::Val{false}) = m
+function deep_params(m, ::Val{true})
+    fields = propertynames(m)
+    NamedTuple{fields}(Tuple([deep_params(getproperty(m, field))
+                              for field in fields]))
+end
+
+"""
+    flat_params(t::NamedTuple)
+
+View a nested named tuple `t` as a tree and return, as a Dict, the key subtrees
+and the values at the leaves, in the order they appear in the original tuple.
+
+```julia-repl
+julia> t = (X = (x = 1, y = 2), Y = 3)
+julia> flat_params(t)
+LittleDict{...} with 3 entries:
+"X__x" => 1
+"X__y" => 2
+"Y"   => 3
+```
+"""
+function flat_params(parameters::NamedTuple)
+    result = LittleDict{String, Any}()
+    for key in keys(parameters)
+        value = params(getproperty(parameters, key))
+        if value isa NamedTuple
+            sub_dict = flat_params(value)
+            for (sub_key, sub_value) in pairs(sub_dict)
+                new_key = string(key, "__", sub_key)
+                result[new_key] = sub_value
+            end
+        else
+            result[string(key)] = value
+        end
+    end
+    return result
+end

test/utilities.jl

@@ -20,6 +20,17 @@ struct Baz <: Foo end
     @test flat_values(t) == (1, 2, 3)
 end
 
+@testset "flattening parameters" begin
+    t = (a = (ax = (ax1 = 1, ax2 = 2), ay = 3), b = 4)
+    dict_t = Dict(
+        "a__ax__ax1" => 1,
+        "a__ax__ax2" => 2,
+        "a__ay" => 3,
+        "b" => 4,
+    )
+    @test MLJBase.flat_params(t) == dict_t
+end
+
 mutable struct M
     a1
     a2