docs (#15)

add docs

Author: tiemvanderdeure

README.md

@@ -1,11 +1,24 @@
-# maxnet
-This is a pure Julia implementation of the [maxnet algorithm](https://github.com/mrmaxent/maxnet).
-
-Maxnet is closely related to the java MaxEnt application, which is widely used in species distribution modelling. It was developped by Steven Philips. Please see [this publication](https://doi.org/10.1111/ecog.03049) for more details about the maxnet algorithm.
-
-Also see the Maxent page on the site of the [American Museum for Natural History](https://biodiversityinformatics.amnh.org/open_source/maxent/)
+# Maxnet
 
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://tiemvanderdeure.github.io/Maxnet.jl/stable/)
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://tiemvanderdeure.github.io/Maxnet.jl/dev/)
 [![Build Status](https://github.com/tiemvanderdeure/Maxnet.jl/actions/workflows/CI.yml/badge.svg?branch=master)](https://github.com/tiemvanderdeure/Maxnet.jl/actions/workflows/CI.yml?query=branch%3Amaster)
 [![Coverage](https://codecov.io/gh/tiemvanderdeure/Maxnet.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/tiemvanderdeure/Maxnet.jl)
+
+This is a Julia implementation of the [maxnet algorithm](https://github.com/mrmaxent/maxnet), with all core functionality in the original R package.
+
+Maxnet transforms input data in various ways and then uses the GLMnet algorithm to fit a lasso path, selecting the best variables and transformations.
+
+Maxnet is closely related to the Java MaxEnt application, which is widely used in species distribution modelling. Maxnet was introduced in [this publication](https://doi.org/10.1111/ecog.03049), which goes more into details about the algorithm.
+
+Also see the Maxent page on the site of the [American Museum for Natural History](https://biodiversityinformatics.amnh.org/open_source/maxent/).
+
+A basic example, using a toy dataset included in the package:
+```julia
+using Maxnet
+p_a, env = Maxnet.bradypus()
+bradypus_model = maxnet(p_a, env)
+prediction = predict(bradypus_model, env)
+```
+
+Maxnet integrates with [MLJ](https://github.com/alan-turing-institute/MLJ.jl) through the `MaxnetBinaryClassifier` type.

docs/make.jl

@@ -11,11 +11,15 @@ makedocs(;
     format=Documenter.HTML(;
         prettyurls=get(ENV, "CI", "false") == "true",
         canonical="https://tiemvanderdeure.github.io/Maxnet.jl",
-        edit_link="master",
         assets=String[],
     ),
     pages=[
         "Home" => "index.md",
+        "Usage" => Any[
+            "Quick start" => "usage/quickstart.md",
+            "MLJ" => "usage/mlj.md",
+        ],
+        "API reference" => "reference/api.md"
     ],
 )
 

docs/src/index.md

@@ -3,12 +3,21 @@ CurrentModule = Maxnet
 ```
 
 # Maxnet
+[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://tiemvanderdeure.github.io/Maxnet.jl/stable/)
+[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://tiemvanderdeure.github.io/Maxnet.jl/dev/)
+[![Build Status](https://github.com/tiemvanderdeure/Maxnet.jl/actions/workflows/CI.yml/badge.svg?branch=master)](https://github.com/tiemvanderdeure/Maxnet.jl/actions/workflows/CI.yml?query=branch%3Amaster)
+[![Coverage](https://codecov.io/gh/tiemvanderdeure/Maxnet.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/tiemvanderdeure/Maxnet.jl)
+
+
+This is a Julia implementation of the [maxnet algorithm](https://github.com/mrmaxent/maxnet), with all core functionality in the original R package.
+
+Maxnet transforms input data in various ways and then uses the GLMnet algorithm to fit a lasso path, selecting the best variables and transformations.
+
+Maxnet is closely related to the Java MaxEnt application, which is widely used in species distribution modelling. It was developped by Steven Philips. See [this publication](https://doi.org/10.1111/ecog.03049) for more details about maxnet.
+
+Also see the Maxent page on the site of the [American Museum for Natural History](https://biodiversityinformatics.amnh.org/open_source/maxent/).
 
 Documentation for [Maxnet](https://github.com/tiemvanderdeure/Maxnet.jl).
 
 ```@index
 ```
-
-```@autodocs
-Modules = [Maxnet]
-```

docs/src/reference/api.md

@@ -0,0 +1,22 @@
+```@meta
+CurrentModule = Maxnet
+```
+
+# API
+
+## Index
+```@index
+```
+
+## Functions
+```@autodocs
+Modules = [Maxnet]
+Order = [:function]
+```
+
+## Types
+```@autodocs
+Modules = [Maxnet]
+Order = [:type]
+```
+

docs/src/usage/mlj.md

@@ -0,0 +1,41 @@
+```@meta
+CurrentModule = Maxnet
+```
+
+# Integration with MLJ
+Maxnet.jl integrates with the MLJ ecosystem.
+
+See [MLJs project page](https://github.com/alan-turing-institute/MLJ.jl) for more info about MLJ.
+
+To use Maxnet with MLJ, initialise a model by calling [`MaxnetBinaryClassifier`](@ref), which accepts any arguments otherwise passed to [`maxnet`]. The model can then be used to construct MLJ's `machine`.
+
+For example:
+
+```julia
+using Maxnet: MaxnetBinaryClassifier, bradypus
+using MLJBase
+using CategoricalArrays
+
+# sample data
+y, X = bradypus()
+
+# define a model
+model = MaxnetBinaryClassifier(features = "lq")
+
+# construct a machine
+mach = machine(model, X, categorical(y))
+
+# partition data
+train, test = partition(eachindex(y), 0.7, shuffle=true)
+
+# fit the machine to the data
+fit!(mach; rows = train)
+
+# predict on test data
+pred_test = predict(mach; rows = test)
+
+# predict on some new dataset
+pred = predict(mach, X)
+```
+
+

docs/src/usage/quickstart.md

@@ -0,0 +1,48 @@
+```@meta
+CurrentModule = Maxnet
+```
+
+## Installation
+Maxnet.jl is not yet registered - install by running
+```julia
+]
+add https://github.com/tiemvanderdeure/Maxnet.jl 
+```
+
+## Basic usage
+### Fit a model
+Use the `maxnet` function to generate a model. `maxnet` takes a `BitVector` as its first arguments, where `true` encodes presences points and `false` background points. As its second argument, it takes any `Tables.jl`-compatible data structure with predictor variables. Categorical variables are treated differently than numeric variables and must be a `CategoricalVector`. Keyword arguments are used to tweak model settings.
+
+`predict` takes a model generated by `maxnet` and any `Tables.jl`-compatible data structure.
+
+Maxnet.jl comes with a sample dataset of presences and background points for the sloth species _Bradypus variegatus_ (see [Philips et al., 2006](https://doi.org/10.1016/j.ecolmodel.2005.03.026) for details).
+
+The following code fits a maxnet model for _Bradypus variegatus_ with default settings and generates the predicted suitability at each point.
+
+```julia
+using Maxnet
+p_a, env = Maxnet.bradypus()
+bradypus_model = maxnet(p_a, env)
+prediction = predict(bradypus_model, env)
+```
+
+There are numerous settings that can be tweaked to change the model fit. These are documentated in the documentatoin for the `maxnet`(@ref) and `Maxnet.predict`(@ref) functions.
+
+### 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`. 
+
+For example:
+```julia
+model1 = maxnet(p_a, env; features = [LinearFeature(), CategoricalFeature(), QuadraticFeature()])
+model2 = maxnet(p_a, env; features = "lqph")
+```
+
+The regularization multiplier controls how much the algorithms penalizes complex models. A higher regularization multiplier will result in a simpler model with fewer features.
+
+```julia
+model3 = maxnet(p_a, env; features = "lqph", regularization_multiplier = 10.0)
+```
+
+The number of features selected is shown when a model is printed in the REPL and can be accessed using `complexity`. Here `complexity(model2)` gives `48` and `complexity(model3)` gives `13`.