+ "markdown": "```@meta\nCurrentModule = AlgorithmicRecourseDynamics\n```\n\n# AlgorithmicRecourseDynamics\n\nDocumentation for [AlgorithmicRecourseDynamics.jl](https://github.com/pat-alt/AlgorithmicRecourseDynamics.jl).\n\n\n\n`AlgorithmicRecourseDynamics.jl` is a small package for modeling Algorithmic Recourse Dynamics. It builds on `CounterfactualExplanations`, a package for generating counterfactual explanations.\n\n## Basic Usage\n\nBelow we first generate some synthetic data for a binary classification task and instantiate an instance of `CounterfactualData`.\n\n::: {.cell execution_count=2}\n``` {.julia .cell-code}\nN = 1000\nxmax = 2\nX, ys = make_blobs(\n N, 2; \n centers=2, as_table=false, center_box=(-xmax => xmax), cluster_std=0.1\n)\nys .= ys.==2\nX = X'\ncounterfactual_data = CounterfactualData(X,ys')\n```\n:::\n\n\nWe then define a simple model for the task and prepare it for use with `CounterfactualExplanations.jl`:\n\n::: {.cell execution_count=3}\n``` {.julia .cell-code}\nn_epochs = 100\nmodel = Chain(Dense(2,1))\nmod = FluxModel(model)\n```\n:::\n\n\nTo generate algorithmic recourse, we will use a simple generic generator:\n\n::: {.cell execution_count=4}\n``` {.julia .cell-code}\ngenerator = GenericGenerator()\n```\n:::\n\n\nFinally we train our model on a subset of the data. The chart below shows the results.\n\n::: {.cell execution_count=5}\n``` {.julia .cell-code}\ndata_train, data_test = Data.train_test_split(counterfactual_data)\nModels.train(mod, data_train; n_epochs=n_epochs)\nplt_original = plot(mod, counterfactual_data; zoom=0, colorbar=false)\ndisplay(plt_original)\n```\n\n::: {.cell-output .cell-output-display}\n{}\n:::\n:::\n\n\n### Simulation\n\nTo model the dynamics of algorithmic recourse, we use simulations, in which we repeatedly select as subset of individuals from the non-target class, generate and implement recourse for all of them and finally retrain the model. To set this experiment up, we can use the code below:\n\n::: {.cell execution_count=6}\n``` {.julia .cell-code}\nmodels = Dict(:mymodel => mod)\ngenerators = Dict(:wachter => generator)\nexperiment = set_up_experiment(data_train, data_test, models, generators)\n```\n:::\n\n\nFinally, we just run the experiment using default parameter settings that specify the number of rounds, the proportion of individuals to select for recourse and related aspects:\n\n::: {.cell execution_count=7}\n``` {.julia .cell-code}\nrun!(experiment)\n```\n\n::: {.cell-output .cell-output-display execution_count=8}\n\\begin{tabular}{r|ccccccccc}\n\t& value & p\\_value & name & scope & k & n & model & generator & \\\\\n\t\\hline\n\t& Float64 & Float64? & Symbol & Symbol & Int64 & Int64 & Symbol & Symbol & \\\\\n\t\\hline\n\t1 & -0.000308861 & \\emph{missing} & mmd & domain & 1 & 0 & mymodel & wachter & $\\dots$ \\\\\n\t2 & 0.0 & \\emph{missing} & perturbation & model & 1 & 0 & mymodel & wachter & $\\dots$ \\\\\n\t3 & -0.000865245 & \\emph{missing} & mmd & model & 1 & 0 & mymodel & wachter & $\\dots$ \\\\\n\t4 & -0.000790169 & \\emph{missing} & mmd\\_grid & model & 1 & 0 & mymodel & wachter & $\\dots$ \\\\\n\t5 & 0.0 & \\emph{missing} & disagreement & model & 1 & 0 & mymodel & wachter & $\\dots$ \\\\\n\t6 & 0.0 & \\emph{missing} & decisiveness & model & 1 & 0 & mymodel & wachter & $\\dots$ \\\\\n\t7 & 0.0 & \\emph{missing} & model\\_performance & model & 1 & 0 & mymodel & wachter & $\\dots$ \\\\\n\t8 & 0.0859171 & 0.0 & mmd & domain & 1 & 10 & mymodel & wachter & $\\dots$ \\\\\n\t9 & 2.29844 & \\emph{missing} & perturbation & model & 1 & 10 & mymodel & wachter & $\\dots$ \\\\\n\t10 & -0.000654647 & 1.0 & mmd & model & 1 & 10 & mymodel & wachter & $\\dots$ \\\\\n\t11 & 0.0867767 & 0.0 & mmd\\_grid & model & 1 & 10 & mymodel & wachter & $\\dots$ \\\\\n\t12 & 0.0 & \\emph{missing} & disagreement & model & 1 & 10 & mymodel & wachter & $\\dots$ \\\\\n\t13 & 0.216456 & \\emph{missing} & decisiveness & model & 1 & 10 & mymodel & wachter & $\\dots$ \\\\\n\t14 & 0.0 & \\emph{missing} & model\\_performance & model & 1 & 10 & mymodel & wachter & $\\dots$ \\\\\n\t15 & -0.000308861 & \\emph{missing} & mmd & domain & 2 & 0 & mymodel & wachter & $\\dots$ \\\\\n\t16 & 0.0 & \\emph{missing} & perturbation & model & 2 & 0 & mymodel & wachter & $\\dots$ \\\\\n\t17 & -0.000865245 & \\emph{missing} & mmd & model & 2 & 0 & mymodel & wachter & $\\dots$ \\\\\n\t18 & -0.000791949 & \\emph{missing} & mmd\\_grid & model & 2 & 0 & mymodel & wachter & $\\dots$ \\\\\n\t19 & 0.0 & \\emph{missing} & disagreement & model & 2 & 0 & mymodel & wachter & $\\dots$ \\\\\n\t20 & 0.0 & \\emph{missing} & decisiveness & model & 2 & 0 & mymodel & wachter & $\\dots$ \\\\\n\t21 & 0.0 & \\emph{missing} & model\\_performance & model & 2 & 0 & mymodel & wachter & $\\dots$ \\\\\n\t22 & 0.105827 & 0.0 & mmd & domain & 2 & 10 & mymodel & wachter & $\\dots$ \\\\\n\t23 & 2.39989 & \\emph{missing} & perturbation & model & 2 & 10 & mymodel & wachter & $\\dots$ \\\\\n\t24 & -0.000623466 & 1.0 & mmd & model & 2 & 10 & mymodel & wachter & $\\dots$ \\\\\n\t25 & 0.0969255 & 0.0 & mmd\\_grid & model & 2 & 10 & mymodel & wachter & $\\dots$ \\\\\n\t26 & 0.0 & \\emph{missing} & disagreement & model & 2 & 10 & mymodel & wachter & $\\dots$ \\\\\n\t27 & 0.2318 & \\emph{missing} & decisiveness & model & 2 & 10 & mymodel & wachter & $\\dots$ \\\\\n\t28 & 0.0 & \\emph{missing} & model\\_performance & model & 2 & 10 & mymodel & wachter & $\\dots$ \\\\\n\t29 & -0.000308861 & \\emph{missing} & mmd & domain & 3 & 0 & mymodel & wachter & $\\dots$ \\\\\n\t30 & 0.0 & \\emph{missing} & perturbation & model & 3 & 0 & mymodel & wachter & $\\dots$ \\\\\n\t$\\dots$ & $\\dots$ & $\\dots$ & $\\dots$ & $\\dots$ & $\\dots$ & $\\dots$ & $\\dots$ & $\\dots$ & \\\\\n\\end{tabular}\n\n:::\n:::\n\n\nThe chart below shows the data and predictions at the end of the simulation:\n\n::: {.cell execution_count=8}\n``` {.julia .cell-code}\nnew_data = experiment.recourse_systems[1][1].data\nnew_model = experiment.recourse_systems[1][1].model\nplt_original = plot(new_model, new_data; zoom=0, colorbar=false)\n```\n\n::: {.cell-output .cell-output-display execution_count=9}\n{}\n:::\n:::\n\n\n## Related Research Paper 📝\n\nThe package was developed for a research project that investigates the dynamics of various counterfactual generators. You can find the details [here](https://github.com/pat-alt/endogenous-macrodynamics-in-algorithmic-recourse).\n\n",
0 commit comments