rename LiteralTarget -> Point

Author: ablaom

docs/src/anatomy_of_an_implementation.md

@@ -129,19 +129,19 @@ end
 Users will be able to call `predict` like this:
 
 ```julia
-predict(model, LiteralTarget(), Xnew)
+predict(model, Point(), Xnew)
 ```
 
-where `Xnew` is a table (of the same form as `X` above). The argument `LiteralTarget()`
+where `Xnew` is a table (of the same form as `X` above). The argument `Point()`
 signals that literal predictions of the target variable are sought, as opposed to some
-proxy for the target, such as probability density functions.  `LiteralTarget` is an
+proxy for the target, such as probability density functions.  `Point` is an
 example of a [`LearnAPI.KindOfProxy`](@ref proxy_types) type. Targets and target proxies
 are discussed [here](@ref proxy).
 
 We provide this implementation for our ridge regressor:
 
 ```@example anatomy
-LearnAPI.predict(model::RidgeFitted, ::LiteralTarget, Xnew) =
+LearnAPI.predict(model::RidgeFitted, ::Point, Xnew) =
     Tables.matrix(Xnew)*model.coefficients
 ```
 
@@ -210,7 +210,7 @@ Because we have implemented `predict`, we are required to overload the
 target, we make this definition:
 
 ```julia
-LearnAPI.kinds_of_proxy(::Ridge) = (LiteralTarget(),)
+LearnAPI.kinds_of_proxy(::Ridge) = (Point(),)
 ```
 
 A macro provides a shortcut, convenient when multiple traits are to be defined:
@@ -219,7 +219,7 @@ A macro provides a shortcut, convenient when multiple traits are to be defined:
 @trait(
     Ridge,
     constructor = Ridge,
-    kinds_of_proxy=(LiteralTarget(),),
+    kinds_of_proxy=(Point(),),
     tags = (:regression,),
     functions = (
         :(LearnAPI.fit),
@@ -326,7 +326,7 @@ LearnAPI.minimize(model::RidgeFitted) =
 @trait(
     Ridge,
     constructor = Ridge,
-    kinds_of_proxy=(LiteralTarget(),),
+    kinds_of_proxy=(Point(),),
     tags = (:regression,),
     functions = (
         :(LearnAPI.fit),
@@ -424,11 +424,11 @@ case:
 ```@example anatomy2
 LearnAPI.obs(::RidgeFitted, Xnew) = Tables.matrix(Xnew)'
 
-LearnAPI.predict(model::RidgeFitted, ::LiteralTarget, observations::AbstractMatrix) =
+LearnAPI.predict(model::RidgeFitted, ::Point, observations::AbstractMatrix) =
     observations'*model.coefficients
 
-LearnAPI.predict(model::RidgeFitted, ::LiteralTarget, Xnew) =
-    predict(model, LiteralTarget(), obs(model, Xnew))
+LearnAPI.predict(model::RidgeFitted, ::Point, Xnew) =
+    predict(model, Point(), obs(model, Xnew))
 ```
 
 ### `target` and `features` methods

docs/src/index.md

@@ -50,7 +50,7 @@ LearnAPI.functions(forest)
 model = fit(forest, X, y)
 
 # Generate point predictions:
-ŷ = predict(model, Xnew) # or `predict(model, LiteralTarget(), Xnew)`
+ŷ = predict(model, Xnew) # or `predict(model, Point(), Xnew)`
 
 # Predict probability distributions:
 predict(model, Distribution(), Xnew)
@@ -65,10 +65,10 @@ serialize("my_random_forest.jls", small_model)
 # Recover saved model and algorithm configuration:
 recovered_model = deserialize("my_random_forest.jls")
 @assert LearnAPI.algorithm(recovered_model) == forest
-@assert predict(recovered_model, LiteralTarget(), Xnew) == ŷ
+@assert predict(recovered_model, Point(), Xnew) == ŷ
 ```
 
-`Distribution` and `LiteralTarget` are singleton types owned by LearnAPI.jl. They allow
+`Distribution` and `Point` are singleton types owned by LearnAPI.jl. They allow
 dispatch based on the [kind of target proxy](@ref proxy), a key LearnAPI.jl concept.
 LearnAPI.jl places more emphasis on the notion of target variables and target proxies than
 on the usual supervised/unsupervised learning dichotomy. From this point of view, a

docs/src/kinds_of_target_proxy.md

@@ -14,64 +14,14 @@ LearnAPI.KindOfProxy
 LearnAPI.IID
 ```
 
-| type                                  | form of an observation                                                                                                                                                            |
-|:-------------------------------------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `LearnAPI.LiteralTarget`              | same as target observations; may have the interpretation of a 50% quantile, 50% expectile or mode                                                                                 |
-| `LearnAPI.Sampleable`                 | object that can be sampled to obtain object of the same form as target observation                                                                                                |
-| `LearnAPI.Distribution`               | explicit probability density/mass function whose sample space is all possible target observations                                                                                 |
-| `LearnAPI.LogDistribution`            | explicit log-probability density/mass function whose sample space is possible target observations                                                                                 |
-| `LearnAPI.Probability`¹               | numerical probability or probability vector                                                                                                                                       |
-| `LearnAPI.LogProbability`¹            | log-probability or log-probability vector                                                                                                                                         |
-| `LearnAPI.Parametric`¹                | a list of parameters (e.g., mean and variance) describing some distribution                                                                                                       |
-| `LearnAPI.LabelAmbiguous`             | collections of labels (in case of multi-class target) but without a known correspondence to the original target labels (and of possibly different number) as in, e.g., clustering |
-| `LearnAPI.LabelAmbiguousSampleable`   | sampleable version of `LabelAmbiguous`; see `Sampleable` above                                                                                                                    |
-| `LearnAPI.LabelAmbiguousDistribution` | pdf/pmf version of `LabelAmbiguous`; see `Distribution`  above                                                                                                                    |
-| `LearnAPI.LabelAmbiguousFuzzy`        | same as `LabelAmbiguous` but with multiple values of indeterminant number                                                                                                         |
-| `LearnAPI.Quantile`²                  | same as target but with quantile interpretation                                                                                                                                   |
-| `LearnAPI.Expectile`²                 | same as target but with expectile interpretation                                                                                                                                  |
-| `LearnAPI.ConfidenceInterval`²        | confidence interval                                                                                                                                                               |
-| `LearnAPI.Fuzzy`                      | finite but possibly varying number of target observations                                                                                                                         |
-| `LearnAPI.ProbabilisticFuzzy`         | as for `Fuzzy` but labeled with probabilities (not necessarily summing to one)                                                                                                    |
-| `LearnAPI.SurvivalFunction`           | survival function                                                                                                                                                                 |
-| `LearnAPI.SurvivalDistribution`       | probability distribution for survival time                                                                                                                                        |
-| `LearnAPI.SurvivalHazardFunction`     | hazard function for survival time                                                                                                                                                 |
-| `LearnAPI.OutlierScore`               | numerical score reflecting degree of outlierness (not necessarily normalized)                                                                                                     |
-| `LearnAPI.Continuous`                 | real-valued approximation/interpolation of a discrete-valued target, such as a count (e.g., number of phone calls)                                                                |
-
-¹Provided for completeness but discouraged to avoid [ambiguities in
-representation](https://github.com/alan-turing-institute/MLJ.jl/blob/dev/paper/paper.md#a-unified-approach-to-probabilistic-predictions-and-their-evaluation).
-
-²The level will be controlled by a hyper-parameter; models providing only quantiles or
-expectiles at 50% will provide `LiteralTarget` instead.
-
-> Table of concrete subtypes of `LearnAPI.IID <: LearnAPI.KindOfProxy`.
-
-
 ## Proxies for density estimation lgorithms
 
 ```@docs
 LearnAPI.Single
 ```
 
-| type `T`                         | form of output of `predict(model, ::T)`                                |
-|:--------------------------------:|:-----------------------------------------------------------------------|
-| `LearnAPI.SingleSampleable`      | object that can be sampled to obtain a single target observation       |
-| `LearnAPI.SingleDistribution`    | explicit probability density/mass function for sampling the target     |
-| `LearnAPI.SingleLogDistribution` | explicit log-probability density/mass function for sampling the target |
-
-> Table of `LearnAPI.KindOfProxy` subtypes subtyping `LearnAPI.Single`
-
-
 ## Joint probability distributions
 
 ```@docs
 LearnAPI.Joint
 ```
-
-| type `T`                        | form of output of `predict(model, ::T, data)`                                                                                                                     |
-|:-------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `LearnAPI.JointSampleable`      | object that can be sampled to obtain a *vector* whose elements have the form of target observations; the vector length matches the number of observations in `data`. |
-| `LearnAPI.JointDistribution`    | explicit probability density/mass function whose sample space is vectors of target observations;  the vector length matches the number of observations in `data`     |
-| `LearnAPI.JointLogDistribution` | explicit log-probability density/mass function whose sample space is vectors of target observations;  the vector length matches the number of observations in `data` |
-
-> Table of `LearnAPI.KindOfProxy` subtypes subtyping `LearnAPI.Joint`

docs/src/minimize.md

@@ -8,14 +8,14 @@ minimize(model) -> <smaller version of model suitable for serialization>
 
 ```julia
 model = fit(algorithm, (X, y)) # or `fit(algorithm, X, y)`
-ŷ = predict(model, LiteralTarget(), Xnew)
+ŷ = predict(model, Point(), Xnew)
 LearnAPI.feature_importances(model)
 
 small_model = minimize(model)
 serialize("my_model.jls", small_model)
 
 recovered_model = deserialize("my_random_forest.jls")
-@assert predict(recovered_model, LiteralTarget(), Xnew) == ŷ
+@assert predict(recovered_model, Point(), Xnew) == ŷ
 
 # throws MethodError:
 LearnAPI.feature_importances(recovered_model)

docs/src/obs.md

@@ -68,7 +68,7 @@ scores = map(train_test_folds) do (train, test)
         global never_trained = false
     end
     predictobs_subset = MLUtils.getobs(predictobs, test)
-    ŷ = predict(model, LiteralTarget(), predictobs_subset)
+    ŷ = predict(model, Point(), predictobs_subset)
 
     return <score comparing ŷ with y[test]>
 

docs/src/predict_transform.md

@@ -27,7 +27,7 @@ ŷ = predict(model, Distribution(), Xnew)
 Generate point predictions:
 
 ```julia
-ŷ = predict(model, LiteralTarget(), Xnew)
+ŷ = predict(model, Point(), Xnew)
 ```
 
 Train a dimension-reducing `algorithm`:
@@ -49,7 +49,7 @@ inverse_transform(model, Xnew_reduced)
 fitobs = obs(algorithm, (X, y)) # algorithm-specific repr. of data
 model = fit(algorithm, MLUtils.getobs(fitobs, 1:100))
 predictobs = obs(model, MLUtils.getobs(X, 101:150))
-ŷ = predict(model, LiteralTarget(), predictobs)
+ŷ = predict(model, Point(), predictobs)
 ```
 
 
@@ -65,7 +65,7 @@ ŷ = predict(model, LiteralTarget(), predictobs)
 
 If the algorithm has a notion of [target variable](@ref proxy), then use 
 [`predict`](@ref) to output each supported [kind of target proxy](@ref
-proxy_types) (`LiteralTarget()`, `Distribution()`, etc).
+proxy_types) (`Point()`, `Distribution()`, etc).
 
 For output not associated with a target variable, implement [`transform`](@ref)
 instead, which does not dispatch on [`LearnAPI.KindOfProxy`](@ref), but can be optionally

docs/src/target_weights_features.md

@@ -22,7 +22,7 @@ target:
 model = fit(algorithm, data)
 X = LearnAPI.features(algorithm, data)
 y = LearnAPI.target(algorithm, data)
-ŷ = predict(model, LiteralTarget(), X)
+ŷ = predict(model, Point(), X)
 training_loss = sum(ŷ .!= y)
 ```
 

src/obs.jl

@@ -24,7 +24,7 @@ Usual workflow, using data-specific resampling methods:
 data = (X, y) # a DataFrame and a vector
 data_train = (Tables.select(X, 1:100), y[1:100])
 model = fit(algorithm, data_train)
-ŷ = predict(model, LiteralTarget(), X[101:150])
+ŷ = predict(model, Point(), X[101:150])
 ```
 
 Alternative workflow using `obs` and the MLUtils.jl method `getobs` (assumes
@@ -37,7 +37,7 @@ fit_observations = obs(algorithm, data)
 model = fit(algorithm, MLUtils.getobs(fit_observations, 1:100))
 
 predict_observations = obs(model, X)
-ẑ = predict(model, LiteralTarget(), MLUtils.getobs(predict_observations, 101:150))
+ẑ = predict(model, Point(), MLUtils.getobs(predict_observations, 101:150))
 @assert ẑ == ŷ
 ```
 

src/predict_transform.jl

@@ -57,7 +57,7 @@ DOC_DATA_INTERFACE(method) =
 
 The first signature returns target predictions, or proxies for target predictions, for
 input features `data`, according to some `model` returned by [`fit`](@ref). Where
-supported, these are literally target predictions if `kind_of_proxy = LiteralTarget()`,
+supported, these are literally target predictions if `kind_of_proxy = Point()`,
 and probability density/mass functions if `kind_of_proxy = Distribution()`. List all
 options with [`LearnAPI.kinds_of_proxy(algorithm)`](@ref), where `algorithm =
 LearnAPI.algorithm(model)`.
@@ -75,7 +75,7 @@ training features `X`, training target `y`, and test features `Xnew`:
 
 ```julia
 model = fit(algorithm, (X, y)) # or `fit(algorithm, X, y)`
-predict(model, LiteralTarget(), Xnew)
+predict(model, Point(), Xnew)
 ```
 
 See also [`fit`](@ref), [`transform`](@ref), [`inverse_transform`](@ref).

src/target_weights_features.jl

@@ -46,7 +46,7 @@ implemented, as in the following sample workflow:
 ```julia
 model = fit(algorithm, data)
 X = features(data)
-ŷ = predict(algorithm, kind_of_proxy, X) # eg, `kind_of_proxy = LiteralTarget()`
+ŷ = predict(algorithm, kind_of_proxy, X) # eg, `kind_of_proxy = Point()`
 ```
 
 The return value has the same number of observations as `data` does. For supervised models