{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using the CLI\n",
    "\n",
    "Aequitas command line interface (CLI) allows you to generate 'The Bias Report' with one line in the terminal. \n",
    "At minimum enter:\n",
    "\n",
    "`aequitas-report --input <file>`\n",
    "\n",
    "The command line interface allows the user to produce reports with more flexability than the webapp without coding in Python. Here we detail the command and provide use cases with different types of data inputs.\n",
    "\n",
    "\n",
    "## CLI use cases\n",
    "\n",
    "### Use with binary scores and csv\n",
    "This use case is presented in [getting started with aequitas-report](./30_seconds_aequitas.html).\n",
    "```\n",
    "aequitas-report --input <csv with binary scores>\n",
    "```\n",
    "__Input data__:\n",
    "Use when the input data has binary 0/1 scores.\n",
    "\n",
    "| score     | label_value| race | sex | age | income|\n",
    "| --------- |------------| -----| --- | ------- | ----|\n",
    "|   0       | 1          | African-American | Female | 55 | 78000 |\n",
    "|   1       | 1          | Caucasian | Female | 43 | 34000|\n",
    "\n",
    "__Configs__: With no configs, the reference group would be determined automatically based on the majority group for a given attribute and all metrics will be calculated.\n",
    "\n",
    "\n",
    "### Use with continuous scores or risk scores\n",
    "```\n",
    "aequitas-report --input <csv with continuous scores> --config configs_example.yaml\n",
    "```\n",
    "__Input data__:\n",
    "\n",
    "Use when the input data has continuous scores.\n",
    "\n",
    "\n",
    "| score     | label_value| race | sex | age |\n",
    "| --------- |------------| -----| --- | ------- | ----|\n",
    "|  .35      | 1        | Asian-American | Male | <30|\n",
    "|   .68       | 0          | Native American | Female | 30-50 | \n",
    "\n",
    "\n",
    "or the input data has risk scores.\n",
    "\n",
    "| score     | label_value| race | sex | age |\n",
    "| --------- |------------| -----| --- | ------- | ----|\n",
    "|  3      | 1          | Asian-American | Male | <30|\n",
    "|   8       | 0          | Native American | Female | 30-50 | \n",
    "\n",
    "__Configs__: When scores are continuous, we have flexibility in who is classified in the positive or negative class based on a thresholds. (Described [here](config.html) or see [example](https://github.com/dssg/aequitas/blob/master/src/aequitas_cli/configs_example.yaml)).\n",
    "\n",
    "### Use with binary scores from a database\n",
    "```\n",
    "aequitas-report --config configs_database_example.yaml --create-tables\n",
    "```\n",
    "__Input data__: Pulled from database based on command in config file.\n",
    "\n",
    "__Configs__: In the configuration file, you must provide database credentials and a SQL query.\n",
    "Described [here](config.html) or see [example](https://github.com/dssg/aequitas/blob/master/src/aequitas_cli/configs_database_example.yaml).\n",
    "\n",
    "\n",
    "## CLI flags\n",
    "### `--input   < path to .csv file >`\n",
    "\n",
    "Absolute filepath for input dataset in csv format. If no input is provided we assume there is a db configuration in the configs.yaml file.\n",
    "\n",
    "### `--config   < path to config.yaml >`\n",
    "\n",
    "To change default behavior uniformly across applications use a configuration file.\n",
    "\n",
    "### `--output-folder <path to folder>`\n",
    "\n",
    "Folder name to be created inside aequitas.\n",
    "\n",
    "### `--create-tables`\n",
    "\n",
    "If you are working with a database, the flag tells aequitas to create table from scratch and drop existing tables. Otherwise, it will append aequitas output. Note, database functionality must be configured in the config.yaml file. \n",
    "\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}