Merge pull request #10 from JuliaAI/dev

Clarify meaning of `ingest!` versus `update!`

docs/src/index.md

@@ -4,13 +4,29 @@
 LearnAPI.jl</span>
 <br>
 <span style="color: #9558B2;font-size:1.6em;font-style:italic;">
-A basic Julia interface for training and applying machine learning models </span>
+A basement-level Julia interface for training and applying machine learning models </span>
 <br><br>
 ```
 
+## Goals
+
+- Ease of implementation for existing machine learning algorithms
+
+- Applicability to a large variety of algorithms
+
+- Provision of clear interface points for model-generic tooling, such as performance
+  evaluation through resampling, hyperparameter optimization, and iterative model control.
+
+- Should be data container agnostic
+
+- Should be documented in detail
+
+It is *not* a design goal of LearnAPI.jl to provide a convenient interface for the general
+user to directly interact with ML models. 
+
 ## Quick tours
 
-- To see how to **USE** models implementing LearnAPI: [Basic fit/predict
+- To see how to **INTERACT WITH** models implementing LearnAPI: [Basic fit/predict
   workflow](@ref workflow).
 
 - For developers wanting to **IMPLEMENT** LearnAPI: [Anatomy of
@@ -58,7 +74,8 @@ The following methods, dispatched on model type, are provided:
 - `update!`, for adding model iterations, or responding efficiently to other
   post-`fit`changes in hyperparameters
 
-- `ingest!`, for incremental learning
+- `ingest!`, for incremental learning (training further using *new* data, without
+  re-initializing learned parameters)
 
 - **operations**, `predict`, `predict_joint`, `transform` and `inverse_transform` for
   applying the model to data not used for training

src/accessor_functions.jl

@@ -8,18 +8,18 @@ const ACCESSOR_FUNCTIONS = (
 """
     LearnAPI.feature_importances(model, fitted_params, report)
 
-Return the model-specific feature importances of `model`, given `fittted_params` and
+Return the model-specific feature importances of `model`, given `fitted_params` and
 `report`, as returned by [`LearnAPI.fit`](@ref), [`LearnAPI.update!`](@ref) or
 [`LearnAPI.ingest!`](@ref). The value returned has the form of an abstract vector of
-`feature::Symbol => importance::Real` pairs (e.g `[:gender =>0.23, :height =>0.7, :weight
+`feature::Symbol => importance::Real` pairs (e.g `[:gender => 0.23, :height => 0.7, :weight
 => 0.1]`).
 
 The `model` supports feature importances if `:feature_importance in
 LearnAPI.functions(model)`.
 
 If for some reason a model is sometimes unable to report feature importances, then
-`feature_importances` will return all importances as 0.0, as in `[:gender =>0.0, :height
-=>0.0, :weight => 0.0]`.
+`feature_importances` will return all importances as 0.0, as in `[:gender => 0.0, :height
+=> 0.0, :weight => 0.0]`.
 
 # New model implementations
 
@@ -36,7 +36,7 @@ function feature_importances end
 """
     training_losses(model, fitted_params, report)
 
-Return the training losses for `model`, given `fittted_params` and
+Return the training losses for `model`, given `fitted_params` and
 `report`, as returned by [`LearnAPI.fit`](@ref), [`LearnAPI.update!`](@ref) or
 [`LearnAPI.ingest!`](@ref).
 
@@ -53,7 +53,7 @@ function training_losses end
 """
     training_scores(model, fitted_params, report)
 
-Return the training scores for `model`, given `fittted_params` and
+Return the training scores for `model`, given `fitted_params` and
 `report`, as returned by [`LearnAPI.fit`](@ref), [`LearnAPI.update!`](@ref) or
 [`LearnAPI.ingest!`](@ref).
 
@@ -71,7 +71,7 @@ function training_scores end
 """
     training_labels(model, fitted_params, report)
 
-Return the training labels for `model`, given `fittted_params` and
+Return the training labels for `model`, given `fitted_params` and
 `report`, as returned by [`LearnAPI.fit`](@ref), [`LearnAPI.update!`](@ref) or
 [`LearnAPI.ingest!`](@ref).