update readme

Author: ablaom

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-MIT License Copyright (c) 2021 - JuliaAI 
+MIT License Copyright (c) 2024 - Anthony Blaom
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -2,26 +2,48 @@
 
 A base Julia interface for machine learning and statistics
 
+[![Lifecycle:Maturing](https://img.shields.io/badge/Lifecycle-Maturing-007EC6)](ROADMAP.md)
+[![Build Status](https://github.com/JuliaAI/LearnAPI.jl/workflows/CI/badge.svg)](https://github.com/JuliaAI/LearnAPI.jl/actions)
+[![Coverage](https://codecov.io/gh/JuliaAI/LearnAPI.jl/branch/master/graph/badge.svg)](https://codecov.io/github/JuliaAI/LearnAPI.jl?branch=master)
+[![Docs](https://img.shields.io/badge/docs-dev-blue.svg)](https://juliaai.github.io/LearnAPI.jl/dev/)
 
-**Devlopement Status:**
+Comprehensive documentation is [here](https://juliaai.github.io/LearnAPI.jl/dev/).
 
-- [X] Detailed proposal stage ([this
-      documentation](https://juliaai.github.io/LearnAPI.jl/dev/)). 
-- [X] 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). 
-- [ ] Proof of concept implementation
-- [ ] Polish
-- [ ] **Register 0.2.0**
+New contributions welcome. See the [road map](ROADMAP.md).
 
-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.
+## Code snippet
 
-To do:
+Configure a learning algorithm, and inspect available functionality:
 
-- [ ] ~~Add methods to create/save persistent representation of learned parameters~~
-- [X] Add more repo tests
-- [ ] Add methods to test an implementation
-- [ ] Add user guide ("Common Implementation Patterns" section of manual)
+```julia
+julia> algorithm = Ridge(lambda=0.1)
+julia> LearnAPI.functions(algorithm)
+(:(LearnAPI.fit), :(LearnAPI.algorithm), :(LearnAPI.minimize), :(LearnAPI.obs), 
+:(LearnAPI.features), :(LearnAPI.target), :(LearnAPI.predict), :(LearnAPI.coefficients))
+```
 
-[![Build Status](https://github.com/JuliaAI/LearnAPI.jl/workflows/CI/badge.svg)](https://github.com/JuliaAI/LearnAPI.jl/actions)
-[![Coverage](https://codecov.io/gh/JuliaAI/LearnAPI.jl/branch/master/graph/badge.svg)](https://codecov.io/github/JuliaAI/LearnAPI.jl?branch=master)
-[![Docs](https://img.shields.io/badge/docs-dev-blue.svg)](https://juliaai.github.io/LearnAPI.jl/dev/)
+Train:
+
+```julia
+julia> model = fit(algorithm, data)
+```
+
+Predict:
+
+```julia
+julia> predict(model, data)[1]
+"setosa"
+```
+
+Predict a probability distribution ([proxy](https://juliaai.github.io/LearnAPI.jl/dev/kinds_of_target_proxy/#proxy_types) for the target):
+
+```julia
+julia> predict(model, Distribution(), data)[1]
+UnivariateFinite{Multiclass{3}}(setosa=>0.0, versicolor=>0.25, virginica=>0.75)
+```
+
+## Credits
+
+Created by Anthony Blaom, in cooperation with [members of the Julia
+community](https://discourse.julialang.org/t/ann-learnapi-jl-proposal-for-a-basement-level-machine-learning-api/93048).
 

ROADMAP.md

@@ -0,0 +1,52 @@
+# Road map
+
+- [ ] Mock up a challenging `update` use-case: controlling an iterative algorithm that
+      wants, for efficiency, to internally compute the out-of-sample predictions that will
+      be for used to *externally* determined early stopping cc: @jeremiedb
+
+- [ ] Get code coverage to 100% (see next item)
+
+- [ ] Add to this repo or a utility repo methods to test a valid implementation of
+	  LearnAPI.jl
+	  
+- [ ] Flush out "Common Implementation Patterns". The current plan is to mock up example
+	  implementations, and add them as LearnAPI.jl tests, with links to the test file from
+	  "Common Implementation Patterns". As real-world implementations roll out, we could
+	  increasingly point to those instead, to conserve effort
+	  - [x] regression
+	  - [ ] classification
+      - [ ] clustering
+	  - [ ] gradient descent
+	  - [ ] iterative algorithms
+	  - [ ] incremental algorithms
+	  - [ ] dimension reduction
+	  - [x] feature engineering
+	  - [x] static algorithms
+	  - [ ] missing value imputation
+	  - [ ] transformers
+	  - [ ] ensemble algorithms
+	  - [ ] time series forecasting
+	  - [ ] time series classification
+	  - [ ] survival analysis
+	  - [ ] density estimation
+	  - [ ] Bayesian algorithms
+	  - [ ] outlier detection
+	  - [ ] collaborative filtering
+	  - [ ] text analysis
+	  - [ ] audio analysis
+	  - [ ] natural language processing
+	  - [ ] image processing
+	  - [ ] meta-algorithms
+
+- [ ] In a utility package provide:
+    - [ ] Method to clone an algorithm with user-specified property(hyperparameter)
+          changes, as in `LearnAPI.clone(algorithm, p1=value1, p22=value2, ...)` (since
+          `algorithm` can have any type, can't really overload `Base.replace` without
+          piracy). This will be needed in tuning meta-algorithms. Or should this be in
+          LearnAPI.jl proper, to expose it to all users?
+	- [ ] Methods to facilitate common-use case data interfaces: support simultaneously
+          `fit` data of the form `data = (X, y)` where `X` is table *or* matrix, and
+          `data` a table with target specified by hyperparameter; here `obs` will return a
+          thin wrapping of the matrix of `X`, the target `y`, and the names of all
+          fields. We can have options to make `X` a concrete array or an adjoint,
+          depending on what is more efficient for the algorithm. 

docs/src/anatomy_of_an_implementation.md

@@ -24,11 +24,11 @@ A transformer ordinarily implements `transform` instead of
     the MLUtils.jl `getobs`/`numobs` interface,
     then an implementation must: (i) overload [`obs`](@ref) to articulate how
     provided data can be transformed into a form that does support
-    this interface, as illustrated below under 
-	[Providing an advanced data interface](@ref), and which may additionally 
-	enable certain performance benefits; or (ii) overload the trait
+    this interface, as illustrated below under
+    [Providing an advanced data interface](@ref), and which may additionally
+    enable certain performance benefits; or (ii) overload the trait
     [`LearnAPI.data_interface`](@ref) to specify a more relaxed data
-    API. 
+    API.
 
 The first line below imports the lightweight package LearnAPI.jl whose methods we will be
 extending. The second imports libraries needed for the core algorithm.
@@ -503,5 +503,5 @@ declaration.
 ⁴ The `data = (X, y)` pattern implemented here is not the only supported pattern. For,
 example, `data` might be a single table containing both features and target variable. In
 this case, it will be necessary to overload [`LearnAPI.features`](@ref) in addition to
-[`LearnAPI.target`](@ref); the name of the target column would need to be a hyperparameter
-or `fit` keyword argument.
+[`LearnAPI.target`](@ref); the name of the target column would need to be a
+hyperparameter.

docs/src/common_implementation_patterns.md

@@ -34,8 +34,13 @@ implementations fall into one (or more) of the following informally understood p
 
 - [Dimension Reduction](@ref): Transformers that learn to reduce feature space dimension
 
+- [Feature Engineering](@ref)
+
 - [Missing Value Imputation](@ref): Transformers that replace missing values.
 
+- [Transformers](@ref): Other transformers, such as standardizers, and categorical
+  encoders.
+
 - [Clusterering](@ref): Algorithms that group data into clusters for classification and
   possibly dimension reduction. May be true learners (generalize to new data) or static.
 
@@ -53,3 +58,5 @@ implementations fall into one (or more) of the following informally understood p
 
 - [Survival Analysis](@ref)
 
+- [Meta-algorithms](@ref)
+

docs/src/patterns/feature_engineering.md

@@ -0,0 +1,5 @@
+# Feature Engineering
+
+- For a simple feature selection algorithm (no "learning) see [these
+examples](https://github.com/JuliaAI/LearnAPI.jl/blob/dev/test/integration/static_algorithms.jl)
+from tests.

docs/src/patterns/meta_algorithms.md

@@ -0,0 +1 @@
+# Meta-algorithms

src/traits.jl

@@ -148,8 +148,9 @@ See also [`LearnAPI.predict`](@ref), [`LearnAPI.KindOfProxy`](@ref).
 
 Must be overloaded whenever `predict` is implemented.
 
-Elements of the returned tuple must be one of the following, described further in
-LearnAPI.jl documentation: $CONCRETE_TARGET_PROXY_TYPES_LIST.
+Elements of the returned tuple must be instances of types in the return value of
+`LearnAPI.kinds_of_proxy()`, i.e., one of the following, described further in LearnAPI.jl
+documentation: $CONCRETE_TARGET_PROXY_TYPES_LIST.
 
 Suppose, for example, we have the following implementation of a supervised learner
 returning only probabilistic predictions:
@@ -170,6 +171,8 @@ For more on target variables and target proxies, refer to the LearnAPI documenta
 
 """
 kinds_of_proxy(::Any) = ()
+kinds_of_proxy() = CONCRETE_TARGET_PROXY_TYPES
+
 
 tags() = [
     "regression",
@@ -179,12 +182,11 @@ tags() = [
     "iterative algorithms",
     "incremental algorithms",
     "dimension reduction",
-    "encoders",
+    "transformers",
     "feature engineering",
     "static algorithms",
     "missing value imputation",
     "ensemble algorithms",
-    "wrappers",
     "time series forecasting",
     "time series classification",
     "survival analysis",
@@ -196,6 +198,7 @@ tags() = [
     "audio analysis",
     "natural language processing",
     "image processing",
+    "meta-algorithms"
 ]
 
 const DOC_TAGS_LIST = join(map(d -> "`\"$d\"`", tags()), ", ")