examples/advanced/sklearn-kmeans/sklearn_kmeans_iris.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "cada310b-e776-4b9a-aabe-f111c31efcc2",
   "metadata": {
    "tags": []
   },
   "source": [
    "# Federated K-Means Clustering with Scikit-learn on Iris Dataset"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0653cbf2-92f2-4a22-8317-69cfb0266e92",
   "metadata": {},
   "source": [
    "## Introduction to Scikit-learn, tabular data, and federated k-Means\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 k-Means clustering\n",
    "The machine learning algorithm in this example is [k-Means clustering](https://scikit-learn.org/stable/modules/generated/sklearn.cluster.KMeans.html).\n",
    "The aggregation follows the scheme defined in [Mini-batch k-Means](https://scikit-learn.org/stable/modules/generated/sklearn.cluster.MiniBatchKMeans.html). \n",
    "Under this setting, each round of federated learning can be formulated as follows:\n",
    "- local training: starting from global centers, each client trains a local MiniBatchKMeans model with their own data\n",
    "- global aggregation: server collects the cluster center, \n",
    "  counts information from all clients, aggregates them by considering \n",
    "  each client's results as a mini-batch, and updates the global center and per-center counts.\n",
    "\n",
    "For center initialization, at the first round, each client generates its initial centers with the k-means++ method. Then, the server collects all initial centers and performs one round of k-means to generate the initial global center.\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 Iris 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_iris.csv\n",
    "!python3 ./utils/prepare_data.py --dataset_name iris --randomize 1 --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. Since the dataset is already randomized in the last step, the split is done sequentially. For unsupervised clustering, we use the whole dataset with ground truth label to validate the performance."
   ]
  },
  {
   "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_iris.csv\n",
    "!python3 ./utils/prepare_job_config.py --task_name \"sklearn_kmeans\" --data_path \"${DATASET_PATH}\" --site_num 3 --valid_frac 1 --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_kmeans_3_uniform -w /tmp/nvflare/sklearn_kmeans_iris -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_kmeans_3_uniform\",\n",
    "    workspace=\"/tmp/nvflare/sklearn_kmeans_iris\",\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",
    "Model accuracy is computed as the homogeneity score between the cluster formed and the ground truth label, 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_kmeans_iris"
   ]
  }
 ],
 "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
}