examples/advanced/federated-statistics/df_stats.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "26cb3afa",
   "metadata": {
    "tags": []
   },
   "source": [
    "# Data Frame Federated Statistics \n",
    "\n",
    "In this example, we will show how to generate federated statistics for data that can be represented as Pandas Data Frame.\n",
    "\n",
    "## Set Up NVFLARE\n",
    "\n",
    "Follow [Getting Started](https://nvflare.readthedocs.io/en/main/getting_started.html) to set up a virtual environment and install NVFLARE.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "64a17f22-5667-4f99-b4f6-d49116db74b0",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Install requirements\n",
    "First, install the required packages:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7c8969bf-d010-42b5-a807-0808922402d6",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%pip install -r df_stats/requirements.txt"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "94faaa6b-08fd-485c-87d5-53b4520177fe",
   "metadata": {
    "tags": []
   },
   "source": [
    "\n",
    "## Prepare data\n",
    "\n",
    "In this example, we are using UCI (University of California, Irvine) [adult dataset](https://archive.ics.uci.edu/dataset/2/adult)\n",
    "The original dataset has already contains \"training\" and \"test\" datasets. Here we simply assume that \"training\" and test data sets are belong to different clients.\n",
    "so we assigned the training data and test data into two clients.\n",
    " \n",
    "Now we use data utility to download UCI datasets to separate client package directory to /tmp/nvflare/data/ directory.\n",
    "Please note that the UCI's website may experience occasional downtime.\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e1ea959f-7282-4e55-bb26-11524ec47e99",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from df_stats.utils.prepare_data import prepare_data\n",
    "\n",
    "prepare_data(data_root_dir = \"/tmp/nvflare/df_stats/data\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c5444d8f-4938-4759-bd43-831013043c23",
   "metadata": {},
   "source": [
    "#### Let's take a look at the data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a1cf37d0-7555-4818-9963-ca7342161a4d",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "data_path =\"/tmp/nvflare/df_stats/data/site-1/data.csv\"\n",
    "data_features = [\n",
    "            \"Age\",\n",
    "            \"Workclass\",\n",
    "            \"fnlwgt\",\n",
    "            \"Education\",\n",
    "            \"Education-Num\",\n",
    "            \"Marital Status\",\n",
    "            \"Occupation\",\n",
    "            \"Relationship\",\n",
    "            \"Race\",\n",
    "            \"Sex\",\n",
    "            \"Capital Gain\",\n",
    "            \"Capital Loss\",\n",
    "            \"Hours per week\",\n",
    "            \"Country\",\n",
    "            \"Target\",\n",
    "        ]\n",
    "\n",
    "        # the original dataset has no header,\n",
    "        # we will use the adult.train dataset for site-1, the adult.test dataset for site-2\n",
    "        # the adult.test dataset has incorrect formatted row at 1st line, we will skip it.\n",
    "skip_rows = {\n",
    "            \"site-1\": [],\n",
    "            \"site-2\": [0],\n",
    "        }\n",
    "\n",
    "df= pd.read_csv(data_path, names=data_features, sep=r\"\\s*,\\s*\", skiprows=skip_rows, engine=\"python\", na_values=\"?\")\n",
    "df\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "81f6d572-7dc0-4cec-8382-f25555f52af9",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true
   },
   "source": [
    "> Note **We will only calculate the statistics of numerical features, categorical features will be skipped**"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f00de5e4-4360-4fc5-a819-4eb156e56341",
   "metadata": {},
   "source": [
    "## Run job in FL Simulator\n",
    "\n",
    "**Run Job using Simulator API**\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6361a85e-4187-433c-976c-0dc4021908ac",
   "metadata": {},
   "outputs": [],
   "source": [
    "! nvflare simulator df_stats/jobs/df_stats -w /tmp/nvflare/df/workdir -n 2 -t 2"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4fdbfb95-90c9-4d45-b727-dab6f5a8bc41",
   "metadata": {
    "tags": []
   },
   "source": [
    "Or python code\n",
    "```\n",
    "from nvflare.private.fed.app.simulator.simulator_runner import SimulatorRunner\n",
    "runner = SimulatorRunner(job_folder=\"df_stats/jobs/df_stats\", workspace=\"/tmp/nvflare/df/workdir\", n_clients = 2, threads=2)\n",
    "runner.run()\n",
    "\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "51be8a9a-b1b8-413c-abab-5cbd7e191a0d",
   "metadata": {
    "tags": []
   },
   "source": [
    "**Run Job using Simulator CLI**\n",
    "\n",
    "From a **terminal** one can also the following equivalent CLI\n",
    "\n",
    "```\n",
    "nvflare simulator df_stats/jobs/df_stats -w /tmp/nvflare/df/workdir -n 2 -t 2\n",
    "\n",
    "```\n",
    "\n",
    "assuming the nvflare is installed from a **terminal**. doing pip install from the notebook cell directory with bash command (! or %%bash) may or may not work depending on which python runtime kernel selected. Also %pip install or %pip install from notebook cell doesn't register the console_scripts in the PATH.   \n",
    "\n",
    "\n",
    "## Examine the result\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "45bf6e9a-3265-4e45-8b06-c8e543605f21",
   "metadata": {},
   "source": [
    "\n",
    "The results are stored in workspace \"/tmp/nvflare/df/workdir/\"\n",
    "```\n",
    "/tmp/nvflare/df/workdir/server/simulate_job/statistics/adults_stats.json\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "112a7dd0-45d9-42ea-98b2-f72a3bbccf48",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "cat /tmp/nvflare/df/workdir/server/simulate_job/statistics/adults_stats.json"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3cd042db-6ce0-4e37-bcbe-d96051e4d164",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Visualization\n",
    "We can visualize the results easly via the visualizaiton notebook. Before we do that, we need to copy the data to the notebook directory \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a3c89693-37b9-450c-85dd-8a2d78fee3fa",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "! cp /tmp/nvflare/df/workdir/server/simulate_job/statistics/adults_stats.json df_stats/demo/."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d5c6f632-3326-4236-902e-8c0965688d85",
   "metadata": {},
   "source": [
    "now we can visualize via the [visualization notebook](df_stats/demo/visualization.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "52d2a52f-8a8d-45ef-8a50-ddbb4ed2f2c6",
   "metadata": {
    "tags": []
   },
   "source": [
    "We are not quite done yet. What if you prefer to use python API instead CLI to run jobs. Lets do that in this section"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fda06c0b-798d-480d-9b4c-a62fab95bcf0",
   "metadata": {
    "tags": []
   },
   "source": [
    "## We are done !\n",
    "Congratulations, you just completed the federated stats calulation with data represented by data frame\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "nvflare_example",
   "language": "python",
   "name": "nvflare_example"
  },
  "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.10.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}