moving into docs

Author: pat-alt

docs/make.jl

@@ -1,15 +1,31 @@
-using Documenter
 using AlgorithmicRecourseDynamics
+using Documenter
+
+ex_meta = quote
+    # Import module(s):
+    using AlgorithmicRecourseDynamics
+end
+
+DocMeta.setdocmeta!(AlgorithmicRecourseDynamics, :DocTestSetup, ex_meta; recursive = true)
 
-makedocs(
-    sitename = "AlgorithmicRecourseDynamics",
-    format = Documenter.HTML(),
-    modules = [AlgorithmicRecourseDynamics]
+makedocs(;
+    modules = [AlgorithmicRecourseDynamics],
+    authors = "Patrick Altmeyer",
+    repo = "https://github.com/pat-alt/AlgorithmicRecourseDynamics.jl/blob/{commit}{path}#{line}",
+    sitename = "AlgorithmicRecourseDynamics.jl",
+    format = Documenter.HTML(;
+        prettyurls = get(ENV, "CI", "false") == "true",
+        canonical = "https://pat-alt.github.io/AlgorithmicRecourseDynamics.jl",
+        edit_link = "main",
+        assets = String[],
+    ),
+    pages = [
+        "🏠 Home" => "index.md",
+        "🎓 Research Paper" => [
+            "Overview" => "paper/index.md",
+        ],
+        "🧐 Reference" => "_reference.md",
+    ],
 )
 
-# Documenter can also automatically deploy documentation to gh-pages.
-# See "Hosting Documentation" and deploydocs() in the Documenter manual
-# for more information.
-#=deploydocs(
-    repo = "<repository url>"
-)=#
+deploydocs(; repo = "github.com/pat-alt/AlgorithmicRecourseDynamics.jl", devbranch = "main")

docs/src/_reference.md

@@ -0,0 +1,42 @@
+```@meta
+CurrentModule = AlgorithmicRecourseDynamics
+```
+
+# Reference
+
+In this reference you will find a detailed overview of the package API.
+
+> Reference guides are technical descriptions of the machinery and how to operate it. Reference material is information-oriented.
+>
+> --- [Diátaxis](https://diataxis.fr/reference/)
+
+In other words, you come here because you want to take a very close look at the code 🧐
+
+## Content
+
+```@contents
+Pages = ["_reference.md"]
+```
+
+## Index
+
+```@index
+```
+
+## Public Interface
+
+```@autodocs
+Modules = [
+    AlgorithmicRecourseDynamics
+]
+Private = false
+```
+
+## Internal functions
+
+```@autodocs
+Modules = [
+    AlgorithmicRecourseDynamics
+]
+Public = false
+```

docs/src/paper/Project.toml

@@ -0,0 +1,8 @@
+[deps]
+AlgorithmicRecourseDynamics = "3d1ede72-abb8-4340-bf8e-2ae06849b5ec"
+CounterfactualExplanations = "2f13d31b-18db-44c1-bc43-ebaf2cff0be0"
+Flux = "587475ba-b771-5e3f-ad9e-33799f191a9c"
+LaplaceRedux = "c52c1a26-f7c5-402b-80be-ba1e638ad478"
+MLJBase = "a7f614a8-145f-11e9-1d2a-a57a1082229d"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"

docs/src/paper/index.qmd

@@ -0,0 +1,26 @@
+---
+title: Endogenous Macrodynamics in Algorithmic Recourse
+subtitle: Research Paper
+--- 
+
+```@meta
+CurrentModule = ConformalPrediction
+```
+
+This part of the documentation is specific to the research paper "Endogenous Macrodynamics in Algorithmic Recourse". To allow for reproducibility of the results at the time of publication, there is a specific package environment linked to this part of the documentation that **will not be updated**. It can be activated as follows:
+
+```{julia}
+using Pkg; Pkg.activate("docs/src/paper")
+```
+
+
+The status of this package environment is shown below:
+
+```{julia}
+#| output: true
+
+Pkg.status()
+```
+
+
+

docs/src/paper/proof_of_concept.qmd

@@ -4,27 +4,38 @@ jupyter: julia-1.7
 ---
 
 ```{julia}
-using Pkg; Pkg.activate("dev")
-```
+#| echo: false
 
+# Environment:
+using Pkg; Pkg.activate("docs/src/paper")
 
-In this notebook we will use toy data to see how endogenous domain shifts and the resulting model shifts can have implications on the validity and cost of algorithmic recourse.
+# Deps:
+using CounterfactualExplanations
+using Flux
+using LaplaceRedux
+using MLJBase
+using Plots
+using Random
 
-```{julia}
-include("dev/utils.jl")
-using AlgorithmicRecourseDynamics
-using CounterfactualExplanations, Flux, Plots, PlotThemes, Random, LaplaceRedux, LinearAlgebra
+# Setup
+Random.seed!(1234)
 theme(:wong)
-output_path = output_dir("poc")
-www_path = www_dir("poc")
+include("docs/src/utils.jl")    # some helper functions
+output_path = output_dir("poc") # output directory for artifacts
+www_path = www_dir("poc")       # output directory for images
 ```
 
+To start with, we will look at a proof-of-concept that demonstrates the main observation underlying that paper is framed around. In particular, we will use synthetic data to see how endogenous domain shifts and the resulting model shifts can have implications on the validity and cost of algorithmic recourse.
+
 ## Classifiers
 
 ```{julia}
-using MLJ
 N = 1000
-X, ys = make_blobs(N, 2; centers=2, as_table=false, center_box=(-2 => 2), cluster_std=0.1)
+xmax = 2
+X, ys = make_blobs(
+    N, 2; 
+    centers=2, as_table=false, center_box=(-xmax => xmax), cluster_std=0.1
+)
 ys .= ys.==2
 X = X'
 xs = Flux.unstack(X,2)
@@ -35,65 +46,33 @@ counterfactual_data = CounterfactualData(X,ys')
 ### Logistic Regression
 
 ```{julia}
-using Flux
+n_epochs = 10
 model = Chain(Dense(2,1))
-M = FluxModel(model)
+Models.forward!(model, data; loss=:logitbinarycrossentropy, opt=:Adam, n_epochs=n_epochs)
 ```
 
-
 ```{julia}
-n_epochs = 10
-using AlgorithmicRecourseDynamics.Models
-M = Models.train(M,counterfactual_data; n_epochs=n_epochs)
+model = Laplace(model, likelihood=:classification)
+LaplaceRedux.fit!(model, data)      # fit Laplace Approximation
+optimize_prior!(model)              # optimize prior
+mod = LaplaceReduxModel(model)
 ```
 
 ```{julia}
-plt_nn = plot(M,counterfactual_data;zoom=0)
-savefig(plt_nn, joinpath(www_path, "nn_contour.png"))
-```
-
-![](../artifacts/upload/www/synthetic/nn_contour.png)
-
-### Laplace Redux
+#| output: true
+#| label: fig-model
+#| fig-cap: "The baseline model: contours indicate the predicted label; dots indicate observed data points."
 
-```{julia}
-λ = 0.1
-model_laplace = Laplace(M.model, λ=λ)
-LaplaceRedux.fit!(model_laplace, data)
+plt_original = plot(mod, counterfactual_data; zoom=0, colorbar=false, title="(a)")
 ```
 
-```{julia}
-M_laplace = Models.LaplaceModel(model_laplace)
-```
-
-```{julia}
-plt_laplace = plot(M_laplace, counterfactual_data;zoom=0)
-savefig(plt_laplace, joinpath(www_path, "la_contour.png"))
-```
-
-![](../artifacts/upload/www/synthetic/la_contour.png)
-
 ## Single Round
 
-```{julia}
-# Models:
-models = (Bayesian=M_laplace, Plugin=M)
-# Generators:
-generators = (
-    Greedy=GreedyGenerator(loss=:logitbinarycrossentropy), 
-    Generic=GenericGenerator(loss=:logitbinarycrossentropy),
-    REVISE=REVISEGenerator(loss=:logitbinarycrossentropy)
-)
-```
-
 ### Generate counterfactual
 
 ```{julia}
-cb = false
 γ = 0.75
-mod = M_laplace
-gen = generators[:Greedy]
-plt_original = plot(mod,counterfactual_data;zoom=0,colorbar=false,title="(a)")
+gen = GenericGenerator(;decision_threshold=γ)
 ```
 
 ```{julia}
@@ -105,7 +84,7 @@ y′ = copy(ys)
 using CounterfactualExplanations.Counterfactuals: counterfactual, counterfactual_label
 for i in chosen
     x = X[:,i]
-    outcome = generate_counterfactual(x, 1, counterfactual_data, mod, gen,γ=γ)
+    outcome = generate_counterfactual(x, 1, counterfactual_data, mod, gen)
     X′[:,i] = counterfactual(outcome)
     y′[i] = first(counterfactual_label(outcome))
 end
@@ -116,7 +95,9 @@ plt_single = plot(mod,counterfactual_data′;zoom=0,colorbar=false,title="(b)")
 ### Retrain
 
 ```{julia}
-mod = Models.train(mod, counterfactual_data′; n_epochs=n_epochs)
+Models.forward!(mod.model.model, data; loss=:logitbinarycrossentropy, opt=:Adam, n_epochs=n_epochs)
+LaplaceRedux.fit!(mod.model, data)      # fit Laplace Approximation
+optimize_prior!(mod.model)              # optimize prior
 plt_single_retrained = plot(mod,counterfactual_data′;zoom=0,colorbar=false,title="(c)")
 ```
 
@@ -129,10 +110,12 @@ while i <= 10
     candidates = findall(y′.==0)
     chosen = rand(candidates, Int(round(μ*length(candidates))))
     H₀ = mod.model.H # use posterior as new prior
-    mod = Models.train(mod, counterfactual_data′; n_epochs=n_epochs, H₀=H₀)
+    Models.forward!(mod.model.model, data; loss=:logitbinarycrossentropy, opt=:Adam, n_epochs=n_epochs)
+    LaplaceRedux.fit!(mod.model, data)      # fit Laplace Approximation
+    optimize_prior!(mod.model)              # optimize prior
     for i in chosen
         x = X′[:,i]
-        outcome = generate_counterfactual(x, 1, counterfactual_data, mod, gen; γ=γ)
+        outcome = generate_counterfactual(x, 1, counterfactual_data, mod, gen)
         X′[:,i] = counterfactual(outcome)
         y′[i] = first(counterfactual_label(outcome))
     end
@@ -143,7 +126,12 @@ plt_single_repeat = plot(mod,counterfactual_data′;zoom=0,colorbar=false,title=
 
 ```{julia}
 plt = plot(plt_original, plt_single, plt_single_retrained, plt_single_repeat, layout=(1,4), legend=false, axis=nothing, size=(600,165))
-savefig(plt, joinpath(www_path, "poc.png"))
+# savefig(plt, joinpath(www_path, "poc.png"))
 ```
 
+```{julia}
+
+```
+
+
 ![](../artifacts/upload/www/synthetic/poc.png)

docs/src/utils.jl

@@ -0,0 +1,41 @@
+"""
+    output_dir(dir="")
+
+Sets up the directory to save computational outputs and returns the path.
+"""
+function output_dir(dir="")
+    root_ = "dev/artifacts/upload/output"
+    output_dir = joinpath(root_, dir)
+    if !isdir(output_dir)
+        mkpath(output_dir)
+    end
+    return output_dir
+end
+
+"""
+    www_dir(dir="")
+
+Sets up the directory to save images and returns the path.
+"""
+function www_dir(dir="")
+    root_ = "dev/artifacts/upload/www"
+    www_dir = joinpath(root_, dir)
+    if !isdir(www_dir)
+        mkpath(www_dir)
+    end
+    return www_dir
+end
+
+"""
+    data_dir(dir="")
+
+Sets up the directory to save images and returns the path.
+"""
+function data_dir(dir="")
+    root_ = "dev/artifacts/upload/data"
+    data_dir = joinpath(root_, dir)
+    if !isdir(data_dir)
+        mkpath(data_dir)
+    end
+    return data_dir
+end