Merge pull request #19 from invenia/wct/tweak-predict-docs

Clarify `predict` docs

Project.toml

@@ -1,7 +1,7 @@
 name = "Models"
 uuid = "e6388cff-ecff-480c-9b53-83211bf7812a"
 authors = ["Invenia Technical Computing Corporation"]
-version = "0.2.1"
+version = "0.2.2"
 
 [deps]
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"

docs/src/design.md

@@ -30,18 +30,25 @@ One does not have to carry both a [`Model`](@ref) type, and a varying collection
 
 ```julia
 model = StatsBase.fit(
-    template,
+    template::Template,
     outputs::AbstractMatrix,  # always Features x Observations
     inputs::AbstractMatrix,   # always Variates x Observations
     weights=uweights(Float32, size(outputs, 2))
 )::Model
 ```
 
 ```julia
+# estimate_type(model) == PointEsimate
 outputs = StatsBase.predict(
-    model,
+    model::Model,
     inputs::AbstractMatrix  # always Features x Observations
 )::AbstractMatrix  # always Variates x Observations
+
+# estimate_type(model) == DistributionEstimate
+outputs = StatsBase.predict(
+    model::Model,
+    inputs::AbstractMatrix  # always Features x Observations
+)::AbstractVector{<:Distribution}  # length Observations
 ```
 
 [`fit`](@ref) takes in a [`Template`](@ref) and some *data* and returns a [`Model`](@ref) that has been fit to the data.

src/Models.jl

@@ -28,7 +28,7 @@ Defined as well are the traits:
 abstract type Model end
 
 """
-   fit(::Template, output, input, [weights]) -> Model
+   fit(::Template, output::AbstractMatrix, input::AbstractMatrix, [weights]) -> Model
 
 Fit the [`Template`](@ref) to the `output` and `input` data and return a trained
 [`Model`](@ref).
@@ -37,11 +37,15 @@ Convention is that `weights` defaults to `StatsBase.uweights(Float32, size(outpu
 function fit end
 
 """
-    predict(::Model, input)
+    predict(model::Model, inputs::AbstractMatrix)
 
-Predict targets for the provided `input` and [`Model`](@ref).
+Predict targets for the provided the collection of `inputs` and [`Model`](@ref).
 
-Returns a predictive distribution or point estimates depending on the [`Model`](@ref).
+If the `estimate_type(model)` is [`PointEstimate`](@ref) then this function should return
+another `AbstractMatrix` in which each column contains the prediction for a single input.
+
+If the `estimate_type(model)` is [`DistributionEstimate`](@ref) then this function should
+return a `AbstractVector{<:Distribution}`.
 """
 function predict end