[2.4] Add xgboost example, unit tests, integration tests (#2392)

Author: YuanTingHsieh

.readthedocs.yaml

@@ -26,6 +26,6 @@ sphinx:
 python:
   install:
     - method: pip
-      path: .[doc]
+      path: .[dev]
 #  system_packages: true
 

build_doc.sh

@@ -49,7 +49,7 @@ function clean_docs() {
 }
 
 function build_html_docs() {
-    pip install -e .[doc]
+    pip install -e .[dev]
     sphinx-apidoc --module-first -f -o docs/apidocs/ nvflare "*poc" "*private"
     sphinx-build -b html docs docs/_build
 }

examples/advanced/xgboost/histogram-based/jobs/base/app/config/config_fed_client.json

@@ -1,23 +1,24 @@
 {
   "format_version": 2,
+  "num_rounds": 100,
   "executors": [
     {
       "tasks": [
         "train"
       ],
       "executor": {
         "id": "Executor",
-        "name": "FedXGBHistogramExecutor",
+        "path": "nvflare.app_opt.xgboost.histogram_based.executor.FedXGBHistogramExecutor",
         "args": {
           "data_loader_id": "dataloader",
-          "num_rounds": 100,
+          "num_rounds": "{num_rounds}",
           "early_stopping_rounds": 2,
           "xgb_params": {
             "max_depth": 8,
             "eta": 0.1,
             "objective": "binary:logistic",
             "eval_metric": "auc",
-            "tree_method": "gpu_hist",
+            "tree_method": "hist",
             "nthread": 16
           }
         }

examples/advanced/xgboost/histogram-based/jobs/base/app/config/config_fed_server.json

@@ -1,8 +1,5 @@
 {
   "format_version": 2,
-  "server": {
-    "heart_beat_timeout": 600
-  },
   "task_data_filters": [],
   "task_result_filters": [],
   "components": [],

examples/advanced/xgboost/histogram-based/jobs/base_v2/app/config/config_fed_client.json

@@ -0,0 +1,38 @@
+{
+  "format_version": 2,
+  "num_rounds": 100,
+  "executors": [
+    {
+      "tasks": [
+        "config", "start"
+      ],
+      "executor": {
+        "id": "Executor",
+        "path": "nvflare.app_opt.xgboost.histogram_based_v2.executor.FedXGBHistogramExecutor",
+        "args": {
+          "data_loader_id": "dataloader",
+          "early_stopping_rounds": 2,
+          "xgb_params": {
+            "max_depth": 8,
+            "eta": 0.1,
+            "objective": "binary:logistic",
+            "eval_metric": "auc",
+            "tree_method": "hist",
+            "nthread": 16
+          }
+        }
+      }
+    }
+  ],
+  "task_result_filters": [],
+  "task_data_filters": [],
+  "components": [
+    {
+      "id": "dataloader",
+      "path": "higgs_data_loader.HIGGSDataLoader",
+      "args": {
+        "data_split_filename": "data_split.json"
+      }
+    }
+  ]
+}

examples/advanced/xgboost/histogram-based/jobs/base_v2/app/config/config_fed_server.json

@@ -0,0 +1,16 @@
+{
+  "format_version": 2,
+  "num_rounds": 100,
+  "task_data_filters": [],
+  "task_result_filters": [],
+  "components": [],
+  "workflows": [
+    {
+      "id": "xgb_controller",
+      "path": "nvflare.app_opt.xgboost.histogram_based_v2.controller.XGBFedController",
+      "args": {
+        "num_rounds": "{num_rounds}"
+      }
+    }
+  ]
+}

examples/advanced/xgboost/histogram-based/jobs/base_v2/app/custom/higgs_data_loader.py

@@ -0,0 +1,77 @@
+# Copyright (c) 2024, NVIDIA CORPORATION.  All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+
+import pandas as pd
+import xgboost as xgb
+
+from nvflare.app_opt.xgboost.data_loader import XGBDataLoader
+
+
+def _read_higgs_with_pandas(data_path, start: int, end: int):
+    data_size = end - start
+    data = pd.read_csv(data_path, header=None, skiprows=start, nrows=data_size)
+    data_num = data.shape[0]
+
+    # split to feature and label
+    x = data.iloc[:, 1:].copy()
+    y = data.iloc[:, 0].copy()
+
+    return x, y, data_num
+
+
+class HIGGSDataLoader(XGBDataLoader):
+    def __init__(self, data_split_filename):
+        """Reads HIGGS dataset and return XGB data matrix.
+
+        Args:
+            data_split_filename: file name to data splits
+        """
+        self.data_split_filename = data_split_filename
+
+    def load_data(self, client_id: str):
+        with open(self.data_split_filename, "r") as file:
+            data_split = json.load(file)
+
+        data_path = data_split["data_path"]
+        data_index = data_split["data_index"]
+
+        # check if site_id and "valid" in the mapping dict
+        if client_id not in data_index.keys():
+            raise ValueError(
+                f"Data does not contain Client {client_id} split",
+            )
+
+        if "valid" not in data_index.keys():
+            raise ValueError(
+                "Data does not contain Validation split",
+            )
+
+        site_index = data_index[client_id]
+        valid_index = data_index["valid"]
+
+        # training
+        x_train, y_train, total_train_data_num = _read_higgs_with_pandas(
+            data_path=data_path, start=site_index["start"], end=site_index["end"]
+        )
+        dmat_train = xgb.DMatrix(x_train, label=y_train)
+
+        # validation
+        x_valid, y_valid, total_valid_data_num = _read_higgs_with_pandas(
+            data_path=data_path, start=valid_index["start"], end=valid_index["end"]
+        )
+        dmat_valid = xgb.DMatrix(x_valid, label=y_valid)
+
+        return dmat_train, dmat_valid

examples/advanced/xgboost/histogram-based/jobs/base_v2/meta.json

@@ -0,0 +1,10 @@
+{
+  "name": "xgboost_histogram_based_v2",
+  "resource_spec": {},
+  "deploy_map": {
+    "app": [
+      "@ALL"
+    ]
+  },
+  "min_clients": 2
+}

examples/advanced/xgboost/prepare_job_config.sh

@@ -22,4 +22,6 @@ prepare_job_config 20 cyclic uniform uniform $TREE_METHOD
 
 prepare_job_config 2 histogram uniform uniform $TREE_METHOD
 prepare_job_config 5 histogram uniform uniform $TREE_METHOD
+prepare_job_config 2 histogram_v2 uniform uniform $TREE_METHOD
+prepare_job_config 5 histogram_v2 uniform uniform $TREE_METHOD
 echo "Job configs generated"

examples/advanced/xgboost/tree-based/jobs/bagging_base/app/config/config_fed_server.json

@@ -1,11 +1,6 @@
 {
   "format_version": 2,
-
-  "server": {
-    "heart_beat_timeout": 600,
-    "task_request_interval": 0.05
-  },
-
+  "num_rounds": 101,
   "task_data_filters": [],
   "task_result_filters": [],
 
@@ -34,7 +29,7 @@
       "name": "ScatterAndGather",
       "args": {
         "min_clients": 5,
-        "num_rounds": 101,
+        "num_rounds": "{num_rounds}",
         "start_round": 0,
         "wait_time_after_min_received": 0,
         "aggregator_id": "aggregator",