From c8da829e4dd5a2c5c2a97734370ae8c9342bd85b Mon Sep 17 00:00:00 2001 From: Qingyun Wu Date: Fri, 4 Jun 2021 13:52:52 -0400 Subject: [PATCH] ChaCha documentation (#100) * update readme * naming --- README.md | 10 +++++----- flaml/onlineml/README.md | 39 +++++++++++++++++++++++++++++++++++++ flaml/onlineml/autovw.py | 4 ++-- notebook/flaml_autovw.ipynb | 2 +- 4 files changed, 47 insertions(+), 8 deletions(-) create mode 100644 flaml/onlineml/README.md diff --git a/README.md b/README.md index 7c9be73a8b..593a6a5665 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,11 @@ tune.run(train_with_config, config={…}, low_cost_partial_config={…}, time_bu * For classification and regression tasks, find quality models with lower computational resources. * Users can choose their desired customizability: minimal customization (computational resource budget), medium customization (e.g., scikit-style learner, search space and metric), full customization (arbitrary training and evaluation code). -* Allow human guidance in hyperparameter tuning to respect prior on certain subspaces but also able to explore other subspaces. +* Allow human guidance in hyperparameter tuning to respect prior on certain subspaces but also able to explore other subspaces. Read more about the +hyperparameter optimization methods +in FLAML [here](https://github.com/microsoft/FLAML/tree/main/flaml/tune). They can be used beyond the AutoML context. +And they can be used in distributed HPO frameworks such as ray tune or nni. +* Support online AutoML: automatic hyperparameter tuning for online learning algorithms. Read more about the online AutoML method in FLAML [here](https://github.com/microsoft/FLAML/tree/main/flaml/onlineml). ## Examples @@ -122,10 +126,6 @@ Please find the API documentation [here](https://microsoft.github.io/FLAML/). Please find demo and tutorials of FLAML [here](https://www.youtube.com/channel/UCfU0zfFXHXdAd5x-WvFBk5A) -Read more about the -hyperparameter optimization methods -in FLAML [here](https://github.com/microsoft/FLAML/tree/main/flaml/tune). They can be used beyond the AutoML context. -And they can be used in distributed HPO frameworks such as ray tune or nni. For more technical details, please check our papers. diff --git a/flaml/onlineml/README.md b/flaml/onlineml/README.md new file mode 100644 index 0000000000..926721055e --- /dev/null +++ b/flaml/onlineml/README.md @@ -0,0 +1,39 @@ +# ChaCha for Online AutoML + +FLAML includes *ChaCha* which is an automatic hyperparameter tuning solution for online machine learning. Online machine learning has the following properties: (1) data comes in sequential order; and (2) the performance of the machine learning model is evaluated online, i.e., at every iteration. *ChaCha* performs online AutoML respecting the aforementioned properties of online learning, and at the same time respecting the following constraints: (1) only a small constant number of 'live' models are allowed to perform online learning at the same time; and (2) no model persistence or offline training is allowed, which means that once we decide to replace a 'live' model with a new one, the replaced model can no longer be retrieved. + +For more technical details about *ChaCha*, please check our paper. + +* ChaCha for online AutoML. Qingyun Wu, Chi Wang, John Langford, Paul Mineiro and Marco Rossi. To appear in ICML 2021. + +## `AutoVW` + +`flaml.AutoVW` is a realization of *ChaCha* AutoML method with online learners from the open-source online machine learning library [Vowpal Wabbit](https://vowpalwabbit.org/) learner. It can be used to tune both conventional numerical and categorical hyperparameters, such as learning rate, and hyperparameters for featurization choices, such as the namespace (a namespace is a group of features) interactions in Vowpal Wabbit. + +An example of online namespace interactions tuning in VW: + +```python +# require: pip install flaml[vw] +from flaml import AutoVW +'''create an AutoVW instance for tuning namespace interactions''' +autovw = AutoVW(max_live_model_num=5, search_space={'interactions': AutoVW.AUTOMATIC}) +``` + +An example of online tuning of both namespace interactions and learning rate in VW: + +```python +# require: pip install flaml[vw] +from flaml import AutoVW +from flaml.tune import loguniform +''' create an AutoVW instance for tuning namespace interactions and learning rate''' +# set up the search space and init config +search_space_nilr = {'interactions': AutoVW.AUTOMATIC, 'learning_rate': loguniform(lower=2e-10, upper=1.0)} +init_config_nilr = {'interactions': set(), 'learning_rate': 0.5} +# create an AutoVW instance +autovw = AutoVW(max_live_model_num=5, search_space=search_space_nilr, init_config=init_config_nilr) +``` + +A user can use the resulting AutoVW instances `autovw` in a similar way to a vanilla Vowpal Wabbit instance, i.e., `pyvw.vw`, to perform online learning by iteratively calling its `predict(data_example)` and `learn(data_example)` functions at each data example. + +For more examples, please check out +[AutoVW notebook](https://github.com/microsoft/FLAML/blob/main/notebook/flaml_autovw.ipynb). \ No newline at end of file diff --git a/flaml/onlineml/autovw.py b/flaml/onlineml/autovw.py index 3feef97b09..f1e4a16246 100644 --- a/flaml/onlineml/autovw.py +++ b/flaml/onlineml/autovw.py @@ -18,7 +18,7 @@ class AutoVW: AUTO """ WARMSTART_NUM = 100 - AUTO_STRING = '_auto' + AUTOMATIC = '_auto' VW_INTERACTION_ARG_NAME = 'interactions' def __init__(self, @@ -94,7 +94,7 @@ def _setup_trial_runner(self, vw_example): # setup the default search space for the namespace interaction hyperparameter search_space = self._search_space.copy() for k, v in self._search_space.items(): - if k == self.VW_INTERACTION_ARG_NAME and v == self.AUTO_STRING: + if k == self.VW_INTERACTION_ARG_NAME and v == self.AUTOMATIC: raw_namespaces = self.get_ns_feature_dim_from_vw_example(vw_example).keys() search_space[k] = polynomial_expansion_set(init_monomials=set(raw_namespaces)) # setup the init config based on the input _init_config and search space diff --git a/notebook/flaml_autovw.ipynb b/notebook/flaml_autovw.ipynb index 341bd4b3de..6f59e36dde 100644 --- a/notebook/flaml_autovw.ipynb +++ b/notebook/flaml_autovw.ipynb @@ -226,7 +226,7 @@ "from flaml import AutoVW\n", "\n", "'''create an AutoVW instance for tuning namespace interactions'''\n", - "autovw_ni = AutoVW(max_live_model_num=5, search_space={'interactions': AutoVW.AUTO_STRING})\n", + "autovw_ni = AutoVW(max_live_model_num=5, search_space={'interactions': AutoVW.AUTOMATIC})\n", "\n", "# online learning with AutoVW\n", "loss_list_autovw_ni = online_learning_loop(max_iter_num, vw_examples, autovw_ni)\n",