Merge pull request #22 from JuliaAI/dev

For a 0.1.0 release

Author: ablaom

Project.toml

@@ -4,6 +4,7 @@ authors = ["Anthony D. Blaom <anthony.blaom@gmail.com>"]
 version = "0.1.0"
 
 [deps]
+InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 
 [extras]

README.md

@@ -1,18 +1,20 @@
 # LearnAPI.jl
 
-A Julia interface for training and applying machine learning models. 
+A base Julia interface for machine learning and statistics
 
 
 **Devlopement Status:**
 
 - [X] Detailed proposal stage ([this
-      documentation](https://juliaai.github.io/LearnAPI.jl/dev/))
-- [ ] Initial feedback stage (opened mid-January, 2023)
+      documentation](https://juliaai.github.io/LearnAPI.jl/dev/)). 
+- [ ] Initial feedback stage (opened mid-January, 2023). General feedback can be provided at [this Julia Discourse thread](https://discourse.julialang.org/t/ann-learnapi-jl-proposal-for-a-basement-level-machine-learning-api/93048/20). 
 - [ ] Implement feedback and finish "To do" list (below)
 - [ ] Proof of concept implementation
 - [ ] Polish
 - [ ] Registration
 
+You can join a discussion on the LearnAPI proposal at [this](https://discourse.julialang.org/t/ann-learnapi-jl-proposal-for-a-basement-level-machine-learning-api/93048) Julia Discourse thread.
+
 To do:
 
 - [ ] Add methods to create/save persistent representation of learned parameters

docs/make.jl

@@ -9,13 +9,14 @@ makedocs(;
     format=Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true"),
     pages=[
         "Overview" => "index.md",
+        "Goals and Approach" => "goals_and_approach.md",
         "Anatomy of an Implementation" => "anatomy_of_an_implementation.md",
         "Reference" => "reference.md",
         "Fit, update and ingest" => "fit_update_and_ingest.md",
         "Predict and other operations" => "operations.md",
         "Accessor Functions" => "accessor_functions.md",
         "Optional Data Interface" => "optional_data_interface.md",
-        "Model Traits" => "model_traits.md",
+        "Algorithm Traits" => "algorithm_traits.md",
         "Common Implementation Patterns" => "common_implementation_patterns.md",
         "Testing an Implementation" => "testing_an_implementation.md",
     ],

docs/src/accessor_functions.md

@@ -1,8 +1,8 @@
 # Accessor Functions 
 
 > **Summary.** While byproducts of training are ordinarily recorded in the `report`
-> component of the output of `fit`/`update!`/`ingest!`, some families of models report an
-> item that is likely shared by multiple model types, and it is useful to have common
+> component of the output of `fit`/`update!`/`ingest!`, some families of algorithms report an
+> item that is likely shared by multiple algorithm types, and it is useful to have common
 > interface for accessing these directly. Training losses and feature importances are two
 > examples.
 

docs/src/algorithm_traits.md

@@ -0,0 +1,139 @@
+# Algorithm Traits
+
+> **Summary.** Traits allow one to promise particular behaviour for an algorithm, such as:
+> *This algorithm supports per-observation weights, which must appear as the third
+> argument of `fit`*, or *This algorithm's `transform` method predicts `Real` vectors*.
+
+Algorithm traits are functions whose first (and usually only) argument is an algorithm. In
+a new implementation, a single-argument trait is declared following this pattern:
+
+```julia
+LearnAPI.is_pure_julia(algorithm::MyAlgorithmType) = true
+```
+
+!!! important
+
+    The value of a trait must be the same for all algorithms of the same type, 
+	even if the types differ only in type parameters.  There are exceptions for 
+	some traits, if 
+    `is_wrapper(algorithm) = true` for all instances `algorithm` of some type 
+	(composite algorithms).  This requirement occasionally requires that 
+	an existing algorithm implementation be split into 	separate LearnAPI 
+	implementations (e.g., one for regression and another for classification).
+
+The declaration above has the shorthand
+
+```julia
+@trait MyAlgorithmType is_pure_julia=true
+```
+
+Multiple traits can be declared like this:
+
+
+```julia
+@trait(
+    MyAlgorithmType,
+    is_pure_julia = true,
+    pkg_name = "MyPackage",
+)
+```
+
+### Special two-argument traits
+
+The two-argument version of [`LearnAPI.predict_output_scitype`](@ref) and
+[`LearnAPI.predict_output_scitype`](@ref) are the only overloadable traits with more than
+one argument. They cannot be declared using the `@trait` macro.
+
+## Trait summary
+
+**Overloadable traits** are available for overloading by any new LearnAPI
+implementation. **Derived traits** are not, and should not be called by performance
+critical code
+
+### Overloadable traits
+
+In the examples column of the table below, `Table`, `Continuous`, `Sampleable` are names owned by the
+package [ScientificTypesBase.jl](https://github.com/JuliaAI/ScientificTypesBase.jl/).
+
+| trait                                            | fallback value        | return value  | example |
+|:-------------------------------------------------|:----------------------|:--------------|:--------|
+| [`LearnAPI.functions`](@ref)`(algorithm)`            | `()`                  | implemented LearnAPI functions (traits excluded) | `(:fit, :predict)` |
+| [`LearnAPI.preferred_kind_of_proxy`](@ref)`(algorithm)` | `LearnAPI.None()`   | an instance `tp` of `KindOfProxy` for which an implementation of `LearnAPI.predict(algorithm, tp, ...)` is guaranteed. | `LearnAPI.Distribution()` |
+| [`LearnAPI.position_of_target`](@ref)`(algorithm)`   | `0`                   | ¹ the positional index of the **target** in `data` in `fit(..., data...; metadata)` calls | 2 |
+| [`LearnAPI.position_of_weights`](@ref)`(algorithm)`  | `0`                   | ¹ the positional index of **per-observation weights** in `data` in `fit(..., data...; metadata)` | 3 |
+| [`LearnAPI.descriptors`](@ref)`(algorithm)`          | `()`                  | lists one or more suggestive algorithm descriptors from `LearnAPI.descriptors()` | (:classifier, :probabilistic) |
+| [`LearnAPI.is_pure_julia`](@ref)`(algorithm)`        | `false`               | is `true` if implementation is 100% Julia code | `true` |
+| [`LearnAPI.pkg_name`](@ref)`(algorithm)`             | `"unknown"`           | name of package providing core code (may be different from package providing LearnAPI.jl implementation) | `"DecisionTree"` |
+| [`LearnAPI.pkg_license`](@ref)`(algorithm)`          | `"unknown"`             | name of license of package providing core code | `"MIT"` |
+| [`LearnAPI.doc_url`](@ref)`(algorithm)`               | `"unknown"`             | url providing documentation of the core code  | `"https://en.wikipedia.org/wiki/Decision_tree_learning"` |
+| [`LearnAPI.load_path`](@ref)`(algorithm)`            | `"unknown"`             | a string indicating where the struct for `typeof(algorithm)` is defined, beginning with name of package providing implementation | `FastTrees.LearnAPI.DecisionTreeClassifier` |
+| [`LearnAPI.is_wrapper`](@ref)`(algorithm)`          | `false`                | is `true` if one or more properties (fields) of `algorithm` may be an algorithm | `true` |
+| [`LearnAPI.human_name`](@ref)`(algorithm)`          | type name with spaces  | human name for the algorithm; should be a noun | "elastic net regressor" |
+| [`LearnAPI.iteration_parameter`](@ref)`(algorithm)` | `nothing`                | symbolic name of an iteration parameter | :epochs |
+| [`LearnAPI.fit_keywords`](@ref)`(algorithm)`        |  `()`                  | tuple of symbols for keyword arguments accepted by `fit` (corresponding  to metadata) | `(:class_weights,)` |
+| [`LearnAPI.fit_scitype`](@ref)`(algorithm)`      | `Union{}` | upper bound on `scitype(data)` in `fit(algorithm, verbosity, data...)`² | `Tuple{Table(Continuous), AbstractVector{Continuous}}` |
+| [`LearnAPI.fit_observation_scitype`](@ref)`(algorithm)` | `Union{}`| upper bound on `scitype(observation)` for `observation` in `data` and `data` in `fit(algorithm, verbosity, data...)`² | `Tuple{AbstractVector{Continuous}, Continuous}` |
+| [`LearnAPI.fit_type`](@ref)`(algorithm)`            | `Union{}` | upper bound on `type(data)` in `fit(algorithm, verbosity, data...)`² | `Tuple{AbstractMatrix{<:Real}, AbstractVector{<:Real}}` |
+| [`LearnAPI.fit_observation_type`](@ref)`(algorithm)`    | `Union{}`| upper bound on `type(observation)` for `observation` in `data` and `data` in `fit(algorithm, verbosity, data...)`*    | `Tuple{AbstractVector{<:Real}, Real}` |
+| [`LearnAPI.predict_input_scitype`](@ref)`(algorithm)`  | `Union{}` | upper bound on `scitype(data)` in `predict(algorithm, fitted_params, data...)`²   | `Table(Continuous)` |
+| [`LearnAPI.predict_output_scitype`](@ref)`(algorithm, kind_of_proxy)` | `Any`     | upper bound on `scitype(first(predict(algorithm, kind_of_proxy, ...)))` | `AbstractVector{Continuous}` |
+| [`LearnAPI.predict_input_type`](@ref)`(algorithm)`     | `Union{}` | upper bound on `typeof(data)` in `predict(algorithm, fitted_params, data...)`²    | `AbstractMatrix{<:Real}` |
+| [`LearnAPI.predict_output_type`](@ref)`(algorithm, kind_of_proxy)`    | `Any`     | upper bound on `typeof(first(predict(algorithm, kind_of_proxy, ...)))`                           | `AbstractVector{<:Real}` |
+| [`LearnAPI.transform_input_scitype`](@ref)`(algorithm)`  | `Union{}` | upper bound on `scitype(data)` in `transform(algorithm, fitted_params, data...)`²   | `Table(Continuous)` |
+| [`LearnAPI.transform_output_scitype`](@ref)`(algorithm)` | `Any`     | upper bound on `scitype(first(transform(algorithm, ...)))`                          |  `Table(Continuous)` |
+| [`LearnAPI.transform_input_type`](@ref)`(algorithm)`     | `Union{}` | upper bound on `typeof(data)` in `transform(algorithm, fitted_params, data...)`²    | `AbstractMatrix{<:Real}}` |
+| [`LearnAPI.transform_output_type`](@ref)`(algorithm)`    | `Any`     | upper bound on `typeof(first(transform(algorithm, ...)))`                           | `AbstractMatrix{<:Real}` |
+
+¹ If the value is `0`, then the variable in boldface type is not supported and not
+expected to appear in `data`. If `length(data)` is less than the trait value, then `data`
+is understood to exclude the variable, but note that `fit` can have multiple signatures of
+varying lengths, as in `fit(algorithm, verbosity, X, y)` and `fit(algorithm, verbosity, X, y,
+w)`. A non-zero value is a promise that `fit` includes a signature of sufficient length to
+include the variable.
+
+² Assuming no [optional data interface](@ref data_interface) is implemented. See docstring
+for the general case.
+
+
+### Derived Traits
+
+The following convenience methods are provided but intended for overloading:
+
+| trait                                | return value                              | example    |
+|:-------------------------------------|:------------------------------------------|:-----------|
+| `LearnAPI.name(algorithm)`           | algorithm type name as string                 | "PCA"  |
+| `LearnAPI.is_algorithm(algorithm)`   | `true` if `functions(algorithm)` is not empty | `true` |
+| [`LearnAPI.predict_output_scitype`](@ref)(algorithm) | dictionary of upper bounds on the scitype of predictions, keyed on subtypes of [`LearnAPI.KindOfProxy`](@ref) |
+| [`LearnAPI.predict_output_type`](@ref)(algorithm)    | dictionary of upper bounds on the type of predictions, keyed on subtypes of [`LearnAPI.KindOfProxy`](@ref)    |
+
+
+## Reference
+
+```@docs
+LearnAPI.functions
+LearnAPI.preferred_kind_of_proxy
+LearnAPI.position_of_target
+LearnAPI.position_of_weights
+LearnAPI.descriptors
+LearnAPI.is_pure_julia
+LearnAPI.pkg_name
+LearnAPI.pkg_license
+LearnAPI.doc_url
+LearnAPI.load_path
+LearnAPI.is_wrapper
+LearnAPI.fit_keywords
+LearnAPI.human_name
+LearnAPI.iteration_parameter
+LearnAPI.fit_scitype
+LearnAPI.fit_type
+LearnAPI.fit_observation_scitype
+LearnAPI.fit_observation_type
+LearnAPI.predict_input_scitype
+LearnAPI.predict_output_scitype
+LearnAPI.predict_input_type
+LearnAPI.predict_output_type
+LearnAPI.transform_input_scitype
+LearnAPI.transform_output_scitype
+LearnAPI.transform_input_type
+LearnAPI.transform_output_type
+```