add privacy filtering nb

holgerroth · Feb 25, 2025 · 0311364 · 0311364
1 parent b8647ac
commit 0311364
Show file tree

Hide file tree

Showing 2 changed files with 772 additions and 70 deletions.
diff --git a/...ivacy/chapter-5_Privacy_In_Federated_Learning/05.1_privacy_filter/privacy_filtering.ipynb b/...ivacy/chapter-5_Privacy_In_Federated_Learning/05.1_privacy_filter/privacy_filtering.ipynb
@@ -5,98 +5,73 @@
    "id": "1398ef0a-f189-4d04-a8a9-276a17ab0f8b",
    "metadata": {},
    "source": [
-    "# Federated Learning with Differential Privacy\n",
+    "# Privacy Preservation using NVFlare's Filters\n",
     "\n",
-    "Please make sure you set up a virtual environment and follow [example root readme](../../README.md) before starting this notebook.\n",
-    "Then, install the requirements.\n",
+    "[Filters](https://nvflare.readthedocs.io/en/main/programming_guide/filters.html) in NVIDIA FLARE are a type of FLComponent that has a process method to transform the Shareable object between the communicating parties. A Filter can be used to provide additional processing to shareable data before sending or after receiving from the peer.\n",
     "\n",
-    "<div class=\"alert alert-block alert-info\"> <b>NOTE</b> Some of the cells below generate long text output.  We're using <pre>%%capture --no-display --no-stderr cell_output</pre> to suppress this output.  Comment or delete this line in the cells below to restore full output.</div>"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 2,
-   "id": "5002e45c-f58e-4f68-bb5a-9626e084947f",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%%capture --no-display --no-stderr cell_output\n",
-    "!pip install -r requirements.txt"
+    "The `FLContext` is available for the `Filter` to use. Filters can be added to your NVFlare job using the [FedJob API](https://nvflare.readthedocs.io/en/main/programming_guide/fed_job_api.html#fedjob-api) you should be familiar with from previous chapters."
    ]
   },
   {
    "cell_type": "markdown",
    "id": "bddd90a1-fe96-4f24-b360-bbe73b24e34a",
    "metadata": {},
    "source": [
-    "### Differential Privacy (DP)\n",
-    "[Differential Privacy (DP)](https://arxiv.org/abs/1910.00962) [7] is a method for ensuring that Federated Learning (FL) preserves privacy by obfuscating the model updates sent from clients to the central server. \n",
-    "This example shows the usage of a CIFAR-10 training code with NVFlare, as well as the usage of DP filters in your FL training. DP is added as a filter in `config_fed_client.json`. Here, we use the \"Sparse Vector Technique\", i.e. the [SVTPrivacy](https://nvflare.readthedocs.io/en/main/apidocs/nvflare.app_common.filters.svt_privacy.html) protocol, as utilized in [Li et al. 2019](https://arxiv.org/abs/1910.00962) [7] (see [Lyu et al. 2016](https://arxiv.org/abs/1603.01699) [8] for more information)."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "9b0c692a-16dc-4ef9-a432-4b7375a2a7d6",
-   "metadata": {},
-   "source": [
-    "## Run experiments with FL simulator\n",
-    "### Training with FL simulator\n",
-    "FL simulator is used to simulate FL experiments or debug codes, not for real FL deployment.\n",
+    "#### Filters\n",
+    "In NVFlare, filters are used for the pre- and post-processing of a task's data.\n",
     "\n",
-    "First, train a model using the FedAvg algorithm with four clients without DP."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "fce5fd7e-f911-4a04-81a6-312e43c832c3",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "!nvflare simulator './configs/brats_fedavg' -w './workspace_brats/brats_fedavg' -n 4 -t 4"
+    "On the **Server** side, before sending the task to the **Client**, “task data filters” (if any) are applied to the task data. Only the filtered task data is sent to the client. Similarly, when the task result is received from the client, “task result filters” are applied to the received result before passing on to the `Controller`.\n",
+    "\n",
+    "On the **Client** side, once a task is received from the Server, “task data filters” (if any) are applied to the task data before passing to the task executor. Similarly, when the task result is computed from the `Executor`, “task result filters” are applied to the task result before sending it to the **Server**.\n",
+    "\n",
+    "![NVFlare's Filter Concept](https://nvflare.readthedocs.io/en/main/_images/Filters.png)"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "c82a3be9-9e58-44ca-9d3f-e85456de7f12",
-   "metadata": {},
-   "source": [
-    "Run the FL simulator with 4 clients for federated learning with differential privacy by running"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "4f1f9065-129f-4e62-ac3d-a1504a3b30bf",
+   "id": "7d299352-28c6-4be6-9297-42a1c8184191",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "!nvflare simulator './configs/brats_fedavg_dp' -w './workspace_brats/brats_fedavg_dp' -n 4 -t 4"
+    "#### Examples of Filters\n",
+    "Filters are the primary technique for data privacy protection.\n",
+    "\n",
+    "Filters can convert data formats and a lot more. You can apply any type of massaging to the data for the purpose of security. In fact, privacy and homomorphic encryption techniques are all implemented as filters:\n",
+    "\n",
+    "ExcludeVars to exclude variables from shareable (`nvflare.app_common.filters.exclude_vars`)\n",
+    "\n",
+    "PercentilePrivacy for truncation of weights by percentile (`nvflare.app_common.filters.percentile_privacy`)\n",
+    "\n",
+    "SVTPrivacy for differential privacy through sparse vector techniques (`nvflare.app_common.filters.svt_privacy`)\n",
+    "\n",
+    "Homomorphic encryption filters to encrypt data before sharing (`nvflare.app_common.homomorphic_encryption.he_model_encryptor` and `nvflare.app_common.homomorphic_encryption.he_model_decryptor`)"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "7118e9a1-85fc-4e5a-8b29-fb5f50a4f941",
+   "id": "9b0c692a-16dc-4ef9-a432-4b7375a2a7d6",
    "metadata": {},
    "source": [
-    "### Testing with FL simulator\n",
-    "The best global models are stored at\n",
-    "```\n",
-    "workspace_brats/[job]/simulated_job/app_server/best_FL_global_model.pt\n",
-    "```\n",
+    "#### Adding a Filter with the JobAPI\n",
+    "You can add `Filters` to an NVFlare job using the `job.to()` method by specifying which tasks the filter applies to and when to apply it, **before** or **after** the task.\n",
+    "\n",
+    "The behavior can be selected by using the [FilterType](https://nvflare.readthedocs.io/en/main/apidocs/nvflare.job_config.defs.html#nvflare.job_config.defs.FilterType). Users must specify the filter type as either `FilterType.TASK_RESULT` (flow from executor to controller) or `FilterType.TASK_DATA` (flow from controller to executor).\n",
     "\n",
-    "Please then add the correct paths to the testing script, and run"
+    "The filter will be added \"task_data_filters\" and task_result_filters accordingly and be applied to the specified tasks (defaults to “[*]” for all tasks).\n",
+    "\n",
+    "For example, you can add a privacy filter as such.\n",
+    "```python\n",
+    "pp_filter = PercentilePrivacy(percentile=10, gamma=0.01)\n",
+    "job.to(pp_filter, \"site-1\", tasks=[\"train\"], filter_type=FilterType.TASK_RESULT)\n",
+    "```"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "e926d179-4063-4f27-9815-b9e3f9569067",
+   "cell_type": "markdown",
+   "id": "351e067f-495a-45d9-bcfd-d8031584cffb",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "!cd ./result_stat\n",
-    "!bash testing_models_3d.sh"
+    "#### Writing Your Own Filter\n",
+    "For writing your own filter, you can utilize the [DXOFilter](https://nvflare.readthedocs.io/en/main/apidocs/nvflare.apis.dxo_filter.html#nvflare.apis.dxo_filter.DXOFilter) base class. For details see the [documentation](https://nvflare.readthedocs.io/en/main/programming_guide/filters.html). "
    ]
   }
  ],