clean up of metadata_model() with some default behaviour changes

Author: ablaom

src/metadata_utils.jl

@@ -1,21 +1,3 @@
-"""
-    docstring_ext
-
-Internal function to help generate the docstring for a package. See
-[`metadata_model`](@ref).
-"""
-function docstring_ext(T; descr::String="")
-    package_name = MLJModelInterface.package_name(T)
-    package_url  = MLJModelInterface.package_url(T)
-    model_name   = MLJModelInterface.name(T)
-    # the message to return
-    message = "$descr"
-    message *= "\n→ based on [$package_name]($package_url)."
-    message *= "\n→ do `@load $model_name pkg=\"$package_name\"` to " *
-        "use the model."
-    message *= "\n→ do `?$model_name` for documentation."
-end
-
 """
     metadata_pkg(T; args...)
 
@@ -72,19 +54,31 @@ function metadata_pkg(
     parentmodule(T).eval(ex)
 end
 
+# Extend `program` (an expression) to include trait definition for
+# specified `trait` and type `T`.
+function _extend!(program::Expr, trait::Symbol, value, T)
+    if value !== nothing
+        push!(program.args, quote
+              MLJModelInterface.$trait(::Type{<:$T}) = $value
+              end)
+    end
+end
+
+const WARN_MISSING_LOAD_PATH = "No `load_path` defined. "
+
+
 """
     metadata_model(`T`; args...)
 
 Helper function to write the metadata for a model `T`.
 
 ## Keywords
 
-* `input_scitype=Unknown` : allowed scientific type of the input data
-* `target_scitype=Unknown`: allowed sc. type of the target (supervised)
-* `output_scitype=Unknown`: allowed sc. type of the transformed data (unsupervised)
-* `supports_weights=false` : whether the model supports sample weights
-* `docstring=""` : short description of the model
-* `load_path=""` : where the model is (usually `PackageName.ModelName`)
+* `input_scitype=Unknown`: allowed scientific type of the input data
+* `target_scitype=Unknown`: allowed scitype of the target (supervised)
+* `output_scitype=Unkonwn`: allowed scitype of the transformed data (unsupervised)
+* `supports_weights=false`: whether the model supports sample weights
+* `load_path="unknown"`: where the model is (usually `PackageName.ModelName`)
 
 ## Example
 
@@ -93,43 +87,40 @@ metadata_model(KNNRegressor,
     input_scitype=MLJModelInterface.Table(MLJModelInterface.Continuous),
     target_scitype=AbstractVector{MLJModelInterface.Continuous},
     supports_weights=true,
-    docstring="K-Nearest Neighbors classifier: ...",
     load_path="NearestNeighbors.KNNRegressor")
 ```
 """
 function metadata_model(
     T;
     # aliases:
-    input=Unknown,
-    target=Unknown,
-    output=Unknown,
-    weights::Bool=false,
-    descr::String="",
-    path::String="",
+    input=nothing,
+    target=nothing,
+    output=nothing,
+    weights::Union{Nothing,Bool}=nothing,
+    descr::Union{Nothing,String}=nothing,
+    path::Union{Nothing,String}=nothing,
 
     # preferred names, corresponding to trait names:
     input_scitype=input,
     target_scitype=target,
     output_scitype=output,
-    supports_weights=weights,
-    docstring=descr,
-    load_path=path,
+    supports_weights::Union{Nothing,Bool}=weights,
+    docstring::Union{Nothing,String}=descr,
+    load_path::Union{Nothing,String}=path,
 )
-    if isempty(load_path)
-        pname = MLJModelInterface.package_name(T)
-        mname = MLJModelInterface.name(T)
-        load_path = "MLJModels.$(pname)_.$(mname)"
-    end
-    ex = quote
-        MLJModelInterface.input_scitype(::Type{<:$T}) = $input_scitype
-        MLJModelInterface.output_scitype(::Type{<:$T}) = $output_scitype
-        MLJModelInterface.target_scitype(::Type{<:$T}) = $target_scitype
-        MLJModelInterface.supports_weights(::Type{<:$T}) = $supports_weights
-        MLJModelInterface.load_path(::Type{<:$T}) = $load_path
-
-        function MLJModelInterface.docstring(::Type{<:$T})
-            return MLJModelInterface.docstring_ext($T; descr=$docstring)
-        end
-    end
-    parentmodule(T).eval(ex)
+    load_path === nothing && @warn WARN_MISSING_LOAD_PATH
+
+    program = quote end
+
+    # Note: Naively using metaprogramming to roll up the following
+    # code does not work. Only change this if you really know what
+    # you're doing.
+    _extend!(program, :input_scitype, input_scitype, T)
+    _extend!(program, :target_scitype, target_scitype, T)
+    _extend!(program, :output_scitype, output_scitype, T)
+    _extend!(program, :supports_weights, supports_weights, T)
+    _extend!(program, :docstring, docstring, T)
+    _extend!(program, :load_path, load_path, T)
+
+    parentmodule(T).eval(program)
 end

src/model_traits.jl

@@ -13,12 +13,7 @@ const DeterministicDetector = Union{
 
 const StatTraits = StatisticalTraits
 
-StatTraits.docstring(M::Type{<:MLJType}) = name(M)
-
-function StatTraits.docstring(M::Type{<:Model})
-    return "$(name(M)) from $(package_name(M)).jl.\n" *
-        "[Documentation]($(package_url(M)))."
-end
+StatTraits.docstring(M::Type{<:Model}) = Base.Docs.doc(M) |> string
 
 StatTraits.is_supervised(::Type{<:Supervised}) = true
 StatTraits.is_supervised(::Type{<:SupervisedAnnotator}) = true

test/metadata_utils.jl

@@ -1,12 +1,11 @@
-# poor man's info dict for testing
-info_dict(MM::Type{<:Model}) =
-    Dict(trait => eval(:($trait))(MM) for trait in M.MODEL_TRAITS)
-
+"""Cool model"""
 @mlj_model mutable struct FooRegressor <: Deterministic
     a::Int = 0::(_ ≥ 0)
     b
 end
 
+struct BarGoo <: Deterministic end
+
 metadata_pkg(FooRegressor,
     name="FooRegressorPkg",
     uuid="10745b16-79ce-11e8-11f9-7d13ad32a3b2",
@@ -15,30 +14,40 @@ metadata_pkg(FooRegressor,
     license="MIT",
     is_wrapper=false
     )
+
+# this is added in MLJBase but not in MLJModelInterface, to avoid
+# InteractiveUtils as dependency:
+setfull()
+M.implemented_methods(::FI, M::Type{<:MLJType}) =
+    getfield.(methodswith(M), :name)
+
+@test_logs(
+    (:warn, MLJModelInterface.WARN_MISSING_LOAD_PATH),
+    metadata_model(BarGoo)
+)
+
 metadata_model(FooRegressor,
-    input=Table(Continuous),
-    target=AbstractVector{Continuous},
-    descr="La di da")
+               input_scitype=Table(Continuous),
+               target_scitype=AbstractVector{Continuous},
+               load_path="goo goo")
 
-@testset "metadata" begin
-    setfull()
-    M.implemented_methods(::FI, M::Type{<:MLJType}) =
-        getfield.(methodswith(M), :name)
-    infos = info_dict(FooRegressor)
+infos =  Dict(trait => eval(:(MLJModelInterface.$trait))(FooRegressor) for
+              trait in M.MODEL_TRAITS)
 
+@testset "metadata" begin
     @test infos[:input_scitype] == Table(Continuous)
     @test infos[:output_scitype] == Unknown
     @test infos[:target_scitype] == AbstractVector{Continuous}
     @test infos[:is_pure_julia]
     @test infos[:package_name] == "FooRegressorPkg"
     @test infos[:package_license] == "MIT"
-    @test infos[:load_path] == "MLJModels.FooRegressorPkg_.FooRegressor"
+    @test infos[:load_path] == "goo goo"
     @test infos[:package_uuid] == "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
     @test infos[:package_url] == "http://existentialcomics.com/"
     @test !infos[:is_wrapper]
     @test !infos[:supports_weights]
     @test !infos[:supports_online]
-    @test startswith(infos[:docstring], "La di da")
+    @test infos[:docstring] == "Cool model\n"
     @test infos[:name] == "FooRegressor"
     @test infos[:is_supervised]
     @test infos[:prediction_type] == :deterministic

test/model_traits.jl

@@ -51,7 +51,7 @@ bar(::P1) = nothing
 
     @test hyperparameter_ranges(md) == (nothing,)
 
-    @test docstring(ms) == "S1 from unknown.jl.\n[Documentation](unknown)."
+    @test contains(docstring(ms), "No documentation")
     @test name(ms) == "S1"
 
     @test is_supervised(ms)
@@ -69,31 +69,16 @@ bar(::P1) = nothing
     # implemented methods is deferred
     setlight()
     @test_throws M.InterfaceError implemented_methods(mp)
-    
+
     setfull()
-    
+
     function M.implemented_methods(::FI, M::Type{<:MLJType})
         return getfield.(methodswith(M), :name)
     end
 
     @test Set(implemented_methods(mp)) == Set([:clean!,:bar,:foo])
 end
 
-module Fruit
-
-import MLJModelInterface.MLJType
-
-struct Banana <: MLJType end
-
-end
-
-import .Fruit
-
-@testset "extras" begin
-    @test docstring(Float64) == "Float64"
-    @test docstring(Fruit.Banana) == "Banana"
-end
-
 @testset "`_density` - helper for predict_scitype fallback" begin
     for T in [Continuous, Count, Textual]
         @test ==(