Initialization of CF doc

doc/source/methods/CF.ipynb

@@ -66,6 +66,74 @@
     "## Usage"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Initialization\n",
+    "The counterfactual (CF) explainer method works on fully black-box models, meaning they can work with arbitrary functions that take arrays and return arrays. However, if the user has access to a full TensorFlow (TF) or Keras model, this can be passed in as well to take advantage of the automatic differentiation in TF to speed up the search. This section describes the initialization for a TF/Keras model, for fully black-box models refer to [numerical gradients](#Numerical-Gradients).\n",
+    "\n",
+    "Similar to other methods, we use TensorFlow (TF) internally to solve the optimization problem defined above, thus we need to run the counterfactual explainer within a TF session, for a Keras model once it has been loaded we can just get it:\n",
+    "\n",
+    "```python\n",
+    "model = load_model('my_model.h5')\n",
+    "sess = K.get_session()\n",
+    "```\n",
+    "\n",
+    "Then we can initialize the counterfactual object:\n",
+    "\n",
+    "```python\n",
+    "shape = (1,) + x_train.shape[1:]\n",
+    "cf = CounterFactual(sess, model, shape, distance_fn='l1', target_proba=1.0,\n",
+    "                    target_class='other', max_iter=1000, early_stop=50, lam_init=1e-1,\n",
+    "                    max_lam_steps=10, tol=0.05, learning_rate_init=0.1,\n",
+    "                    feature_range=(-1e10, 1e10), eps=0.01, init='identity',\n",
+    "                    decay=True, write_dir=None, debug=False)\n",
+    "```\n",
+    "\n",
+    "Besides passing the session and the model, we set a number of **hyperparameters** ...\n",
+    "\n",
+    "... **general**:\n",
+    "* `shape`: shape of the instance to be explained, starting with batch dimension. Currently only single explanations are supported, so the batch dimension should be equal to 1.\n",
+    "\n",
+    "* `feature_range`: global or feature-wise min and max values for the perturbed instance.\n",
+    "\n",
+    "* `write_dir`: write directory for Tensorboard logging of the loss terms. It can be helpful when tuning the hyperparameters for your use case. It makes it easy to verify that e.g. not 1 loss term dominates the optimization, that the number of iterations is OK etc. You can access Tensorboard by running `tensorboard --logdir {write_dir}` in the terminal.\n",
+    "\n",
+    "* `debug`: flag to enable/disable writing to Tensorboard\n",
+    "\n",
+    "... related to the **optimizer**:\n",
+    "\n",
+    "* `max_iterations`: number of loss optimization steps for each value of $\\lambda$; the multiplier of the distance loss term.\n",
+    "\n",
+    "* `learning_rate_init`: initial learning rate, follows linear decay.\n",
+    "\n",
+    "* `decay`: flag to disable learning rate decay if desired\n",
+    "\n",
+    "* `early_stop`: early stopping criterion for the search. If no counterfactuals are found for this many steps or if this many counterfactuals are found in a row we change $\\lambda$ accordingly and continue the search.\n",
+    "* `init`: how to initialize the search, currently only `\"identity\"` is supported meaning the search starts from the original instance.\n",
+    "\n",
+    "\n",
+    "... related to the **objective function**:\n",
+    "\n",
+    "* `distance_fn`: distance function between the test instance $X$ and the proposed counterfactual $X^\\prime$, currently only `\"l1\"` is supported.\n",
+    "\n",
+    "* `target_proba`: desired target probability for the returned counterfactual instance. Defaults to `1.0`, but it could be useful to reduce it to allow a looser definition of a counterfactual instance.\n",
+    "\n",
+    "* `tol`: the tolerance within the `target_proba`, this works in tandem with `target_proba` to specify a range of acceptable predicted probability values for the counterfactual.\n",
+    "\n",
+    "* `target_class`: desired target class for the returned counterfactual instance. Can be either an integer denoting the specific class membership or the string `other` which will find a counterfactual instance whose predicted class is anything other than the class of the test instance.\n",
+    "\n",
+    "* `lam_init`: initial value of the hyperparameter $\\lambda$. This is set to a high value $\\lambda=1e^{-1}$ and annealed during the search to find good bounds for $\\lambda$ and for most applications should be fine to leave as default.\n",
+    "\n",
+    "* `max_lam_steps`: the number of steps (outer loops) to search for with a different value of $\\lambda$.\n",
+    "\n",
+    "\n",
+    "\n",
+    "\n",
+    "While the default values for the loss term coefficients worked well for the simple examples provided in the notebooks, it is recommended to test their robustness for your own applications. "
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},