Repository: optuna/optuna
Pull request: Add an Example and Variable Explanations to `HyperBandPruner`.
<!-- Thank you for creating a pull request!

Please go through [our contribution guide][CONTRIBUTING.md] to hopefully get your changes merged quicker.

[CONTRIBUTING.md]: https://github.com/optuna/optuna/blob/master/CONTRIBUTING.md -->

To fix #906 .
Added following:
- example
- explanation for r and eta.


Problem statement:
Hyperband Usage Documentation
First many thanks for the new hyperband pruner.

I would like to request some more information on how to use it. I guess that it is necessary to tune the default parameters. Maybe you could provide some more information then just link to the papers. When should I set which parameter to what value?

The paper talks about an infinite horizon setting. Since I often do not set the number of iterations on optuna but stop it with KeyboardInterrupt is that relevant for me?

Many thanks
Philip

Hints from issue discussion:
Maybe you both could help with this? @crcrpar @arita37 
For example I am interested in the question on how to configure the Hyperband pruner when your trial needs 5 hours to fit and when you can only afford to calculate like 40 trials. And under which conditions is it useful to change the default parameters?

Commit message: Add an example and variable explanations

Patch to review:
diff --git a/optuna/pruners/hyperband.py b/optuna/pruners/hyperband.py
index c9b7137872b..5888298330a 100644
--- a/optuna/pruners/hyperband.py
+++ b/optuna/pruners/hyperband.py
@@ -49,22 +49,40 @@ class HyperbandPruner(BasePruner):
         Thus, for example, if ``HyperbandPruner`` has :math:`4` pruners in it,
         at least :math:`4 \\times 10` pruners are consumed for startup.
 
+    Example:
+
+        We minimize an objective function with Hyperband pruning algorithm.
+
+        .. testcode::
+
+            from optuna import create_study
+            from optuna.pruners import HyperbandPruner
+
+            def objective(trial):
+                x = trial.suggest_uniform('x', -1, 1)
+                return x ** 2
+
+            study = create_study(pruner=HyperbandPruner())
+            study.optimize(objective)
+
     Args:
         min_resource:
             A parameter for specifying the minimum resource allocated to a trial noted as :math:`r`
-            in the paper.
+            in the paper. Basically, a smaller :math:`r` will give a result faster, but a larger
+            :math:`r` will give a better guarantee of successful judging between configurations.
             See the details for :class:`~optuna.pruners.SuccessiveHalvingPruner`.
         reduction_factor:
             A parameter for specifying reduction factor of promotable trials noted as
-            :math:`\\eta` in the paper. See the details for
-            :class:`~optuna.pruners.SuccessiveHalvingPruner`.
+            :math:`\\eta` in the paper. Basically, the paper says that results are
+            not very sensitive to the choice of :math:`\\eta`.
+            See the details for :class:`~optuna.pruners.SuccessiveHalvingPruner`.
         n_brackets:
             The number of :class:`~optuna.pruners.SuccessiveHalvingPruner`\\ s (brackets).
             Defaults to :math`4`. See
             https://github.com/optuna/optuna/pull/809#discussion_r361363897.
         min_early_stopping_rate_low:
             A parameter for specifying the minimum early-stopping rate.
-            This parameter is related to a parameter that is referred to as :math:`r` and used in
+            This parameter is related to a parameter that is referred to as :math:`s` and used in
             `Asynchronous SuccessiveHalving paper <http://arxiv.org/abs/1810.05934>`_.
             The minimum early stopping rate for :math:`i` th bracket is :math:`i + s`.
     """


Code review comments:
diff_hunk: @@ -49,22 +49,40 @@ class HyperbandPruner(BasePruner):
         Thus, for example, if ``HyperbandPruner`` has :math:`4` pruners in it,
         at least :math:`4 \\times 10` pruners are consumed for startup.
 
+    Example:
+
+        We minimize an objective function with Hyperband pruning algorithm.
+
+        .. testcode::
+
+            from optuna import create_study
+            from optuna.pruners import HyperbandPruner
+
+            def objective(trial):
+                x = trial.suggest_uniform('x', -1, 1)
+                return x ** 2
path: optuna/pruners/hyperband.py
text: @user1:
The pruner is never activated because this objective function does not have `trial.report` or `trial.should_prune`. How about using the same objective function as the other pruners (e.g., https://github.com/optuna/optuna/blob/v1.2.0/optuna/pruners/median.py#L14-L44).

diff_hunk: @@ -49,22 +49,40 @@ class HyperbandPruner(BasePruner):
         Thus, for example, if ``HyperbandPruner`` has :math:`4` pruners in it,
         at least :math:`4 \\times 10` pruners are consumed for startup.
 
+    Example:
+
+        We minimize an objective function with Hyperband pruning algorithm.
+
+        .. testcode::
+
+            from optuna import create_study
+            from optuna.pruners import HyperbandPruner
+
+            def objective(trial):
+                x = trial.suggest_uniform('x', -1, 1)
+                return x ** 2
+
+            study = create_study(pruner=HyperbandPruner())
+            study.optimize(objective)
path: optuna/pruners/hyperband.py
text: @user1:
Please add `n_trials` (or `timeout`) to stop optimization.
```suggestion
            study.optimize(objective, n_trials=20)
```