add Annotator and Detector types

bump 1.1.3

add UnsupervisedAnnotator <: Unsupervised

add Detector <: Probabilistic

overload target_scitype for Detector to be OrderedFactor{2}

add augmented_transform stub

export new types/methods

list all model subtypes in a constant for easier MLJBase extension

re-arrange

oops

typo

oops

oops

oops

tweaks

add forgotten types to list

Author: ablaom

src/MLJModelInterface.jl

@@ -1,7 +1,7 @@
 module MLJModelInterface
 
-const MODEL_TRAITS = [
-    :input_scitype,
+const MODEL_TRAITS =
+    [:input_scitype,
     :output_scitype,
     :target_scitype,
     :fit_data_scitype,
@@ -38,7 +38,17 @@ const ABSTRACT_MODEL_SUBTYPES =
      :Deterministic,
      :Interval,
      :JointProbabilistic,
-     :Static]
+     :Static,
+     :Annotator,
+     :SupervisedAnnotator,
+     :UnsupervisedAnnotator,
+     :SupervisedDetector,
+     :UnsupervisedDetector,
+     :AbstractProbabilisticSupervisedDetector,
+     :AbstractProbabilisticUnsupervisedDetector,
+     :AbstractDeterministicSupervisedDetector,
+     :AbstractDeterministicUnsupervisedDetector]
+
 
 # ------------------------------------------------------------------------
 # Dependencies
@@ -69,7 +79,8 @@ export @mlj_model, metadata_pkg, metadata_model
 # model api
 export fit, update, update_data, transform, inverse_transform,
     fitted_params, predict, predict_mode, predict_mean, predict_median,
-    predict_joint, evaluate, clean!, reformat, training_losses
+    predict_joint, evaluate, clean!, reformat, training_losses,
+    augmented_predict
 
 # model traits
 for trait in MODEL_TRAITS
@@ -118,17 +129,30 @@ abstract type Model   <: MLJType end
 # ------------------------------------------------------------------------
 # Model subtypes
 
-abstract type   Supervised <: Model end
-abstract type Unsupervised <: Model end
+abstract type          Supervised <: Model end
+abstract type        Unsupervised <: Model end
+abstract type           Annotator <: Model end
 
 abstract type Probabilistic <: Supervised end
 abstract type Deterministic <: Supervised end
 abstract type      Interval <: Supervised end
 
-abstract type Static <: Unsupervised end
-
 abstract type JointProbabilistic <: Probabilistic end
 
+abstract type Static                <: Unsupervised end
+
+abstract type SupervisedAnnotator   <: Annotator end
+abstract type UnsupervisedAnnotator <: Annotator end
+
+abstract type UnsupervisedDetector <: UnsupervisedAnnotator end
+abstract type SupervisedDetector   <: SupervisedAnnotator end
+
+abstract type AbstractProbabilisticSupervisedDetector   <: SupervisedDetector end
+abstract type AbstractProbabilisticUnsupervisedDetector <: UnsupervisedDetector end
+
+abstract type AbstractDeterministicSupervisedDetector   <: SupervisedDetector end
+abstract type AbstractDeterministicUnsupervisedDetector <: UnsupervisedDetector end
+
 # ------------------------------------------------------------------------
 # includes
 

src/data_utils.jl

@@ -434,3 +434,9 @@ UnivariateFinite(probs; kwargs...) =
     UnivariateFinite(get_interface_mode(), probs; kwargs...)
 UnivariateFinite(::LightInterface, a...; kwargs...) =
     errlight("UnivariateFinite")
+
+## FOR DETECTION MODELS
+
+const OUTLIER = "outlier"
+const INLIER = "inlier"
+const UNKNOWN = "unknown"

src/model_api.jl

@@ -15,6 +15,9 @@ 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::Probabilistic, verbosity, X, y) =  fit(m, verbosity, X)
+
 """
     MLJModelInterface.update(model, verbosity, fitresult, cache, data...)
 
@@ -98,24 +101,54 @@ fitted_params(::Model, fitresult) = (fitresult=fitresult,)
 
     predict(model, fitresult, new_data...)
 
-`Supervised` models must implement the `predict` operation. Here
-`new_data` is the output of `reformat` called on user-specified data.
+`Supervised` and `SupervisedAnnotator` models must implement the
+`predict` operation. Here `new_data` is the output of `reformat`
+called on user-specified data.
 
 """
 function predict end
 
 """
-probabilistic supervised models may overload `predict_mean`
+    augmented_predict
+
+If implemented, the same as `predict`, but with a return value
+augmented by the `predict`ion of the training data.
+
+For example, if implemented for a `Supervised` model with a
+`predict` method, `augmented_predict(model, fitresult, Xnew)` will
+return
+
+```julia
+(predict(model, fitresult, X), predict(model, fitresult, Xnew))
+```
+
+where `(X, y)` was the training data.
+
+Must be implemented by any `UnsupervisedDetector` or `SupervisedDetector`.
+
+"""
+function augmented_predict end
+
 """
-function predict_mean end
 
+Models types `M` for which `prediction_type(M) == :probablisitic` may
+overload `predict_mean`.
+
+"""
+function predict_mean end
 """
-probabilistic supervised models may overload `predict_mode`
+
+Models types `M` for which `prediction_type(M) == :probablisitic` may
+overload `predict_mode`.
+
 """
 function predict_mode end
 
 """
-probabilistic supervised models may overload `predict_median`
+
+Models types `M` for which `prediction_type(M) == :probablisitic` may
+overload `predict_median`.
+
 """
 function predict_median end
 
@@ -127,12 +160,14 @@ function predict_median end
 function predict_joint end
 
 """
-unsupervised methods must implement the `transform` operation
+`Unsupervised` models must implement the `transform` operation.
 """
 function transform end
 
 """
-unsupervised methods may implement the `inverse_transform` operation
+
+`Unsupervised` models may implement the `inverse_transform` operation.
+
 """
 function inverse_transform end
 
@@ -145,3 +180,4 @@ function restore end
 some meta-models may choose to implement the `evaluate` operations
 """
 function evaluate end
+

src/model_traits.jl

@@ -1,14 +1,33 @@
 ## OVERLOADING TRAIT DEFAULTS RELEVANT TO MODELS
 
-StatisticalTraits.docstring(M::Type{<:MLJType}) = name(M)
-StatisticalTraits.docstring(M::Type{<:Model}) =
+# unexported aliases:
+const Detector = Union{SupervisedDetector,UnsupervisedDetector}
+const ProbabilisticDetector = Union{AbstractProbabilisticSupervisedDetector,
+                                    AbstractProbabilisticUnsupervisedDetector}
+const DeterministicDetector = Union{AbstractDeterministicSupervisedDetector,
+                                    AbstractDeterministicUnsupervisedDetector}
+
+const StatTraits = StatisticalTraits
+
+StatTraits.docstring(M::Type{<:MLJType}) = name(M)
+StatTraits.docstring(M::Type{<:Model}) =
     "$(name(M)) from $(package_name(M)).jl.\n" *
     "[Documentation]($(package_url(M)))."
 
-StatisticalTraits.is_supervised(::Type{<:Supervised})      = true
-StatisticalTraits.prediction_type(::Type{<:Deterministic}) = :deterministic
-StatisticalTraits.prediction_type(::Type{<:Probabilistic}) = :probabilistic
-StatisticalTraits.prediction_type(::Type{<:Interval})      = :interval
+StatTraits.is_supervised(::Type{<:Supervised})      = true
+
+StatTraits.prediction_type(::Type{<:Deterministic}) = :deterministic
+StatTraits.prediction_type(::Type{<:Probabilistic}) = :probabilistic
+StatTraits.prediction_type(::Type{<:Interval})      = :interval
+StatTraits.prediction_type(::Type{<:ProbabilisticDetector}) =
+    :probabilistic
+StatTraits.prediction_type(::Type{<:DeterministicDetector}) =
+    :deterministic
+
+StatTraits.target_scitype(::Type{<:ProbabilisticDetector}) =
+    AbstractVector{OrderedFactor{2}}
+StatTraits.target_scitype(::Type{<:DeterministicDetector}) =
+    AbstractVector{OrderedFactor{2}}
 
 # implementation is deferred as it requires methodswith which depends upon
 # InteractiveUtils which we don't want to bring here as a dependency
@@ -18,13 +37,13 @@ implemented_methods(model) = implemented_methods(typeof(model))
 implemented_methods(::LightInterface, M) = errlight("implemented_methods")
 
 for M in ABSTRACT_MODEL_SUBTYPES
-    @eval(StatisticalTraits.abstract_type(::Type{<:$M}) = $M)
+    @eval(StatTraits.abstract_type(::Type{<:$M}) = $M)
 end
 
-StatisticalTraits.fit_data_scitype(M::Type{<:Unsupervised}) =
+StatTraits.fit_data_scitype(M::Type{<:Unsupervised}) =
     Tuple{input_scitype(M)}
-StatisticalTraits.fit_data_scitype(::Type{<:Static}) = Tuple{}
-function StatisticalTraits.fit_data_scitype(M::Type{<:Supervised})
+StatTraits.fit_data_scitype(::Type{<:Static}) = Tuple{}
+function StatTraits.fit_data_scitype(M::Type{<:Supervised})
     I = input_scitype(M)
     T = target_scitype(M)
     ret = Tuple{I,T}
@@ -37,24 +56,42 @@ function StatisticalTraits.fit_data_scitype(M::Type{<:Supervised})
     end
     return ret
 end
+StatTraits.fit_data_scitype(M::Type{<:UnsupervisedAnnotator}) =
+    Tuple{input_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{
+    AbstractProbabilisticUnsupervisedDetector,
+    AbstractDeterministicUnsupervisedDetector}}) =
+        Union{Tuple{input_scitype(M)},
+              Tuple{input_scitype(M),target_scitype(M)}}
 
-StatisticalTraits.transform_scitype(M::Type{<:Unsupervised}) =
+StatTraits.transform_scitype(M::Type{<:Unsupervised}) =
     output_scitype(M)
 
-StatisticalTraits.inverse_transform_scitype(M::Type{<:Unsupervised}) =
+StatTraits.inverse_transform_scitype(M::Type{<:Unsupervised}) =
     input_scitype(M)
 
-StatisticalTraits.predict_scitype(M::Type{<:Deterministic}) = target_scitype(M)
+StatTraits.predict_scitype(M::Type{<:Union{
+    Deterministic,DeterministicDetector}}) = target_scitype(M)
 
 
-## FALLBACKS FOR `predict_scitype` FOR `Probabilistic` MODELS
+## FALLBACKS FOR `predict_scitype` FOR `Probabilistic` and
+## `ProbabilisticDetector` MODELS
 
 # This seems less than ideal but should reduce the number of `Unknown`
 # in `prediction_type` for models which, historically, have not
 # implemented the trait.
 
-StatisticalTraits.predict_scitype(M::Type{<:Probabilistic}) =
-    _density(target_scitype(M))
+StatTraits.predict_scitype(
+    M::Type{<:Union{Probabilistic,ProbabilisticDetector}}
+) = _density(target_scitype(M))
 
 _density(::Any) = Unknown
 for T in [:Continuous, :Count, :Textual]
@@ -78,6 +115,7 @@ for T in [:Finite,
          end)
 end
 
+
 for T in [:Finite, :Multiclass, :OrderedFactor]
     eval(quote
          _density(::Type{AbstractArray{<:$T{N},D}}) where {N,D} =