docs tweaks (#24)

* maxnet is registered

* fully implement MLJ (#22)

* add mlj docstring

* test with MLJTestInterface

* throw a helpful error if input data only has one class

* mljtestinterface is not a dep (oops)

* move allequal error to main function

* fix allequal error

* fix tests

* add MLJBase as docs dep

* fix mlj doctest

* attempt fix of multiclass printing

* use @example instead of jldoctest

* test for no failures in mlj interface test

* maxnet is registered

* more MLJ docs

* small tweaks to core function docs

* add check scitypes

Co-authored-by: Anthony Blaom, PhD <[email protected]>

* Clogloglink is from Maxnet

Co-authored-by: Anthony Blaom, PhD <[email protected]>

---------

Co-authored-by: Anthony Blaom, PhD <[email protected]>

Author: tiemvanderdeure

docs/src/usage/quickstart.md

@@ -3,10 +3,10 @@ CurrentModule = Maxnet
 ```
 
 ## Installation
-Maxnet.jl is not yet registered - install by running
+Install the latest version of Maxnet.jl by running
 ```julia
 ]
-add https://github.com/tiemvanderdeure/Maxnet.jl 
+add Maxnet
 ```
 
 ## Basic usage
@@ -31,7 +31,7 @@ There are numerous settings that can be tweaked to change the model fit. These a
 ### Model settings
 The two most important settings to change when running Maxnet is the feature classes selected and the regularization factor.
 
-By default, the feature classes selected depends on the number of presence points, see [Maxnet.default_features](@ref). To set them manually, specify the `features` keyword using either a `Vector` of `AbstractFeatureClass`, or a `string`, where `l` represents `LinearFeature` and `CategoricalFeature`, `q` represents `QuadraticFeature`, `p` represents `ProductFeature`, `t` represents `ThresholdFeature` and `h` represents `HingeFeature`. 
+By default, the feature classes selected depends on the number of presence points, see [default_features](@ref). To set them manually, specify the `features` keyword using either a `Vector` of `AbstractFeatureClass`, or a `string`, where `l` represents `LinearFeature` and `CategoricalFeature`, `q` represents `QuadraticFeature`, `p` represents `ProductFeature`, `t` represents `ThresholdFeature` and `h` represents `HingeFeature`. 
 
 For example:
 ```julia

src/maxnet_function.jl

@@ -16,9 +16,11 @@
 - `features`: Either a `Vector` of `AbstractFeatureClass` to be used in the model, 
     or a `String` where "l" = linear and categorical, "q" = quadratic, "p" = product, "t" = threshold, "h" = hinge (e.g. "lqh"); or
     By default, the features are based on the number of presences are used. See [`default_features`](@ref)
-- `regularization_multiplier`: A constant to adjust regularization, where a higher `regularization_multiplier` results in a higher penalization for features
-- `regularization_function`: A function to compute a regularization for each feature. A default `regularization_function` is built in.
-- `addsamplestobackground`: A boolean, where `true` adds the background samples to the predictors. Defaults to `true`.
+- `regularization_multiplier`: A constant to adjust regularization, where a higher `regularization_multiplier` results in a higher 
+    penalization for features and therefore less overfitting.
+- `regularization_function`: A function to compute a regularization for each feature. A default `regularization_function` is built in
+    and should be used in most cases.
+- `addsamplestobackground`: Whether to add presence values to the background. Defaults to `true`.
 - `n_knots`: the number of knots used for Threshold and Hinge features. Defaults to 50. Ignored if there are neither Threshold nor Hinge features
 - `weight_factor`: A `Float64` value to adjust the weight of the background samples. Defaults to 100.0.
 - `kw...`: Further arguments to be passed to `GLMNet.glmnet`
@@ -32,6 +34,7 @@ using Maxnet
 p_a, env = Maxnet.bradypus();
 bradypus_model = maxnet(p_a, env; features = "lq")
 
+# Output
 Fit Maxnet model
 Features classes: Maxnet.AbstractFeatureClass[LinearFeature(), CategoricalFeature(), QuadraticFeature()]
 Entropy: 6.114650341746531

src/mlj_interface.jl

@@ -46,16 +46,66 @@ MMI.metadata_model(
 """
 $(MMI.doc_header(MaxnetBinaryClassifier))
 
-The keywords `link`, and `clamp` are passed to [`predict`](@ref), while all other keywords are passed to [`maxnet`](@ref).
-See the documentation of these functions for the meaning of these parameters and their defaults.
+# Training data
+
+In MLJ or MLJBase, bind an instance `model` to data with
+
+    mach = machine(model, X, y)
+
+where
+
+- `X`: any table of input features (eg, a `DataFrame`) whose columns
+  each have one of the following element scitypes: `Continuous` or `<:Multiclass`. Check
+  `scitypes` with `schema(X)`.
+
+- `y`: is the target, which can be any `AbstractVector` whose element
+  scitype is `<:Binary`. The first class should refer to background values,
+  and the second class to presence values.
+
+# Hyper-parameters
+
+- `features`: Specifies which features classes to use in the model, e.g. "lqh" for linear, quadratic and hinge features. 
+    See also [Maxnet.maxnet](@ref)
+- `regularization_multiplier = 1.0`: 'Adjust how tight the model will fit. Increasing this will reduce overfitting.
+- `regularization_function`: A function to compute the regularization of each feature class. Defaults to `Maxnet.default_regularization`
+- `addsamplestobackground = true`: Controls wether to add presence values to the background.
+- `n_knots = 50`: The number of knots used for Threshold and Hinge features. A higher number gives more flexibility for these features.
+- `weight_factor = 100.0`: A `Float64` value to adjust the weight of the background samples.
+- `link = Maxnet.CloglogLink()`: The link function to use when predicting. See `Maxnet.predict` 
+- `clamp = false`: Clamp values passed to `MLJBase.predict` to the range the model was trained on.
+
+# Operations
+
+- `predict(mach, Xnew)`: return predictions of the target given
+  features `Xnew` having the same scitype as `X` above. Predictions are 
+  probabilistic and can be interpreted as the probability of presence.
+
+# Fitted Parameters
+
+The fields of `fitted_params(mach)` are:
+
+- `fitresult`: A `Tuple` where the first entry is the `Maxnet.MaxnetModel` returned by the Maxnet algorithm
+    and the second the entry is the classes of `y`
+
+# Report
+
+The fields of `report(mach)` are:
+
+- `selected_variables`: A `Vector` of `Symbols` of the variables that were selected.
+- `selected_features`: A `Vector` of `Maxnet.ModelMatrixColumn` with the features that were selected.
+- `complexity`: the number of selected features in the model.
+
 
 # Example
+
 ```@example
-using MLJBase
+using MLJBase, Maxnet
 p_a, env = Maxnet.bradypus()
+y = coerce(p_a, Binary)
+X = coerce(env, Count => Continuous)
 
-mach = machine(MaxnetBinaryClassifier(features = "lqp"), env, categorical(p_a), scitype_check_level = 0)
-fit!(mach, verbosity = 0)
+mach = machine(MaxnetBinaryClassifier(features = "lqp"), X, y)
+fit!(mach)
 yhat = MLJBase.predict(mach, env)
 
 ```