Merge pull request #44 from alan-turing-institute/dev

For a 0.2.6 release

Author: ablaom

Project.toml

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

src/data_utils.jl

@@ -1,4 +1,3 @@
-
 vtrait(X) = X |> trait |> Val
 
 const REQUIRE = "(requires MLJBase to be loaded)"
@@ -292,24 +291,36 @@ _squeeze(v) = first(v)
 # UnivariateFinite
 
 const UNIVARIATE_FINITE_DOCSTRING =
-    """
-        UnivariateFinite(classes, p)
+"""
+        UnivariateFinite(classes, p; pool=nothing, ordered=false)
+
+Construct a discrete univariate distribution whose finite support is
+the elements of the vector `classes`, and whose corresponding
+probabilities are elements of the vector `p`, which must sum to one $REQUIRE.
+
+*Important.* Here `classes` must have type
+ `AbstractVector{<:CategoricalValue}` and all elements are assumed to
+share the same categorical pool. Raw classes *may* be used, but only provided
+`pool` is specified. The possible values are:
+
+- some `v::CategoricalVector`  such that `classes` is a subset of `levels(v)`
+
+- some `a::CategoricalValue` such that `classes` is a subset of `levels(a)`
+
+- `missing`, in which case a new categorical pool is created which has
+  `classes` as its only levels.
 
-A discrete univariate distribution whose finite support is the elements of the
-vector `classes`, and whose corresponding probabilities are elements of the
-vector `p`, which must sum to one $REQUIRE. Here `classes` must have type
-`AbstractVector{<:CategoricalElement}` where
+In the last case specify `ordered=true` to order the new pool.
 
-        CategoricalElement = Union{CategoricalValue,CategoricalString}
+        UnivariateFinite(prob_given_class; pool=nothing, ordered=false)
 
-and all classes are assumed to share the same categorical pool.
+Construct a discrete univariate distribution whose finite support is
+the set of keys of the provided dictionary, `prob_given_class`, and
+whose values specify the corresponding probabilities $REQUIRE.
 
-        UnivariateFinite(prob_given_class)
+The type requirements on the keys of the dictionary are the same as
+`classes` above.
 
-A discrete univariate distribution whose finite support is the set of keys of
-the provided dictionary, `prob_given_class` $REQUIRE. The dictionary keys must
-be of type `CategoricalElement` (see above) and the dictionary values specify
-the corresponding probabilities.
 """
 UnivariateFinite(d::AbstractDict; kwargs...) =
     UnivariateFinite(get_interface_mode(), d; kwargs...)