chore: import upstream snapshot with attribution

examples/python-guide/dask/README.md

@@ -0,0 +1,25 @@
+Dask Examples
+=============
+
+This directory contains examples of machine learning workflows with LightGBM and [Dask](https://dask.org/).
+
+Before running this code, see [the installation instructions for the Dask-package](https://github.com/lightgbm-org/LightGBM/tree/main/python-package#install-dask-package).
+
+After installing the package and its dependencies, any of the examples here can be run with a command like this:
+
+```shell
+python binary-classification.py
+```
+
+The examples listed below contain minimal code showing how to train LightGBM models using Dask.
+
+**Training**
+
+* [binary-classification.py](./binary-classification.py)
+* [multiclass-classification.py](./multiclass-classification.py)
+* [ranking.py](./ranking.py)
+* [regression.py](./regression.py)
+
+**Prediction**
+
+* [prediction.py](./prediction.py)

examples/python-guide/dask/binary-classification.py

@@ -0,0 +1,30 @@
+import dask.array as da
+from distributed import Client, LocalCluster
+from sklearn.datasets import make_blobs
+
+import lightgbm as lgb
+
+if __name__ == "__main__":
+    print("loading data")
+
+    X, y = make_blobs(n_samples=1000, n_features=50, centers=2)
+
+    print("initializing a Dask cluster")
+
+    cluster = LocalCluster()
+    client = Client(cluster)
+
+    print("created a Dask LocalCluster")
+
+    print("distributing training data on the Dask cluster")
+
+    dX = da.from_array(X, chunks=(100, 50))
+    dy = da.from_array(y, chunks=(100,))
+
+    print("beginning training")
+
+    dask_model = lgb.DaskLGBMClassifier(n_estimators=10)
+    dask_model.fit(dX, dy)
+    assert dask_model.fitted_
+
+    print("done training")

examples/python-guide/dask/multiclass-classification.py

@@ -0,0 +1,30 @@
+import dask.array as da
+from distributed import Client, LocalCluster
+from sklearn.datasets import make_blobs
+
+import lightgbm as lgb
+
+if __name__ == "__main__":
+    print("loading data")
+
+    X, y = make_blobs(n_samples=1000, n_features=50, centers=3)
+
+    print("initializing a Dask cluster")
+
+    cluster = LocalCluster(n_workers=2)
+    client = Client(cluster)
+
+    print("created a Dask LocalCluster")
+
+    print("distributing training data on the Dask cluster")
+
+    dX = da.from_array(X, chunks=(100, 50))
+    dy = da.from_array(y, chunks=(100,))
+
+    print("beginning training")
+
+    dask_model = lgb.DaskLGBMClassifier(n_estimators=10)
+    dask_model.fit(dX, dy)
+    assert dask_model.fitted_
+
+    print("done training")

examples/python-guide/dask/prediction.py

@@ -0,0 +1,48 @@
+import dask.array as da
+from distributed import Client, LocalCluster
+from sklearn.datasets import make_regression
+from sklearn.metrics import mean_squared_error
+
+import lightgbm as lgb
+
+if __name__ == "__main__":
+    print("loading data")
+
+    X, y = make_regression(n_samples=1000, n_features=50)
+
+    print("initializing a Dask cluster")
+
+    cluster = LocalCluster(n_workers=2)
+    client = Client(cluster)
+
+    print("created a Dask LocalCluster")
+
+    print("distributing training data on the Dask cluster")
+
+    dX = da.from_array(X, chunks=(100, 50))
+    dy = da.from_array(y, chunks=(100,))
+
+    print("beginning training")
+
+    dask_model = lgb.DaskLGBMRegressor(n_estimators=10)
+    dask_model.fit(dX, dy)
+    assert dask_model.fitted_
+
+    print("done training")
+
+    print("predicting on the training data")
+
+    preds = dask_model.predict(dX)
+
+    # the code below uses sklearn.metrics, but this requires pulling all of the
+    # predictions and target values back from workers to the client
+    #
+    # for larger datasets, consider the metrics from dask-ml instead
+    # https://ml.dask.org/modules/api.html#dask-ml-metrics-metrics
+    print("computing MSE")
+
+    preds_local = preds.compute()
+    actuals_local = dy.compute()
+    mse = mean_squared_error(actuals_local, preds_local)
+
+    print(f"MSE: {mse}")

examples/python-guide/dask/ranking.py

@@ -0,0 +1,50 @@
+from pathlib import Path
+
+import dask.array as da
+import numpy as np
+from distributed import Client, LocalCluster
+from sklearn.datasets import load_svmlight_file
+
+import lightgbm as lgb
+
+if __name__ == "__main__":
+    print("loading data")
+
+    rank_example_dir = Path(__file__).absolute().parents[2] / "lambdarank"
+    X, y = load_svmlight_file(str(rank_example_dir / "rank.train"))
+    group = np.loadtxt(str(rank_example_dir / "rank.train.query"))
+
+    print("initializing a Dask cluster")
+
+    cluster = LocalCluster(n_workers=2)
+    client = Client(cluster)
+
+    print("created a Dask LocalCluster")
+
+    print("distributing training data on the Dask cluster")
+
+    # split training data into two partitions
+    rows_in_part1 = int(np.sum(group[:100]))
+    rows_in_part2 = X.shape[0] - rows_in_part1
+    num_features = X.shape[1]
+
+    # make this array dense because we're splitting across
+    # a sparse boundary to partition the data
+    X = X.toarray()
+
+    dX = da.from_array(x=X, chunks=[(rows_in_part1, rows_in_part2), (num_features,)])
+    dy = da.from_array(
+        x=y,
+        chunks=[
+            (rows_in_part1, rows_in_part2),
+        ],
+    )
+    dg = da.from_array(x=group, chunks=[(100, group.size - 100)])
+
+    print("beginning training")
+
+    dask_model = lgb.DaskLGBMRanker(n_estimators=10)
+    dask_model.fit(dX, dy, group=dg)
+    assert dask_model.fitted_
+
+    print("done training")

examples/python-guide/dask/regression.py

@@ -0,0 +1,30 @@
+import dask.array as da
+from distributed import Client, LocalCluster
+from sklearn.datasets import make_regression
+
+import lightgbm as lgb
+
+if __name__ == "__main__":
+    print("loading data")
+
+    X, y = make_regression(n_samples=1000, n_features=50)
+
+    print("initializing a Dask cluster")
+
+    cluster = LocalCluster(n_workers=2)
+    client = Client(cluster)
+
+    print("created a Dask LocalCluster")
+
+    print("distributing training data on the Dask cluster")
+
+    dX = da.from_array(X, chunks=(100, 50))
+    dy = da.from_array(y, chunks=(100,))
+
+    print("beginning training")
+
+    dask_model = lgb.DaskLGBMRegressor(n_estimators=10)
+    dask_model.fit(dX, dy)
+    assert dask_model.fitted_
+
+    print("done training")