emigrate reformat doc-string detail into MLJ/docs

Author: ablaom

src/model_api.jl

@@ -34,91 +34,20 @@ function update_data end
 
 Models optionally overload `reformat` to define transformations of
 user-supplied data into some model-specific representation (e.g., from
-a table to a matrix). Computational overheads associated with multiple
-`fit!`/`predict`/`transform` calls are then avoided, when memory
-resources allow. The fallback returns `args` (no transformation).
-
-Here "user-supplied data" is what the MLJ user supplies when
-constructing a machine, as in `machine(models, args...)`, which
-coincides with the arguments expected by `fit(model, verbosity,
-args...)` when `reformat` is not overloaded.
-
-Implementing a `reformat` data front-end is permitted for any `Model`
-subtype, except for subtypes of `Static`. Here is a complete list of
-responsibilities for such an implementation, for some
-`model::SomeModelType`:
-
-- A `reformat(model::SomeModelType, args...) -> data` method must be
-  implemented for each form of `args...` appearing in a valid machine
-  construction `machine(model, args...)` (there will be one for each
-  possible signature of `fit(::SomeModelType, ...)`).
-
-- Additionally, if not included above, there must be a single argument
-  form of reformat, `reformat(model::SommeModelType, arg) -> (data,)`,
-  serving as a data front-end for operations like `predict`. It must
-  always hold that `reformat(model, args...)[1] = reformat(model,
-  args[1])`.
-
-**Warning.** `reformat(model::SomeModelType, args...)` must always
-  return a tuple of the same length as `args`, even if this is one.
-
-- `fit(model::SomeModelType, verbosity, data...)` should be
-  implemented as if `data` is the output of `reformat(model,
-  args...)`, where `args` is the data an MLJ user has bound to `model`
-  in some machine. The same applies to any overloading of `update`.
-
-- Each implemented operation, such as `predict` and `transform` - but
-  excluding `inverse_transform` - must be defined as if its data
-  arguments are `reformat`ed versions of user-supplied data. For
-  example, in the supervised case, `data_new` in
-  `predict(model::SomeModelType, fitresult, data_new)` is
-  `reformat(model, Xnew)`, where `Xnew is the data provided by the MLJ
-  user in a call `predict(mach, Xnew)` (`mach.model == model`).
-
-- To specify how the model-specific representation of data is to be
-  resampled, implement `selectrows(model::SomeModelType, I, data...)
-  -> resampled_data` for each overloading of `reformat(model::SomeModel,
-  args...) -> data` above. Here `I` is an arbitrary abstract integer
-  vector or `:` (type `Colon`).
-
-**Warning.** `selectrows(model::SomeModelType, I, args...)` must always
-return a tuple of the same length as `args`, even if this is one.
-
-The fallback for `selectrows` is described at [`selectrows`](@ref).
-
-
-### Example
-
-Suppose a supervised model type `SomeSupervised` supports sample
-weights, leading to two different `fit` signatures:
-
-    fit(model::SomeSupervised, verbosity, X, y)
-    fit(model::SomeSupervised, verbosity, X, y, w)
-
-    predict(model::SomeSupervised, fitresult, Xnew)
-
-Without a data front-end implemented, suppose `X` is expected to be a
-table and `y` a vector, but suppose the core algorithm always converts
-`X` to a matrix with features as rows (features corresponding to
-columns in the table).  Then a new data-front end might look like
-this:
-
-    constant MMI = MLJModelInterface
-
-    # for fit:
-    MMI.reformat(::SomeSupervised, X, y) = (MMI.matrix(X, transpose=true), y)
-    MMI.reformat(::SomeSupervised, X, y, w) = (MMI.matrix(X, transpose=true), y, w)
-    MMI.selectrows(::SomeSupervised, I, Xmatrix, y) =
-        (view(Xmatrix, :, I), view(y, I))
-    MMI.selectrows(::SomeSupervised, I, Xmatrix, y, w) =
-        (view(Xmatrix, :, I), view(y, I), view(w, I))
-
-    # for predict:
-    MMI.reformat(::SomeSupervised, X) = (MMI.matrix(X, transpose=true),)
-    MMI.selectrows(::SomeSupervised, I, Xmatrix) = view(Xmatrix, I)
-
-With these additions, `fit` and `predict` are refactored, so that `X`
-and `Xnew` represent matrices with features as rows.
+a table to a matrix). When implemented, the MLJ user can avoid
+repeating such transformations unnecessarily, and can additionally
+make use of more efficient row subsampling, which is then based on the
+model-specific representation of data, rather than the
+user-representation. When `reformat` is overloaded,
+`selectrows(::Model, ...)` must be as well (see
+[`selectrows](@ref)). Furthermore, the model `fit` method(s), and
+operations such as `predict` and `transform`, must be refactored to
+act on the model-specific representions of the data.
+
+To implement the `reformat` data front-end for a model, refer to
+"Implementing a data front-end" in the [MLJ
+manual](https://alan-turing-institute.github.io/MLJ.jl/dev/adding_models_for_general_use/).
+
 
 """
 reformat(model::Model, args...) = args