Merge pull request #169 from JuliaAI/dev

For a 1.8 release

Author: ablaom

Project.toml

@@ -1,7 +1,7 @@
 name = "MLJModelInterface"
 uuid = "e80e1ace-859a-464e-9ed9-23947d8ae3ea"
 authors = ["Thibaut Lienart and Anthony Blaom"]
-version = "1.7.1"
+version = "1.8.0"
 
 [deps]
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"

src/MLJModelInterface.jl

@@ -41,6 +41,7 @@ const ABSTRACT_MODEL_SUBTYPES = [
     :Probabilistic,
     :Deterministic,
     :Interval,
+    :ProbabilisticSet,
     :JointProbabilistic,
     :Static,
     :Annotator,
@@ -143,6 +144,7 @@ abstract type Annotator <: Model end
 abstract type Probabilistic <: Supervised end
 abstract type Deterministic <: Supervised end
 abstract type Interval <: Supervised end
+abstract type ProbabilisticSet <: Supervised end
 
 abstract type JointProbabilistic <: Probabilistic end
 

src/metadata_utils.jl

@@ -152,7 +152,7 @@ end
 # example given in the docstring for `doc_header`.
 
 """
-    MLJModelInterface.doc_header(SomeModelType)
+    MLJModelInterface.doc_header(SomeModelType; augment=false)
 
 Return a string suitable for interpolation in the document string of
 an MLJ model type. In the example given below, the header expands to
@@ -199,7 +199,7 @@ metadata_model(FooRegressor,
     descr="La di da")
 ```
 
-Then the docstring is defined post-facto with the following code:
+Then the docstring is defined after these declarations with the following code:
 
 ```
 \"\"\"
@@ -216,15 +216,34 @@ FooRegressor
 
 ```
 
+# Variation to augment existing document string
+
+For models that have a native API with separate documentation, one may want to call
+`doc_header(FooRegressor, augment=true)` instead. In that case, the output will look like
+this:
+
+>From MLJ, the `FooRegressor` type can be imported using
+>
+>
+>    `FooRegressor = @load FooRegressor pkg=FooRegressorPkg`
+>
+>Construct an instance with default hyper-parameters using the syntax
+>`model = FooRegressor()`. Provide keyword arguments to override
+>hyper-parameter defaults, as in `FooRegressor(a=...)`.
+
 """
-function doc_header(SomeModelType)
+function doc_header(SomeModelType; augment=false)
     name = MLJModelInterface.name(SomeModelType)
     human_name = MLJModelInterface.human_name(SomeModelType)
     package_name = MLJModelInterface.package_name(SomeModelType)
     package_url = MLJModelInterface.package_url(SomeModelType)
     params = MLJModelInterface.hyperparameters(SomeModelType)
 
-    ret =
+    top = augment ?
+        """
+        From MLJ, the `$name` type can be imported using
+
+        """ :
         """
         ```
         $name
@@ -235,7 +254,9 @@ function doc_header(SomeModelType)
         model interface.
 
         From MLJ, the type can be imported using
-
+        """
+    ret = top*
+        """
         ```
         $name = @load $name pkg=$package_name
         ```

src/model_traits.jl

@@ -27,6 +27,7 @@ StatTraits.is_supervised(::Type{<:SupervisedAnnotator}) = true
 StatTraits.prediction_type(::Type{<:Deterministic}) = :deterministic
 StatTraits.prediction_type(::Type{<:Probabilistic}) = :probabilistic
 StatTraits.prediction_type(::Type{<:Interval}) = :interval
+StatTraits.prediction_type(::Type{<:ProbabilisticSet}) = :probabilistic_set
 StatTraits.prediction_type(::Type{<:ProbabilisticDetector}) = :probabilistic
 StatTraits.prediction_type(::Type{<:DeterministicDetector}) = :deterministic
 

test/metadata_utils.jl

@@ -158,7 +158,8 @@ FooRegressor
 ```
 
 A model type for constructing a foo regressor, based on
-[FooRegressorPkg.jl](http://existentialcomics.com/).
+[FooRegressorPkg.jl](http://existentialcomics.com/), and implementing the MLJ model
+interface.
 
 From MLJ, the type can be imported using
 
@@ -171,9 +172,69 @@ Provide keyword arguments to override hyper-parameter
 defaults, as in `FooRegressor(a=...)`.
 """ |> chomp |> Markdown.parse
 
+    @test string(header) == string(comparison)
 end
 
 @testset "document string" begin
     doc = (@doc FooRegressor) |> string |> chomp
     @test endswith(doc, "We have no bananas today!")
 end
+
+
+# # DOC STRING - AUGMENTED CASE
+
+"""Cool model"""
+@mlj_model mutable struct FooRegressor2 <: Deterministic
+    a::Int = 0::(_ ≥ 0)
+    b
+end
+
+metadata_pkg(FooRegressor2,
+    name="FooRegressor2Pkg",
+    uuid="10745b16-79ce-11e8-11f9-7d13ad32a3b2",
+    url="http://existentialcomics.com/",
+    julia=true,
+    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)
+
+const HEADER2 = MLJModelInterface.doc_header(FooRegressor2, augment=true)
+
+@doc """
+$HEADER2
+
+Yes, we have no bananas. We have no bananas today!
+""" FooRegressor2
+
+@testset "doc_header(ModelType, augment=true)" begin
+
+    # we test markdown parsed strings for less fussy comparison
+
+    header  = Markdown.parse(HEADER2)
+    comparison =
+"""
+From MLJ, the `FooRegressor2` type can be imported using
+
+```
+FooRegressor2 = @load FooRegressor2 pkg=FooRegressor2Pkg
+```
+
+Do `model = FooRegressor2()` to construct an instance with default hyper-parameters.
+Provide keyword arguments to override hyper-parameter
+defaults, as in `FooRegressor2(a=...)`.
+""" |> chomp |> Markdown.parse
+
+    @test string(header) == string(comparison)
+
+end
+
+@testset "document string" begin
+    doc = (@doc FooRegressor2) |> string |> chomp
+    @test endswith(doc, "We have no bananas today!")
+end