Merge pull request #122 from JuliaAI/dev

For a 1.3.3 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.3.2"
+version = "1.3.3"
 
 [deps]
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"

src/data_utils.jl

@@ -323,6 +323,14 @@ construct an abstract *array* of `UnivariateFinite` distributions by
 choosing `probs` to be an array of one higher dimension than the array
 generated.
 
+Here the word "probabilities" is an abuse of terminology as there is
+no requirement that probabilities actually sum to one, only that they
+be non-negative. So `UnivariateFinite` objects actually implement
+arbitrary non-negative measures over finite sets of labelled points. A
+`UnivariateDistribution` will be a bona fide probability measure when
+constructed using the `augment=true` option (see below) or when
+`fit` to data.
+
 Unless `pool` is specified, `support` should have type
  `AbstractVector{<:CategoricalValue}` and all elements are assumed to
  share the same categorical pool, which may be larger than `support`.
@@ -335,7 +343,8 @@ If `probs` is a matrix, it should have a column for each class in
 `support` (or one less, if `augment=true`). More generally, `probs`
 will be an array whose size is of the form `(n1, n2, ..., nk, c)`,
 where `c = length(support)` (or one less, if `augment=true`) and the
-constructor then returns an array of size `(n1, n2, ..., nk)`.
+constructor then returns an array of `UnivariateFinite` distributions
+of size `(n1, n2, ..., nk)`.
 
 ```
 using CategoricalArrays
@@ -401,11 +410,12 @@ julia> UnivariateFinite([:x, :y, :z], probs, pool=v)
 
 ### Probability augmentation
 
-Unless `augment=true`, sums of elements along the last axis (row-sums
-in the case of a matrix) must be equal to one, and otherwise such an
-array is created by inserting appropriate elements *ahead* of those
-provided. This means the provided probabilities are associated with
-the the classes `c2, c3, ..., cn`.
+If `augment=true` the provided array is augmented by inserting
+appropriate elements *ahead* of those provided, along the last
+dimension of the array. This means the user only provides probabilities
+for the classes `c2, c3, ..., cn`. The class `c1` probabilities are
+chosen so that each `UnivariateFinite` distribution in the returned
+array is a bona fide probability distribution.
 
 ---
 

src/model_api.jl

@@ -15,12 +15,11 @@ fit(::Static, ::Integer, data...) = (nothing, nothing, nothing)
 # fallbacks for supervised models that don't support sample weights:
 fit(m::Supervised, verbosity, X, y, w) = fit(m, verbosity, X, y)
 
-# fallback for unsupervised detectors when no "evaluation" labels appear:
-fit(m::Union{ProbabilisticUnsupervisedDetector,
-             DeterministicUnsupervisedDetector},
-             verbosity,
-             X,
-             y) =  fit(m, verbosity, X)
+# fallback for unsupervised annotators when labels or weights appear:
+# this is useful for evaluation and mixed composite models that combine
+# both supervised and unsupervised annotators
+fit(m::UnsupervisedAnnotator, verbosity, X, y) =  fit(m, verbosity, X)
+fit(m::UnsupervisedAnnotator, verbosity, X, y, w) =  fit(m, verbosity, X)
 
 """
     MLJModelInterface.update(model, verbosity, fitresult, cache, data...)
@@ -90,7 +89,7 @@ selectrows(::Model, I, data...) = map(X -> selectrows(X, I), data)
 # this operation can be optionally overloaded to provide access to
 # fitted parameters (eg, coeficients of linear model):
 """
-   fitted_params(model, fitresult) -> human_readable_fitresult # named_tuple
+    fitted_params(model, fitresult) -> human_readable_fitresult # named_tuple
 
 Models may overload `fitted_params`. The fallback returns
 `(fitresult=fitresult,)`.

src/model_traits.jl

@@ -41,10 +41,8 @@ for M in ABSTRACT_MODEL_SUBTYPES
     @eval(StatTraits.abstract_type(::Type{<:$M}) = $M)
 end
 
-StatTraits.fit_data_scitype(M::Type{<:Unsupervised}) =
-    Tuple{input_scitype(M)}
-StatTraits.fit_data_scitype(::Type{<:Static}) = Tuple{}
-function StatTraits.fit_data_scitype(M::Type{<:Supervised})
+# helper to determine the scitype of supervised models
+function supervised_fit_data_scitype(M)
     I = input_scitype(M)
     T = target_scitype(M)
     ret = Tuple{I,T}
@@ -57,21 +55,21 @@ function StatTraits.fit_data_scitype(M::Type{<:Supervised})
     end
     return ret
 end
-StatTraits.fit_data_scitype(M::Type{<:UnsupervisedAnnotator}) =
+
+StatTraits.fit_data_scitype(M::Type{<:Unsupervised}) =
     Tuple{input_scitype(M)}
+StatTraits.fit_data_scitype(::Type{<:Static}) = Tuple{}
+StatTraits.fit_data_scitype(M::Type{<:Supervised}) =
+    supervised_fit_data_scitype(M)
+
+# In special case of `UnsupervisedAnnotator`, we allow the target 
+# as an optional argument to `fit` (that is ignored) so that the
+# `machine` constructor will accept it as a valid argument, which
+# then enables *evaluation* of the detector with labeled data:
+StatTraits.fit_data_scitype(M::Type{<:UnsupervisedAnnotator}) =
+    Union{Tuple{input_scitype(M)}, supervised_fit_data_scitype(M)}
 StatTraits.fit_data_scitype(M::Type{<:SupervisedAnnotator}) =
-    Tuple{input_scitype(M),target_scitype(M)}
-
-# In special case of `UnsupervisedProbabilisticDetector`, and
-# `UnsupervsedDeterministicDetector` we allow the target as an
-# optional argument to `fit` (that is ignored) so that the `machine`
-# constructor will accept it as a valid argument, which then enables
-# *evaluation* of the detector with labeled data:
-StatTraits.fit_data_scitype(M::Type{<:Union{
-    ProbabilisticUnsupervisedDetector,
-    DeterministicUnsupervisedDetector}}) =
-        Union{Tuple{input_scitype(M)},
-              Tuple{input_scitype(M),target_scitype(M)}}
+    supervised_fit_data_scitype(M)
 
 StatTraits.transform_scitype(M::Type{<:Unsupervised}) =
     output_scitype(M)
@@ -82,7 +80,6 @@ StatTraits.inverse_transform_scitype(M::Type{<:Unsupervised}) =
 StatTraits.predict_scitype(M::Type{<:Union{
     Deterministic,DeterministicDetector}}) = target_scitype(M)
 
-
 ## FALLBACKS FOR `predict_scitype` FOR `Probabilistic` and
 ## `ProbabilisticDetector` MODELS