Merge pull request #44 from JuliaAI/dev

Update docs. No new release

Author: ablaom

.github/codecov.yml

@@ -0,0 +1,9 @@
+coverage:
+  status:
+    project:
+      default:
+        threshold: 0.5%
+        removed_code_behavior: fully_covered_patch
+    patch:
+      default:
+        target: 80

.github/workflows/SpellCheck.yml

@@ -0,0 +1,13 @@
+name: Spell Check
+
+on: [pull_request]
+
+jobs:
+  typos-check:
+    name: Spell Check with Typos
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Actions Repository
+        uses: actions/checkout@v4
+      - name: Check spelling
+        uses: crate-ci/typos@master

.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.6'
+          - '1.10' # LTS release
           - '1' # automatically expands to the latest stable 1.x release of Julia.
         os:
           - ubuntu-latest
@@ -44,9 +44,11 @@ jobs:
         env:
           JULIA_NUM_THREADS: 2
       - uses: julia-actions/julia-processcoverage@v1
-      - uses: codecov/codecov-action@v1
+      - uses: codecov/codecov-action@v4
         with:
-          file: lcov.info
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
+          verbose: true 
   docs:
     name: Documentation
     runs-on: ubuntu-latest
@@ -65,4 +67,4 @@ jobs:
             using Documenter: DocMeta, doctest
             using LearnAPI
             DocMeta.setdocmeta!(LearnAPI, :DocTestSetup, :(using LearnAPI); recursive=true)
-            doctest(LearnAPI)'
+            doctest(LearnAPI)'

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

Project.toml

@@ -3,16 +3,11 @@ uuid = "92ad9a40-7767-427a-9ee6-6e577f1266cb"
 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"
-
 [compat]
-julia = "1.6"
+julia = "1.10"
 
 [extras]
-SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["SparseArrays", "Test"]
+test = ["Test",]

README.md

@@ -2,27 +2,53 @@
 
 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)
+[![codecov](https://codecov.io/gh/JuliaAI/LearnAPI.jl/graph/badge.svg?token=9IWT9KYINZ)](https://codecov.io/gh/JuliaAI/LearnAPI.jl?branch=dev)
+[![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/)). 
-- [ ] 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
-- [ ] **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 machine learning algorithm:
 
-- [ ] Add methods to create/save persistent representation of learned parameters
-- [ ] Add more repo tests
-- [ ] Add methods to test an implementation
-- [ ] Add user guide ("Common Implementation Patterns" section of manual)
+```julia
+julia> ridge = Ridge(lambda=0.1)
+```
 
-[![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/)
+Inspect available functionality:
+
+```
+julia> @functions ridge
+(fit, LearnAPI.learner, LearnAPI.strip, obs, LearnAPI.features, LearnAPI.target, predict, LearnAPI.coefficients)
+```
+
+Train:
+
+```julia
+julia> model = fit(ridge, data)
+```
+
+Predict:
+
+```julia
+julia> predict(model, data)[1]
+"virginica"
+```
+
+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 Cameron Bieganek and other [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,47 @@
+# 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
+  - [x] gradient descent
+  - [x] iterative algorithms
+  - [ ] incremental algorithms
+  - [ ] dimension reduction
+  - [x] feature engineering
+  - [x] static algorithms
+  - [ ] missing value imputation
+  - [ ] transformers
+  - [x] 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:
+   - [ ] 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/Project.toml

@@ -1,8 +1,11 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
+LearnAPI = "92ad9a40-7767-427a-9ee6-6e577f1266cb"
+MLUtils = "f1d291b0-491e-4a28-83b9-f70985020b54"
 ScientificTypesBase = "30f210dd-8aff-4c5f-94ba-8e64358c1161"
 Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
 
 [compat]
-Documenter = "^0.27"
-julia = "1"
+Documenter = "1"
+julia = "1.10"

docs/make.jl

@@ -1,31 +1,39 @@
 using Documenter
 using LearnAPI
 using ScientificTypesBase
+using DocumenterInterLinks
 
-const REPO="github.com/JuliaAI/LearnAPI.jl"
+const  REPO = Remotes.GitHub("JuliaAI", "LearnAPI.jl")
 
-makedocs(;
+makedocs(
     modules=[LearnAPI,],
-    format=Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true"),
+    format=Documenter.HTML(
+        prettyurls = true,#get(ENV, "CI", nothing) == "true",
+        collapselevel = 1,
+    ),
     pages=[
-        "Overview" => "index.md",
-        "Goals and Approach" => "goals_and_approach.md",
+        "Home" => "index.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",
-        "Algorithm Traits" => "algorithm_traits.md",
+        "Reference" => [
+            "Overview" => "reference.md",
+            "fit/update" => "fit_update.md",
+            "predict/transform" => "predict_transform.md",
+            "Kinds of Target Proxy" => "kinds_of_target_proxy.md",
+            "obs and Data Interfaces" => "obs.md",
+            "target/weights/features" => "target_weights_features.md",
+            "Accessor Functions" => "accessor_functions.md",
+            "Learner Traits" => "traits.md",
+        ],
         "Common Implementation Patterns" => "common_implementation_patterns.md",
         "Testing an Implementation" => "testing_an_implementation.md",
     ],
-    repo="https://$REPO/blob/{commit}{path}#L{line}",
-    sitename="LearnAPI.jl"
+    sitename="LearnAPI.jl",
+    warnonly = [:cross_references, :missing_docs],
+    repo = Remotes.GitHub("JuliaAI", "LearnAPI.jl"),
 )
 
 deploydocs(
-    ; repo=REPO,
     devbranch="dev",
     push_preview=false,
+    repo="github.com/JuliaAI/LearnAPI.jl.git",
 )

docs/src/accessor_functions.md

@@ -1,16 +1,53 @@
-# Accessor Functions 
+# [Accessor Functions](@id accessor_functions)
 
-> **Summary.** While byproducts of training are ordinarily recorded in the `report`
-> 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.
+The sole argument of an accessor function is the output, `model`, of
+[`fit`](@ref). Learners are free to implement any number of these, or none of them. Only
+`LearnAPI.strip` has a fallback, namely the identity.
+
+- [`LearnAPI.learner(model)`](@ref)
+- [`LearnAPI.extras(model)`](@ref)
+- [`LearnAPI.strip(model)`](@ref)
+- [`LearnAPI.coefficients(model)`](@ref)
+- [`LearnAPI.intercept(model)`](@ref)
+- [`LearnAPI.tree(model)`](@ref)
+- [`LearnAPI.trees(model)`](@ref)
+- [`LearnAPI.feature_names(model)`](@ref)
+- [`LearnAPI.feature_importances(model)`](@ref)
+- [`LearnAPI.training_losses(model)`](@ref)
+- [`LearnAPI.out_of_sample_losses(model)`](@ref)
+- [`LearnAPI.predictions(model)`](@ref)
+- [`LearnAPI.out_of_sample_indices(model)`](@ref)
+- [`LearnAPI.training_scores(model)`](@ref)
+- [`LearnAPI.components(model)`](@ref)
+
+Learner-specific accessor functions may also be implemented. The names of all accessor
+functions are included in the list returned by [`LearnAPI.functions(learner)`](@ref).
+
+## Implementation guide
+
+All new implementations must implement [`LearnAPI.learner`](@ref). While, all others are
+optional, any implemented accessor functions must be added to the list returned by
+[`LearnAPI.functions`](@ref).
+
+
+## Reference
 
 ```@docs
+LearnAPI.learner
+LearnAPI.extras
+LearnAPI.strip
+LearnAPI.coefficients
+LearnAPI.intercept
+LearnAPI.tree
+LearnAPI.trees
+LearnAPI.feature_names
 LearnAPI.feature_importances
 LearnAPI.training_losses
+LearnAPI.out_of_sample_losses
+LearnAPI.predictions
+LearnAPI.out_of_sample_indices
 LearnAPI.training_scores
-LearnAPI.training_labels
+LearnAPI.components
 ```