examples/advanced/sklearn-svm/sklearn_svm_cancer.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "cada310b-e776-4b9a-aabe-f111c31efcc2",
   "metadata": {
    "tags": []
   },
   "source": [
    "# Federated SVM with Scikit-learn on Breast Cancer Dataset"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0653cbf2-92f2-4a22-8317-69cfb0266e92",
   "metadata": {},
   "source": [
    "## Introduction to Scikit-learn, tabular data, and federated SVM\n",
    "### Scikit-learn\n",
    "This example shows how to use [NVIDIA FLARE](https://nvflare.readthedocs.io/en/main/index.html) on tabular data.\n",
    "It uses [Scikit-learn](https://scikit-learn.org/),\n",
    "a widely used open-source machine learning library that supports supervised \n",
    "and unsupervised learning.\n",
    "### Tabular data\n",
    "The data used in this example is tabular in a format that can be handled by [pandas](https://pandas.pydata.org/), such that:\n",
    "- rows correspond to data samples\n",
    "- the first column represents the label \n",
    "- the other columns cover the features.    \n",
    "\n",
    "Each client is expected to have one local data file containing both training \n",
    "and validation samples. To load the data for each client, the following \n",
    "parameters are expected by the local learner:\n",
    "- data_file_path: string, the full path to the client's data file \n",
    "- train_start: int, start row index for the training set\n",
    "- train_end: int, end row index for the training set\n",
    "- valid_start: int, start row index for the validation set\n",
    "- valid_end: int, end row index for the validation set\n",
    "\n",
    "### Federated SVM\n",
    "The machine learning algorithm shown in this example is [SVM for Classification (SVC)](https://scikit-learn.org/stable/modules/generated/sklearn.svm.SVC.html).\n",
    "Under this setting, federated learning can be formulated in two steps:\n",
    "- local training: each client trains a local SVM model with their own data\n",
    "- global training: server collects the support vectors from all clients and \n",
    "  trains a global SVM model based on them\n",
    "\n",
    "Unlike other iterative federated algorithms, federated SVM only involves \n",
    "these two training steps. Hence, in the server config, we set\n",
    "`\"num_rounds\": 2`\n",
    "The first round is the training round, performing local training and global aggregation. \n",
    "Next, the global model will be sent back to clients for the second round, \n",
    "performing model validation and local model update. \n",
    "If this number is set to a number greater than 2, the system will report an error and exit.\n",
    "\n",
    "Below we listed steps to run this example."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a5a0292c-78b6-4bde-96d6-699dae996173",
   "metadata": {},
   "source": [
    "## 1. Setup NVFLARE\n",
    "\n",
    "Follow the [Getting_Started](https://nvflare.readthedocs.io/en/main/getting_started.html) to setup virtual environment and install NVFLARE\n",
    "\n",
    "We also provide a [Notebook](../../nvflare_setup.ipynb) for this setup process. \n",
    "\n",
    "Assume you have already setup the venv, lets first install required packages."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f4130b15-09e6-456f-a3c7-87c8ee9e07f0",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%pip install -r requirements.txt"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1d872d8a-9e44-49dd-94b1-7862b3815ffe",
   "metadata": {},
   "source": [
    "## 2. Data preparation \n",
    "This example uses the the breast cancer dataset available from Scikit-learn's dataset API.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f906a1c9-dce0-476c-be65-79ebd8ad5da9",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%env DATASET_PATH=/tmp/nvflare/dataset/sklearn_breast_cancer.csv\n",
    "!python3 ./utils/prepare_data.py --dataset_name cancer --randomize 0 --out_path ${DATASET_PATH}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "af257e69-2bb7-49b6-ac6c-f007b0e6618e",
   "metadata": {},
   "source": [
    "## 3. Prepare clients' configs with proper data split information \n",
    "We are using NVFlare's FL simulator to run the following experiments. Here we simulate 3 clients with uniform data split."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fdb7290a-48ff-4e80-be58-5e6b0e0f9379",
   "metadata": {
    "scrolled": true,
    "tags": []
   },
   "outputs": [],
   "source": [
    "%env DATASET_PATH=/tmp/nvflare/dataset/sklearn_breast_cancer.csv\n",
    "!python3 ./utils/prepare_job_config.py \\\n",
    "        --task_name \"sklearn_svm\" \\\n",
    "        --data_path \"${DATASET_PATH}\" \\\n",
    "        --site_num 3 \\\n",
    "        --valid_frac 0.2 \\\n",
    "        --split_method \"uniform\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bd0713e2-e393-41c0-9da0-392535cf8a54",
   "metadata": {},
   "source": [
    "## 4. Run simulated kmeans experiment\n",
    "Now that we have the job configs ready, we run the experiment using Simulator."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bde19b89-3aef-49ac-99d9-800d65829830",
   "metadata": {},
   "source": [
    "Simulator can either be used with CLI command: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9bb6cab4-9c24-400a-bc3c-f1e4a6d5a346",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "! nvflare simulator ./jobs/sklearn_svm_base -w /tmp/nvflare/sklearn_svm_cancer -n 3 -t 3"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3915369e-62eb-4903-a120-69b238791075",
   "metadata": {},
   "source": [
    "or via Simulator API:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "33c75dcb-014d-40c4-8a4a-7a53847c486b",
   "metadata": {
    "scrolled": true,
    "tags": []
   },
   "outputs": [],
   "source": [
    "import os\n",
    "from nvflare.private.fed.app.simulator.simulator_runner import SimulatorRunner  \n",
    "\n",
    "simulator = SimulatorRunner(\n",
    "    job_folder=f\"./jobs/sklearn_svm_base\",\n",
    "    workspace=\"/tmp/nvflare/sklearn_svm_cancer\",\n",
    "    n_clients=3,\n",
    "    threads=3\n",
    ")\n",
    "run_status = simulator.run()\n",
    "print(\"Simulator finished with run_status\", run_status)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "913e9ee2-e993-442d-a525-d2baf92af539",
   "metadata": {},
   "source": [
    "## 5. Result visualization\n",
    "Running with default [SVC](https://scikit-learn.org/stable/modules/generated/sklearn.svm.SVC.html) classifier, the resulting global model's AUC is 0.806 which can be visualized in tensorboard."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a6814434-4e6d-4460-b480-709cb3e77cc8",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%load_ext tensorboard\n",
    "%tensorboard --logdir /tmp/nvflare/sklearn_svm_cancer"
   ]
  }
 ],
 "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.8.17"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}