diff --git a/README.md b/README.md index 6d1287e..26dea49 100644 --- a/README.md +++ b/README.md @@ -22,9 +22,8 @@ julia> ridge = Ridge(lambda=0.1) Inspect available functionality: ``` -julia> LearnAPI.functions(ridge) -(:(LearnAPI.fit), :(LearnAPI.learner), :(LearnAPI.strip), :(LearnAPI.obs), -:(LearnAPI.features), :(LearnAPI.target), :(LearnAPI.predict), :(LearnAPI.coefficients)) +julia> @functions ridge +(fit, LearnAPI.learner, LearnAPI.strip, obs, LearnAPI.features, LearnAPI.target, predict, LearnAPI.coefficients ``` Train: diff --git a/docs/src/index.md b/docs/src/index.md index 9a0c94f..ea7f347 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -55,7 +55,7 @@ y = Xnew = # List LearnaAPI functions implemented for `forest`: -LearnAPI.functions(forest) +@functions forest # Train: model = fit(forest, X, y) diff --git a/docs/src/reference.md b/docs/src/reference.md index 3928393..9cff53d 100644 --- a/docs/src/reference.md +++ b/docs/src/reference.md @@ -199,8 +199,9 @@ minimal (but useless) implementation, see the implementation of `SmallLearner` ## Utilities ```@docs +@functions LearnAPI.clone -LearnAPI.@trait +@trait ``` --- diff --git a/src/LearnAPI.jl b/src/LearnAPI.jl index 5d31ce9..2e4a3ee 100644 --- a/src/LearnAPI.jl +++ b/src/LearnAPI.jl @@ -11,7 +11,7 @@ include("accessor_functions.jl") include("traits.jl") include("clone.jl") -export @trait +export @trait, @functions export fit, update, update_observations, update_features export predict, transform, inverse_transform, obs diff --git a/src/accessor_functions.jl b/src/accessor_functions.jl index c1b4447..1de228c 100644 --- a/src/accessor_functions.jl +++ b/src/accessor_functions.jl @@ -312,23 +312,23 @@ function training_labels end # :extras intentionally excluded: const ACCESSOR_FUNCTIONS_WITHOUT_EXTRAS = ( - learner, - coefficients, - intercept, - tree, - trees, - feature_names, - feature_importances, - training_labels, - training_losses, - training_predictions, - training_scores, - components, + :(LearnAPI.learner), + :(LearnAPI.coefficients), + :(LearnAPI.intercept), + :(LearnAPI.tree), + :(LearnAPI.trees), + :(LearnAPI.feature_names), + :(LearnAPI.feature_importances), + :(LearnAPI.training_labels), + :(LearnAPI.training_losses), + :(LearnAPI.training_predictions), + :(LearnAPI.training_scores), + :(LearnAPI.components), ) const ACCESSOR_FUNCTIONS_WITHOUT_EXTRAS_LIST = join( map(ACCESSOR_FUNCTIONS_WITHOUT_EXTRAS) do f - "[`LearnAPI.$f`](@ref)" + "[`$f`](@ref)" end, ", ", " and ", @@ -354,11 +354,12 @@ $(DOC_IMPLEMENTED_METHODS(":(LearnAPI.training_labels)")). """ function extras end -const ACCESSOR_FUNCTIONS = (extras, ACCESSOR_FUNCTIONS_WITHOUT_EXTRAS...) +const ACCESSOR_FUNCTIONS = + (:(LearnAPI.extras), ACCESSOR_FUNCTIONS_WITHOUT_EXTRAS...) const ACCESSOR_FUNCTIONS_LIST = join( map(ACCESSOR_FUNCTIONS) do f - "[`LearnAPI.$f`](@ref)" + "[`$f`](@ref)" end, ", ", " and ", diff --git a/src/traits.jl b/src/traits.jl index ca01783..40d20da 100644 --- a/src/traits.jl +++ b/src/traits.jl @@ -65,12 +65,18 @@ with `learner`, or an associated model (object returned by `fit(learner, ...)`, first argument. Learner traits (methods for which `learner` is the *only* argument) are excluded. +To return actual functions, instead of symbols, use [`@functions`](@ref)` learner` +instead. + The returned tuple may include expressions like `:(DecisionTree.print_tree)`, which reference functions not owned by LearnAPI.jl. The understanding is that `learner` is a LearnAPI-compliant object whenever the return value is non-empty. +Do `LearnAPI.functions()` to list all possible elements of the return value owned by +LearnAPI.jl. + # Extended help # New implementations @@ -100,6 +106,7 @@ learner-specific ones. The LearnAPI.jl accessor functions are: $ACCESSOR_FUNCTIO (`LearnAPI.strip` is always included). """ +functions(::Any) = () functions() = ( :(LearnAPI.fit), :(LearnAPI.learner), @@ -114,8 +121,34 @@ functions() = ( :(LearnAPI.predict), :(LearnAPI.transform), :(LearnAPI.inverse_transform), + ACCESSOR_FUNCTIONS..., ) -functions(::Any) = () + +""" + @functions learner + +Return a tuple of functions that can be meaningfully applied with `learner`, or an +associated model, as the first argument. An "associated model" is an object returned by +`fit(learner, ...)`. Learner traits (methods for which `learner` is the *only* argument) +are excluded. + +``` +julia> @functions my_feature_selector +(fit, LearnAPI.learner, strip, obs, transform) + +``` + +New learner implementations should overload [`LearnAPI.functions`](@ref). + +See also [`LearnAPI.functions`](@ref). + +""" +macro functions(learner) + quote + exs = LearnAPI.functions(learner) + eval.(exs) + end |> esc +end """ LearnAPI.kinds_of_proxy(learner)