Heart disease notebooks

_toc.yml

@@ -12,6 +12,10 @@ parts:
     chapters:
     - file: fedbiomed-tutorial/intro-tutorial-mednist.ipynb
       title: Intro tutorial (MedNIST)
+    - file: fedbiomed-tutorial/tutorial-sklearn-problem.ipynb
+      title: Heart disease detection 
+    - file: fedbiomed-tutorial/tutorial-sklearn-solutions.ipynb
+      title: Heart disease detection 
     - file: fedbiomed-tutorial/brain-segmentation-exercise.ipynb
       title: Brain segmentation 
     - file: fedbiomed-tutorial/brain-segmentation-solution.ipynb

fedbiomed-tutorial/tutorial-sklearn-problem.ipynb

+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "64e87007",
+   "metadata": {
+    "pycharm": {
+     "name": "#%% md\n"
+    }
+   },
+   "source": [
+    "# Heart disease detection"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9e351015",
+   "metadata": {},
+   "source": [
+    "In this tutorial, we will focus on applying federated learning techniques to a classification problem using Scikit-Learn, a popular machine learning library in Python. We will walk you through the process step by step, from setting up the federated learning environment to evaluating the model's performance.\n",
+    "\n",
+    "\n",
+    "Scikit-Learn, also known as sklearn, is a popular machine learning library in Python. It provides a wide range of tools and algorithms for tasks such as data preprocessing, feature selection, model training, and evaluation. Sklearn is widely used for tasks such as classification, regression, clustering, and dimensionality reduction. It offers a user-friendly interface and integrates well with other libraries in the Python ecosystem, making it a go-to choice for many machine learning practitioners and researchers."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ade4cbea",
+   "metadata": {
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "%load_ext autoreload\n",
+    "%autoreload 2"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5827f560",
+   "metadata": {},
+   "source": [
+    "# Table of content\n",
+    "\n",
+    "1. [The dataset](#dataset)\n",
+    "2. [Task 1: training plan](#task1)\n",
+    "3. [Task 2: the experment](#task2)\n",
+    "4. [Task 3: model validation](#task3)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "59d00ae5",
+   "metadata": {},
+   "source": [
+    "# Tutorial"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b9036f7d",
+   "metadata": {},
+   "source": [
+    "## The dataset <a name=\"dataset\"></a>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e4f03a34",
+   "metadata": {},
+   "source": [
+    "The Heart Disease dataset available at https://archive.ics.uci.edu/dataset/45/heart+disease is a widely used dataset in the field of cardiovascular research and machine learning. It contains a collection of medical attributes from patients suspected of having heart disease, along with their corresponding diagnosis (presence or absence of heart disease). The dataset includes information such as age, sex, blood pressure, cholesterol levels, and various other clinical measurements.\n",
+    "\n",
+    "It was collected in 4 hospitals in the USA, Switzerland and Hungary. This dataset contains tabular information about 740 patients distributed among these four clients. \n",
+    "\n",
+    "A federated version of this dataset has been proposed in [Flamby](https://arxiv.org/pdf/2210.04620.pdf). Following thier actions, we preprocess the dataset by removing missing values and encoding non-binary categorical variables as dummy variables. We finally obtain the following centers:\n",
+    "\n",
+    "| Number | Client               | Dataset size |\n",
+    "|--------|----------------------|--------------|\n",
+    "| 0      | Cleveland’s Hospital | 303          |\n",
+    "| 1      | Hungarian Hospital   | 261          |\n",
+    "| 2      | Switzerland Hospital | 46           |\n",
+    "| 3      | Long Beach Hospital  | 130          | \n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6d8554fa",
+   "metadata": {},
+   "source": [
+    "For teaching purposes, we decided to merge: client0 with client3 and client1 with client2.\n",
+    "The final federated scenario, in this way, is the following:\n",
+    "- **client1**, with 349 elements\n",
+    "- **client2**, with 391 elements"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e860a74e",
+   "metadata": {},
+   "source": [
+    "## Task 1: Defining the training plan <a name=\"task1\"></a>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fd2daf01",
+   "metadata": {},
+   "source": [
+    "A training plan is a class that defines the four main components of federated model training: the data, the model, he loss and the optimizer. It is responsible for providing custom methods allowing every node to perform the training.\n",
+    "\n",
+    "\n",
+    "In the case of scikit-learn, Fed-BioMed already does a lot of the heavy lifting for you by providing the FedPerceptron, FedSGDClassifier and FedSGDRegressor classes as training plans. These classes already take care of the model, optimizer, loss function and related dependencies for you, so you only need to define how the data will be loaded.\n",
+    "\n",
+    "\n",
+    "In this tutorial we are going to use an [SGDClassifier](https://scikit-learn.org/stable/modules/generated/sklearn.linear_model.SGDClassifier.html), so the related FedSGDClassifier training plan."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "11ec284b",
+   "metadata": {},
+   "source": [
+    "### Model arguments\n",
+    "*model_args* is a dictionary with the arguments related to the model, that will be passed to the Perceptron constructor.\n",
+    "\n",
+    "**IMPORTANT** For classification tasks, you are required to specify the following two fields:\n",
+    "\n",
+    "- n_features: the number of features in each input sample (in our case, the number of pixels in the images)\n",
+    "- n_classes: the number of classes in the target data\n",
+    "\n",
+    "Other model arguments depend on the specific model you are using, and are defined in the model definition. Refer to the model documentation \n",
+    "\n",
+    "\n",
+    "### Training arguments\n",
+    "*training_args* is a dictionary containing the arguments for the training routine (e.g. batch size, learning rate, epochs, etc.). This will be passed to the routine on the node side.\n",
+    "\n",
+    "**IMPORTANT** To set the training arguments we may either pass them to the Experiment constructor, or set them on an instance with the setter method:\n",
+    "\n",
+    "     'exp.set_training_arguments(training_args=training_args)'\n",
+    "The setters are available also for single training arguments, like: \n",
+    "\n",
+    "    'exp.set_aggregator(aggregator=FedAverage)'"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7571ab66",
+   "metadata": {},
+   "source": [
+    "**TO_DO:**\n",
+    "\n",
+    "- Apply the scaler to your data\n",
+    "- Define training args: num_updates, batch_size.\n",
+    "- Define model args as explained above."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "998bb584",
+   "metadata": {
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "from fedbiomed.common.training_plans import FedSGDRegressor, FedPerceptron, FedSGDClassifier\n",
+    "from fedbiomed.common.data import DataManager\n",
+    "from sklearn.preprocessing import MinMaxScaler\n",
+    "class SkLearnClassifierTrainingPlan(FedSGDClassifier):\n",
+    "    def init_dependencies(self):\n",
+    "        \"\"\"Define additional dependencies.\n",
+    "        return [\"from torchvision import datasets, transforms\",\n",
+    "                \"from torch.utils.data import DataLoader\"]\n",
+    "\n",
+    "    def training_data(self, batch_size):\n",
+    "        \n",
+    "        In this case, we rely on torchvision functions for preprocessing the images.\n",
+    "        \"\"\"\n",
+    "        return [\"from sklearn.preprocessing import MinMaxScaler\"]\n",
+    "    \n",
+    "    def training_data(self, batch_size):\n",
+    "        df = pd.read_csv(self.dataset_path, delimiter=';', header=None)\n",
+    "\n",
+    "        X = df.iloc[:, :-1]\n",
+    "        y = df.iloc[:, -1]\n",
+    "        self.scaler = MinMaxScaler()\n",
+    "        # X =  [...] TODO: apply the transformer to the data.\n",
+    "        return DataManager(dataset=X,target=y, batch_size=batch_size, shuffle=True)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "653e8aea",
+   "metadata": {
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "n_features = 18\n",
+    "n_classes = 2\n",
+    "\n",
+    "model_args = { 'max_iter':100, \n",
+    "               'tol': 1e-1 , \n",
+    "               'loss': 'huber',\n",
+    "              # [...] TODO: Insert the missing model arguments.\n",
+    "              }\n",
+    "\n",
+    "training_args = {   \n",
+    "    # [...] TODO: Insert the training arguments as elements in the dic.\n",
+    "}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b3020aa6",
+   "metadata": {},
+   "source": [
+    "## Task 2: the Experiment <a name=\"task2\"></a>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9ae58ccf",
+   "metadata": {},
+   "source": [
+    "The experiment enables Federated Learning by orchestrating the training process across multiple nodes. It searches for datasets based on specific tags, uploads the training plan file, sends model and training arguments, tracks and checks training progress, and downloads and aggregates model parameters for the next round."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c17ef104",
+   "metadata": {},
+   "source": [
+    "**TO_DO:**\n",
+    "\n",
+    "- Define the used training plan.\n",
+    "- Pass model and training arguments "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "28f602da",
+   "metadata": {},
+   "source": [
+    "<div class=\"alert alert-block alert-info\"> <b>TAGS:</b> Replace %%%% in the tags with your username </div>"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4b1a1341",
+   "metadata": {
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "from fedbiomed.researcher.experiment import Experiment\n",
+    "from fedbiomed.researcher.aggregators.fedavg import FedAverage\n",
+    "\n",
+    "tags =  ['heart-jupyter-%%%%']\n",
+    "rounds = 10\n",
+    "\n",
+    "# search for corresponding datasets across nodes datasets\n",
+    "exp = Experiment(tags=tags,\n",
+    "                 model_args=None, #TODO: insert the correct value\n",
+    "                 training_plan_class=None, #TODO: insert the correct value\n",
+    "                 training_args=None, #TODO: insert the correct value\n",
+    "                 round_limit=rounds,\n",
+    "                 aggregator=FedAverage(),\n",
+    "                 node_selection_strategy=None)\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d6ff55da",
+   "metadata": {
+    "pycharm": {
+     "name": "#%%\n"
+    },
+    "scrolled": false
+   },
+   "outputs": [],
+   "source": [
+    "exp.run()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "88e2a782",
+   "metadata": {
+    "pycharm": {
+     "name": "#%% md\n"
+    }
+   },
+   "source": [
+    "## Task 3: Model Validation <a name=\"task3\"></a>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "84f2ad10",
+   "metadata": {},
+   "source": [
+    "During federated training, model validation plays a crucial role in assessing performance without a dedicated holdout dataset. Fed-BioMed enables separate model validation on each node after parameter updates, allowing comparison of model performances. Two types of validation can be performed:\n",
+    "- one on globally updated parameters before training a round, \n",
+    "- another on locally updated parameters after local training is completed on a node. \n",
+    "\n",
+    "This helps users evaluate the impact of node-specific training on model improvement."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1cbc4d1a",
+   "metadata": {},
+   "source": [
+    "Here is the list of validation arguments that can be configured.\n",
+    "\n",
+    "- *test_ratio*: Ratio of the validation partition of the dataset. The remaining samples will be used for training. By default, it is 0.0.\n",
+    "- *test_on_global_updates*: Boolean value that indicates whether validation will be applied to globally updated (aggregated) parameters (see Figure 1). Default is False\n",
+    "- *test_on_local_updates*: Boolean value that indicates whether validation will be applied to locally updated (trained) parameters (see Figure 1). Default is False\n",
+    "- *test_metric*: One of MetricTypes that indicates which metric will be used for validation. It can be str or an instance of MetricTypes (e.g. MetricTypes.RECALL or RECALL ). If it is None and there isn't testing_step defined in the training plan (see section: Define Custom Validation Step) default metric will be ACCURACY.\n",
+    "- *test_metric_args*: A dictionary that contains the arguments that will be used for the metric function."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "700d8da1",
+   "metadata": {},
+   "source": [
+    "**TO_DO:**\n",
+    "\n",
+    "- Initialize a new experiements.\n",
+    "- Use the setters to define the validation arguments.\n",
+    "- Launch the training and check the validation performances."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9972f57d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "exp = Experiment(\n",
+    "    # [...]\n",
+    "    training_args=training_args\n",
+    ")\n",
+    "#TODO: set the parameters using the setters. Example: exp.set_test_ratio(test_ratio=0.1)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "827b9920",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "exp.run()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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.9.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}