{ "cells": [ { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "Copyright (c) 2020-2021 Microsoft Corporation. All rights reserved. \n", "\n", "Licensed under the MIT License.\n", "\n", "# Run FLAML in AzureML\n", "\n", "\n", "## 1. Introduction\n", "\n", "FLAML is a Python library (https://github.com/microsoft/FLAML) designed to automatically produce accurate machine learning models \n", "with low computational cost. It is fast and cheap. The simple and lightweight design makes it easy \n", "to use and extend, such as adding new learners. FLAML can \n", "- serve as an economical AutoML engine,\n", "- be used as a fast hyperparameter tuning tool, or \n", "- be embedded in self-tuning software that requires low latency & resource in repetitive\n", " tuning tasks.\n", "\n", "In this notebook, we use one real data example (binary classification) to showcase how to use FLAML library together with AzureML.\n", "\n", "FLAML requires `Python>=3.6`. To run this notebook example, please install flaml with the `notebook` and `azureml` option:\n", "```bash\n", "pip install flaml[notebook,azureml]\n", "```" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "!pip install flaml[notebook,azureml]" ] }, { "source": [ "### Enable mlflow in AzureML workspace" ], "cell_type": "markdown", "metadata": {} }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "import mlflow\n", "from azureml.core import Workspace\n", "\n", "ws = Workspace.from_config()\n", "mlflow.set_tracking_uri(ws.get_mlflow_tracking_uri())" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "## 2. Classification Example\n", "### Load data and preprocess\n", "\n", "Download [Airlines dataset](https://www.openml.org/d/1169) from OpenML. The task is to predict whether a given flight will be delayed, given the information of the scheduled departure." ] }, { "cell_type": "code", "execution_count": 2, "metadata": { "slideshow": { "slide_type": "subslide" }, "tags": [] }, "outputs": [ { "output_type": "stream", "name": "stdout", "text": [ "load dataset from ./openml_ds1169.pkl\n", "Dataset name: airlines\n", "X_train.shape: (404537, 7), y_train.shape: (404537,);\n", "X_test.shape: (134846, 7), y_test.shape: (134846,)\n" ] } ], "source": [ "from flaml.data import load_openml_dataset\n", "X_train, X_test, y_train, y_test = load_openml_dataset(dataset_id = 1169, data_dir = './')" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### Run FLAML\n", "In the FLAML automl run configuration, users can specify the task type, time budget, error metric, learner list, whether to subsample, resampling strategy type, and so on. All these arguments have default values which will be used if users do not provide them. For example, the default ML learners of FLAML are `['lgbm', 'xgboost', 'catboost', 'rf', 'extra_tree', 'lrl1']`. " ] }, { "cell_type": "code", "execution_count": 3, "metadata": { "slideshow": { "slide_type": "slide" } }, "outputs": [], "source": [ "''' import AutoML class from flaml package '''\n", "from flaml import AutoML\n", "automl = AutoML()" ] }, { "cell_type": "code", "execution_count": 4, "metadata": { "slideshow": { "slide_type": "slide" } }, "outputs": [], "source": [ "settings = {\n", " \"time_budget\": 60, # total running time in seconds\n", " \"metric\": 'accuracy', # primary metrics can be chosen from: ['accuracy','roc_auc','f1','log_loss','mae','mse','r2']\n", " \"estimator_list\": ['lgbm', 'rf', 'xgboost'], # list of ML learners\n", " \"task\": 'classification', # task type \n", " \"sample\": False, # whether to subsample training data\n", " \"log_file_name\": 'airlines_experiment.log', # flaml log file\n", "}" ] }, { "cell_type": "code", "execution_count": 5, "metadata": { "slideshow": { "slide_type": "slide" }, "tags": [] }, "outputs": [ { "output_type": "stream", "name": "stderr", "text": [ "INFO - Evaluation method: holdout\n", "INFO - Using StratifiedKFold\n", "INFO - Minimizing error metric: 1-accuracy\n", "INFO - List of ML learners in AutoML Run: ['lgbm', 'rf', 'xgboost']\n", "INFO - iteration 0 current learner lgbm\n", "INFO - at 1.6s,\tbest lgbm's error=0.3771,\tbest lgbm's error=0.3771\n", "INFO - iteration 1 current learner lgbm\n", "INFO - at 4.7s,\tbest lgbm's error=0.3771,\tbest lgbm's error=0.3771\n", "INFO - iteration 2 current learner lgbm\n", "INFO - at 5.6s,\tbest lgbm's error=0.3751,\tbest lgbm's error=0.3751\n", "INFO - iteration 3 current learner xgboost\n", "INFO - at 9.6s,\tbest xgboost's error=0.3750,\tbest xgboost's error=0.3750\n", "INFO - iteration 4 current learner lgbm\n", "INFO - at 12.5s,\tbest lgbm's error=0.3751,\tbest xgboost's error=0.3750\n", "INFO - iteration 5 current learner lgbm\n", "INFO - at 14.3s,\tbest lgbm's error=0.3558,\tbest lgbm's error=0.3558\n", "INFO - iteration 6 current learner rf\n", "INFO - at 22.7s,\tbest rf's error=0.3876,\tbest lgbm's error=0.3558\n", "INFO - iteration 7 current learner lgbm\n", "INFO - at 24.3s,\tbest lgbm's error=0.3492,\tbest lgbm's error=0.3492\n", "INFO - iteration 8 current learner lgbm\n", "INFO - at 27.7s,\tbest lgbm's error=0.3492,\tbest lgbm's error=0.3492\n", "INFO - iteration 9 current learner lgbm\n", "INFO - at 29.5s,\tbest lgbm's error=0.3470,\tbest lgbm's error=0.3470\n", "INFO - iteration 10 current learner rf\n", "INFO - at 35.9s,\tbest rf's error=0.3876,\tbest lgbm's error=0.3470\n", "INFO - iteration 11 current learner rf\n", "INFO - at 43.4s,\tbest rf's error=0.3839,\tbest lgbm's error=0.3470\n", "INFO - iteration 12 current learner xgboost\n", "INFO - at 44.3s,\tbest xgboost's error=0.3750,\tbest lgbm's error=0.3470\n", "INFO - iteration 13 current learner xgboost\n", "INFO - at 45.1s,\tbest xgboost's error=0.3750,\tbest lgbm's error=0.3470\n", "INFO - iteration 14 current learner xgboost\n", "INFO - at 45.9s,\tbest xgboost's error=0.3736,\tbest lgbm's error=0.3470\n", "INFO - iteration 15 current learner lgbm\n", "INFO - at 47.5s,\tbest lgbm's error=0.3470,\tbest lgbm's error=0.3470\n", "INFO - iteration 16 current learner lgbm\n", "INFO - at 49.1s,\tbest lgbm's error=0.3470,\tbest lgbm's error=0.3470\n", "INFO - iteration 17 current learner lgbm\n", "INFO - at 50.6s,\tbest lgbm's error=0.3470,\tbest lgbm's error=0.3470\n", "INFO - iteration 18 current learner lgbm\n", "INFO - at 52.5s,\tbest lgbm's error=0.3412,\tbest lgbm's error=0.3412\n", "INFO - iteration 19 current learner lgbm\n", "INFO - at 56.7s,\tbest lgbm's error=0.3374,\tbest lgbm's error=0.3374\n", "INFO - iteration 20 current learner xgboost\n", "INFO - at 59.8s,\tbest xgboost's error=0.3696,\tbest lgbm's error=0.3374\n", "INFO - iteration 21 current learner rf\n", "INFO - no enough budget for learner rf\n", "INFO - selected model: LGBMClassifier(colsample_bytree=0.99236562733598,\n", " learning_rate=0.32864729892819683, max_bin=1023,\n", " min_child_weight=5.630999649172112, n_estimators=6,\n", " num_leaves=1073, objective='binary',\n", " reg_alpha=1.978160373587824e-09, reg_lambda=1.0)\n", "INFO - fit succeeded\n" ] } ], "source": [ "mlflow.set_experiment(\"flaml\")\n", "with mlflow.start_run() as run:\n", " '''The main flaml automl API'''\n", " automl.fit(X_train = X_train, y_train = y_train, **settings)" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### Best model and metric" ] }, { "cell_type": "code", "execution_count": 6, "metadata": { "slideshow": { "slide_type": "slide" }, "tags": [] }, "outputs": [ { "output_type": "stream", "name": "stdout", "text": [ "Best ML leaner: lgbm\nBest hyperparmeter config: {'n_estimators': 6.0, 'max_leaves': 1073.0, 'min_child_weight': 5.630999649172112, 'learning_rate': 0.32864729892819683, 'subsample': 1.0, 'log_max_bin': 10.0, 'colsample_bytree': 0.99236562733598, 'reg_alpha': 1.978160373587824e-09, 'reg_lambda': 1.0}\nBest accuracy on validation data: 0.6626\nTraining duration of best run: 2.253 s\n" ] } ], "source": [ "''' retrieve best config and best learner'''\n", "print('Best ML leaner:', automl.best_estimator)\n", "print('Best hyperparmeter config:', automl.best_config)\n", "print('Best accuracy on validation data: {0:.4g}'.format(1-automl.best_loss))\n", "print('Training duration of best run: {0:.4g} s'.format(automl.best_config_train_time))" ] }, { "cell_type": "code", "execution_count": 7, "metadata": { "slideshow": { "slide_type": "slide" } }, "outputs": [ { "output_type": "execute_result", "data": { "text/plain": [ "LGBMClassifier(colsample_bytree=0.99236562733598,\n", " learning_rate=0.32864729892819683, max_bin=1023,\n", " min_child_weight=5.630999649172112, n_estimators=6,\n", " num_leaves=1073, objective='binary',\n", " reg_alpha=1.978160373587824e-09, reg_lambda=1.0)" ] }, "metadata": {}, "execution_count": 7 } ], "source": [ "automl.model" ] }, { "cell_type": "code", "execution_count": 8, "metadata": { "slideshow": { "slide_type": "slide" } }, "outputs": [], "source": [ "''' pickle and save the automl object '''\n", "import pickle\n", "with open('automl.pkl', 'wb') as f:\n", " pickle.dump(automl, f, pickle.HIGHEST_PROTOCOL)" ] }, { "cell_type": "code", "execution_count": 9, "metadata": { "slideshow": { "slide_type": "slide" }, "tags": [] }, "outputs": [ { "output_type": "stream", "name": "stdout", "text": [ "Predicted labels [1 0 1 ... 1 0 0]\nTrue labels [0 0 0 ... 0 1 0]\n" ] } ], "source": [ "''' compute predictions of testing dataset ''' \n", "y_pred = automl.predict(X_test)\n", "print('Predicted labels', y_pred)\n", "print('True labels', y_test)\n", "y_pred_proba = automl.predict_proba(X_test)[:,1]" ] }, { "cell_type": "code", "execution_count": 10, "metadata": { "slideshow": { "slide_type": "slide" }, "tags": [] }, "outputs": [ { "output_type": "stream", "name": "stdout", "text": [ "accuracy = 0.6649585453035315\n", "roc_auc = 0.7164009096685227\n", "log_loss = 0.6109261780043986\n", "f1 = 0.5708885406278198\n" ] } ], "source": [ "''' compute different metric values on testing dataset'''\n", "from flaml.ml import sklearn_metric_loss_score\n", "print('accuracy', '=', 1 - sklearn_metric_loss_score('accuracy', y_pred, y_test))\n", "print('roc_auc', '=', 1 - sklearn_metric_loss_score('roc_auc', y_pred_proba, y_test))\n", "print('log_loss', '=', sklearn_metric_loss_score('log_loss', y_pred_proba, y_test))\n", "print('f1', '=', 1 - sklearn_metric_loss_score('f1', y_pred, y_test))" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### Log history" ] }, { "cell_type": "code", "execution_count": 11, "metadata": { "slideshow": { "slide_type": "subslide" }, "tags": [] }, "outputs": [ { "output_type": "stream", "name": "stdout", "text": [ "{'Current Learner': 'lgbm', 'Current Sample': 364083, 'Current Hyper-parameters': {'n_estimators': 4, 'max_leaves': 4, 'min_child_weight': 20.0, 'learning_rate': 0.1, 'subsample': 1.0, 'log_max_bin': 8, 'colsample_bytree': 1.0, 'reg_alpha': 1e-10, 'reg_lambda': 1.0}, 'Best Learner': 'lgbm', 'Best Hyper-parameters': {'n_estimators': 4, 'max_leaves': 4, 'min_child_weight': 20.0, 'learning_rate': 0.1, 'subsample': 1.0, 'log_max_bin': 8, 'colsample_bytree': 1.0, 'reg_alpha': 1e-10, 'reg_lambda': 1.0}}\n{'Current Learner': 'lgbm', 'Current Sample': 364083, 'Current Hyper-parameters': {'n_estimators': 4.0, 'max_leaves': 4.0, 'min_child_weight': 20.0, 'learning_rate': 0.46335414315327306, 'subsample': 0.9339389930838808, 'log_max_bin': 10.0, 'colsample_bytree': 0.9904286645657556, 'reg_alpha': 2.841147337412889e-10, 'reg_lambda': 0.12000833497054482}, 'Best Learner': 'lgbm', 'Best Hyper-parameters': {'n_estimators': 4.0, 'max_leaves': 4.0, 'min_child_weight': 20.0, 'learning_rate': 0.46335414315327306, 'subsample': 0.9339389930838808, 'log_max_bin': 10.0, 'colsample_bytree': 0.9904286645657556, 'reg_alpha': 2.841147337412889e-10, 'reg_lambda': 0.12000833497054482}}\n{'Current Learner': 'xgboost', 'Current Sample': 364083, 'Current Hyper-parameters': {'n_estimators': 4, 'max_leaves': 4, 'min_child_weight': 20.0, 'learning_rate': 0.1, 'subsample': 1.0, 'colsample_bylevel': 1.0, 'colsample_bytree': 1.0, 'reg_alpha': 1e-10, 'reg_lambda': 1.0}, 'Best Learner': 'xgboost', 'Best Hyper-parameters': {'n_estimators': 4, 'max_leaves': 4, 'min_child_weight': 20.0, 'learning_rate': 0.1, 'subsample': 1.0, 'colsample_bylevel': 1.0, 'colsample_bytree': 1.0, 'reg_alpha': 1e-10, 'reg_lambda': 1.0}}\n{'Current Learner': 'lgbm', 'Current Sample': 364083, 'Current Hyper-parameters': {'n_estimators': 23.0, 'max_leaves': 4.0, 'min_child_weight': 20.0, 'learning_rate': 1.0, 'subsample': 0.9917683183663918, 'log_max_bin': 10.0, 'colsample_bytree': 0.9858892907525497, 'reg_alpha': 3.8783982645515837e-10, 'reg_lambda': 0.36607431863072826}, 'Best Learner': 'lgbm', 'Best Hyper-parameters': {'n_estimators': 23.0, 'max_leaves': 4.0, 'min_child_weight': 20.0, 'learning_rate': 1.0, 'subsample': 0.9917683183663918, 'log_max_bin': 10.0, 'colsample_bytree': 0.9858892907525497, 'reg_alpha': 3.8783982645515837e-10, 'reg_lambda': 0.36607431863072826}}\n{'Current Learner': 'lgbm', 'Current Sample': 364083, 'Current Hyper-parameters': {'n_estimators': 11.0, 'max_leaves': 17.0, 'min_child_weight': 14.947587304572773, 'learning_rate': 0.6092558236172073, 'subsample': 0.9659256891661986, 'log_max_bin': 10.0, 'colsample_bytree': 1.0, 'reg_alpha': 3.816590663384559e-08, 'reg_lambda': 0.4482946615262561}, 'Best Learner': 'lgbm', 'Best Hyper-parameters': {'n_estimators': 11.0, 'max_leaves': 17.0, 'min_child_weight': 14.947587304572773, 'learning_rate': 0.6092558236172073, 'subsample': 0.9659256891661986, 'log_max_bin': 10.0, 'colsample_bytree': 1.0, 'reg_alpha': 3.816590663384559e-08, 'reg_lambda': 0.4482946615262561}}\n{'Current Learner': 'lgbm', 'Current Sample': 364083, 'Current Hyper-parameters': {'n_estimators': 7.0, 'max_leaves': 51.0, 'min_child_weight': 20.0, 'learning_rate': 0.8834537640176922, 'subsample': 1.0, 'log_max_bin': 10.0, 'colsample_bytree': 0.9837052481490312, 'reg_alpha': 4.482246955743696e-08, 'reg_lambda': 0.028657570201141073}, 'Best Learner': 'lgbm', 'Best Hyper-parameters': {'n_estimators': 7.0, 'max_leaves': 51.0, 'min_child_weight': 20.0, 'learning_rate': 0.8834537640176922, 'subsample': 1.0, 'log_max_bin': 10.0, 'colsample_bytree': 0.9837052481490312, 'reg_alpha': 4.482246955743696e-08, 'reg_lambda': 0.028657570201141073}}\n{'Current Learner': 'lgbm', 'Current Sample': 364083, 'Current Hyper-parameters': {'n_estimators': 15.0, 'max_leaves': 165.0, 'min_child_weight': 11.09973081317571, 'learning_rate': 1.0, 'subsample': 0.9847553005974036, 'log_max_bin': 9.0, 'colsample_bytree': 0.9508927355861483, 'reg_alpha': 2.031936014930936e-06, 'reg_lambda': 0.00624701632609755}, 'Best Learner': 'lgbm', 'Best Hyper-parameters': {'n_estimators': 15.0, 'max_leaves': 165.0, 'min_child_weight': 11.09973081317571, 'learning_rate': 1.0, 'subsample': 0.9847553005974036, 'log_max_bin': 9.0, 'colsample_bytree': 0.9508927355861483, 'reg_alpha': 2.031936014930936e-06, 'reg_lambda': 0.00624701632609755}}\n{'Current Learner': 'lgbm', 'Current Sample': 364083, 'Current Hyper-parameters': {'n_estimators': 6.0, 'max_leaves': 1073.0, 'min_child_weight': 5.630999649172112, 'learning_rate': 0.32864729892819683, 'subsample': 1.0, 'log_max_bin': 10.0, 'colsample_bytree': 0.99236562733598, 'reg_alpha': 1.978160373587824e-09, 'reg_lambda': 1.0}, 'Best Learner': 'lgbm', 'Best Hyper-parameters': {'n_estimators': 6.0, 'max_leaves': 1073.0, 'min_child_weight': 5.630999649172112, 'learning_rate': 0.32864729892819683, 'subsample': 1.0, 'log_max_bin': 10.0, 'colsample_bytree': 0.99236562733598, 'reg_alpha': 1.978160373587824e-09, 'reg_lambda': 1.0}}\n" ] } ], "source": [ "from flaml.data import get_output_from_log\n", "time_history, best_valid_loss_history, valid_loss_history, config_history, train_loss_history = \\\n", " get_output_from_log(filename = settings['log_file_name'], time_budget = 60)\n", "\n", "for config in config_history:\n", " print(config)" ] }, { "cell_type": "code", "execution_count": 12, "metadata": { "slideshow": { "slide_type": "slide" } }, "outputs": [ { "output_type": "display_data", "data": { "text/plain": "
", "image/svg+xml": "\r\n\r\n\r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n\r\n", "image/png": "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\n" }, "metadata": { "needs_background": "light" } } ], "source": [ "import matplotlib.pyplot as plt\n", "import numpy as np\n", "\n", "plt.title('Learning Curve')\n", "plt.xlabel('Wall Clock Time (s)')\n", "plt.ylabel('Validation Accuracy')\n", "plt.scatter(time_history, 1-np.array(valid_loss_history))\n", "plt.step(time_history, 1-np.array(best_valid_loss_history), where='post')\n", "plt.show()" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "## 3. Customized Learner" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "Some experienced automl users may have a preferred model to tune or may already have a reasonably by-hand-tuned model before launching the automl experiment. They need to select optimal configurations for the customized model mixed with standard built-in learners. \n", "\n", "FLAML can easily incorporate customized/new learners (preferably with sklearn API) provided by users in a real-time manner, as demonstrated below." ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### Example of Regularized Greedy Forest\n", "\n", "[Regularized Greedy Forest](https://arxiv.org/abs/1109.0887) (RGF) is a machine learning method currently not included in FLAML. The RGF has many tuning parameters, the most critical of which are: `[max_leaf, n_iter, n_tree_search, opt_interval, min_samples_leaf]`. To run a customized/new learner, the user needs to provide the following information:\n", "* an implementation of the customized/new learner\n", "* a list of hyperparameter names and types\n", "* rough ranges of hyperparameters (i.e., upper/lower bounds)\n", "* choose initial value corresponding to low cost for cost-related hyperparameters (e.g., initial value for max_leaf and n_iter should be small)\n", "\n", "In this example, the above information for RGF is wrapped in a python class called *MyRegularizedGreedyForest* that exposes the hyperparameters." ] }, { "cell_type": "code", "execution_count": 13, "metadata": { "slideshow": { "slide_type": "slide" } }, "outputs": [], "source": [ "''' SKLearnEstimator is the super class for a sklearn learner '''\n", "from flaml.model import SKLearnEstimator\n", "from flaml import tune\n", "from rgf.sklearn import RGFClassifier, RGFRegressor\n", "\n", "\n", "class MyRegularizedGreedyForest(SKLearnEstimator):\n", "\n", "\n", " def __init__(self, task = 'binary:logistic', n_jobs = 1, **params):\n", " '''Constructor\n", " \n", " Args:\n", " task: A string of the task type, one of\n", " 'binary:logistic', 'multi:softmax', 'regression'\n", " n_jobs: An integer of the number of parallel threads\n", " params: A dictionary of the hyperparameter names and values\n", " '''\n", "\n", " super().__init__(task, **params)\n", "\n", " '''task=regression for RGFRegressor; \n", " binary:logistic and multiclass:softmax for RGFClassifier'''\n", " if 'regression' in task:\n", " self.estimator_class = RGFRegressor\n", " else:\n", " self.estimator_class = RGFClassifier\n", "\n", " # convert to int for integer hyperparameters\n", " self.params = {\n", " \"n_jobs\": n_jobs,\n", " 'max_leaf': int(params['max_leaf']),\n", " 'n_iter': int(params['n_iter']),\n", " 'n_tree_search': int(params['n_tree_search']),\n", " 'opt_interval': int(params['opt_interval']),\n", " 'learning_rate': params['learning_rate'],\n", " 'min_samples_leaf':int(params['min_samples_leaf'])\n", " } \n", "\n", " @classmethod\n", " def search_space(cls, data_size, task):\n", " '''[required method] search space\n", "\n", " Returns:\n", " A dictionary of the search space. \n", " Each key is the name of a hyperparameter, and value is a dict with\n", " its domain and init_value (optional), cat_hp_cost (optional) \n", " e.g., \n", " {'domain': tune.randint(lower=1, upper=10), 'init_value': 1}\n", " '''\n", " space = { \n", " 'max_leaf': {'domain': tune.qloguniform(lower = 4, upper = data_size, q = 1), 'init_value': 4},\n", " 'n_iter': {'domain': tune.qloguniform(lower = 1, upper = data_size, q = 1), 'init_value': 1},\n", " 'n_tree_search': {'domain': tune.qloguniform(lower = 1, upper = 32768, q = 1), 'init_value': 1},\n", " 'opt_interval': {'domain': tune.qloguniform(lower = 1, upper = 10000, q = 1), 'init_value': 100},\n", " 'learning_rate': {'domain': tune.loguniform(lower = 0.01, upper = 20.0)},\n", " 'min_samples_leaf': {'domain': tune.qloguniform(lower = 1, upper = 20, q = 1), 'init_value': 20},\n", " }\n", " return space\n", "\n", " @classmethod\n", " def size(cls, config):\n", " '''[optional method] memory size of the estimator in bytes\n", " \n", " Args:\n", " config - the dict of the hyperparameter config\n", "\n", " Returns:\n", " A float of the memory size required by the estimator to train the\n", " given config\n", " '''\n", " max_leaves = int(round(config['max_leaf']))\n", " n_estimators = int(round(config['n_iter']))\n", " return (max_leaves*3 + (max_leaves-1)*4 + 1.0)*n_estimators*8\n", "\n", " @classmethod\n", " def cost_relative2lgbm(cls):\n", " '''[optional method] relative cost compared to lightgbm\n", " '''\n", " return 1.0\n" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### Add Customized Learner and Run FLAML AutoML\n", "\n", "After adding RGF into the list of learners, we run automl by tuning hyperpameters of RGF as well as the default learners. " ] }, { "cell_type": "code", "execution_count": 14, "metadata": { "slideshow": { "slide_type": "slide" } }, "outputs": [], "source": [ "automl = AutoML()\n", "automl.add_learner(learner_name = 'RGF', learner_class = MyRegularizedGreedyForest)" ] }, { "cell_type": "code", "execution_count": 15, "metadata": { "slideshow": { "slide_type": "slide" }, "tags": [] }, "outputs": [ { "output_type": "stream", "name": "stderr", "text": [ "INFO - Evaluation method: holdout\n", "INFO - Using StratifiedKFold\n", "INFO - Minimizing error metric: 1-accuracy\n", "INFO - List of ML learners in AutoML Run: ['RGF', 'lgbm', 'rf', 'xgboost']\n", "INFO - iteration 0 current learner RGF\n", "INFO - at 1.3s,\tbest RGF's error=0.3787,\tbest RGF's error=0.3787\n", "INFO - iteration 1 current learner RGF\n", "INFO - at 4.4s,\tbest RGF's error=0.3787,\tbest RGF's error=0.3787\n", "INFO - iteration 2 current learner RGF\n", "INFO - at 5.3s,\tbest RGF's error=0.3787,\tbest RGF's error=0.3787\n", "INFO - iteration 3 current learner lgbm\n", "INFO - at 5.3s,\tbest lgbm's error=0.3777,\tbest lgbm's error=0.3777\n", "INFO - iteration 4 current learner RGF\n", "INFO - at 8.4s,\tbest RGF's error=0.3787,\tbest lgbm's error=0.3777\n", "INFO - iteration 5 current learner lgbm\n", "INFO - at 8.4s,\tbest lgbm's error=0.3777,\tbest lgbm's error=0.3777\n", "INFO - iteration 6 current learner lgbm\n", "INFO - at 8.5s,\tbest lgbm's error=0.3669,\tbest lgbm's error=0.3669\n", "INFO - iteration 7 current learner lgbm\n", "INFO - at 10.4s,\tbest lgbm's error=0.3669,\tbest lgbm's error=0.3669\n", "INFO - iteration 8 current learner lgbm\n", "INFO - at 10.5s,\tbest lgbm's error=0.3662,\tbest lgbm's error=0.3662\n", "INFO - iteration 9 current learner lgbm\n", "INFO - at 12.4s,\tbest lgbm's error=0.3636,\tbest lgbm's error=0.3636\n", "INFO - iteration 10 current learner lgbm\n", "INFO - at 14.4s,\tbest lgbm's error=0.3621,\tbest lgbm's error=0.3621\n", "INFO - iteration 11 current learner lgbm\n", "INFO - at 16.3s,\tbest lgbm's error=0.3621,\tbest lgbm's error=0.3621\n", "INFO - iteration 12 current learner lgbm\n", "INFO - at 16.4s,\tbest lgbm's error=0.3621,\tbest lgbm's error=0.3621\n", "INFO - iteration 13 current learner lgbm\n", "INFO - at 16.4s,\tbest lgbm's error=0.3621,\tbest lgbm's error=0.3621\n", "INFO - iteration 14 current learner lgbm\n", "INFO - at 16.5s,\tbest lgbm's error=0.3621,\tbest lgbm's error=0.3621\n", "INFO - iteration 15 current learner lgbm\n", "INFO - at 16.6s,\tbest lgbm's error=0.3621,\tbest lgbm's error=0.3621\n", "INFO - iteration 16 current learner RGF\n", "INFO - at 17.5s,\tbest RGF's error=0.3787,\tbest lgbm's error=0.3621\n", "INFO - iteration 17 current learner lgbm\n", "INFO - at 18.8s,\tbest lgbm's error=0.3621,\tbest lgbm's error=0.3621\n", "INFO - iteration 18 current learner xgboost\n", "INFO - at 18.9s,\tbest xgboost's error=0.3787,\tbest lgbm's error=0.3621\n", "INFO - iteration 19 current learner xgboost\n", "INFO - at 19.0s,\tbest xgboost's error=0.3787,\tbest lgbm's error=0.3621\n", "INFO - iteration 20 current learner xgboost\n", "INFO - at 19.1s,\tbest xgboost's error=0.3757,\tbest lgbm's error=0.3621\n", "INFO - iteration 21 current learner RGF\n", "INFO - at 20.1s,\tbest RGF's error=0.3787,\tbest lgbm's error=0.3621\n", "INFO - iteration 22 current learner lgbm\n", "INFO - at 21.6s,\tbest lgbm's error=0.3611,\tbest lgbm's error=0.3611\n", "INFO - iteration 23 current learner xgboost\n", "INFO - at 23.5s,\tbest xgboost's error=0.3756,\tbest lgbm's error=0.3611\n", "INFO - iteration 24 current learner rf\n", "INFO - at 24.0s,\tbest rf's error=0.4046,\tbest lgbm's error=0.3611\n", "INFO - iteration 25 current learner xgboost\n", "INFO - at 24.0s,\tbest xgboost's error=0.3620,\tbest lgbm's error=0.3611\n", "INFO - iteration 26 current learner xgboost\n", "INFO - at 24.1s,\tbest xgboost's error=0.3620,\tbest lgbm's error=0.3611\n", "INFO - iteration 27 current learner xgboost\n", "INFO - at 24.2s,\tbest xgboost's error=0.3620,\tbest lgbm's error=0.3611\n", "INFO - iteration 28 current learner xgboost\n", "INFO - at 24.3s,\tbest xgboost's error=0.3620,\tbest lgbm's error=0.3611\n", "INFO - iteration 29 current learner xgboost\n", "INFO - at 24.4s,\tbest xgboost's error=0.3620,\tbest lgbm's error=0.3611\n", "INFO - iteration 30 current learner lgbm\n", "INFO - at 25.4s,\tbest lgbm's error=0.3585,\tbest lgbm's error=0.3585\n", "INFO - iteration 31 current learner lgbm\n", "INFO - at 27.9s,\tbest lgbm's error=0.3585,\tbest lgbm's error=0.3585\n", "INFO - iteration 32 current learner lgbm\n", "INFO - at 29.8s,\tbest lgbm's error=0.3531,\tbest lgbm's error=0.3531\n", "INFO - iteration 33 current learner xgboost\n", "INFO - at 31.9s,\tbest xgboost's error=0.3598,\tbest lgbm's error=0.3531\n", "INFO - iteration 34 current learner lgbm\n", "INFO - at 33.1s,\tbest lgbm's error=0.3522,\tbest lgbm's error=0.3522\n", "INFO - iteration 35 current learner rf\n", "INFO - at 35.5s,\tbest rf's error=0.4046,\tbest lgbm's error=0.3522\n", "INFO - iteration 36 current learner xgboost\n", "INFO - at 35.6s,\tbest xgboost's error=0.3593,\tbest lgbm's error=0.3522\n", "INFO - iteration 37 current learner rf\n", "INFO - at 36.0s,\tbest rf's error=0.4046,\tbest lgbm's error=0.3522\n", "INFO - iteration 38 current learner rf\n", "INFO - at 36.5s,\tbest rf's error=0.4046,\tbest lgbm's error=0.3522\n", "INFO - iteration 39 current learner lgbm\n", "INFO - at 39.0s,\tbest lgbm's error=0.3359,\tbest lgbm's error=0.3359\n", "INFO - iteration 40 current learner rf\n", "INFO - at 41.8s,\tbest rf's error=0.3968,\tbest lgbm's error=0.3359\n", "INFO - iteration 41 current learner lgbm\n", "INFO - at 44.1s,\tbest lgbm's error=0.3359,\tbest lgbm's error=0.3359\n", "INFO - iteration 42 current learner RGF\n", "INFO - at 45.6s,\tbest RGF's error=0.3787,\tbest lgbm's error=0.3359\n", "INFO - iteration 43 current learner lgbm\n", "INFO - at 50.1s,\tbest lgbm's error=0.3359,\tbest lgbm's error=0.3359\n", "INFO - iteration 44 current learner xgboost\n", "INFO - at 50.3s,\tbest xgboost's error=0.3593,\tbest lgbm's error=0.3359\n", "INFO - iteration 45 current learner lgbm\n", "INFO - at 52.0s,\tbest lgbm's error=0.3359,\tbest lgbm's error=0.3359\n", "INFO - iteration 46 current learner RGF\n", "INFO - at 61.6s,\tbest RGF's error=0.3787,\tbest lgbm's error=0.3359\n", "INFO - selected model: LGBMClassifier(colsample_bytree=0.9950430045845675,\n", " learning_rate=0.23086971995751512, max_bin=1023,\n", " min_child_weight=5.096453108920863, n_estimators=14,\n", " num_leaves=453, objective='binary', reg_alpha=1e-10,\n", " reg_lambda=1.0, subsample=0.9433718793194579)\n", "INFO - fit succeeded\n" ] } ], "source": [ "settings = {\n", " \"time_budget\": 60, # total running time in seconds\n", " \"metric\": 'accuracy', \n", " \"estimator_list\": ['RGF', 'lgbm', 'rf', 'xgboost'], # list of ML learners\n", " \"task\": 'classification', # task type \n", " \"sample\": True, # whether to subsample training data\n", " \"log_file_name\": 'airlines_experiment_custom.log', # flaml log file\n", " \"log_training_metric\": True, # whether to log training metric\n", "}\n", "\n", "mlflow.set_experiment(\"flaml_custom\")\n", "with mlflow.start_run() as run:\n", " '''The main flaml automl API'''\n", " automl.fit(X_train = X_train, y_train = y_train, **settings)" ] } ], "metadata": { "kernelspec": { "name": "python3", "display_name": "Python 3.7.7 64-bit ('flaml': conda)", "metadata": { "interpreter": { "hash": "bfcd9a6a9254a5e160761a1fd7a9e444f011592c6770d9f4180dde058a9df5dd" } } }, "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.7.7-final" } }, "nbformat": 4, "nbformat_minor": 2 }