update doc/example

Author: reiase

.gitignore

@@ -127,3 +127,8 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+examples/data/
+examples/mnist/mlruns/
+examples/sparse_lr/mlruns/
+.vscode/
+.DS_Store

docs/index.md

@@ -16,10 +16,10 @@ or becomes powerful with `params()`:
 
 ```python
 params().a.b.c.getOrElse(3) # 3 (default value)
-params().a.b.c(3) # 3 (shortcut for default value)
+params().a.b.c(3)           # 3 (shortcut for default value)
 
-params().a.b.c = 4 # set value to param `a.b.c`
-params().a.b.c(3) # 4 (default value is ignored) 
+params().a.b.c = 4          # set value to param `a.b.c`
+params().a.b.c(3)           # 4 (default value is ignored) 
 ```
 
 ## Scoped Parameter
@@ -35,8 +35,8 @@ or becomes powerful with `nested scope`:
 ``` python
 with param_scope(a=1) as hp: 
     with param_scope(a=2) as hp: 
-        hp.a == 2 # True
-    hp.a == 1 # True
+        hp.a == 2 # True, a=2 for inner scope
+    hp.a == 1     # True, a=1 for outer scope
 ```
 
 even more powerful when using `param_scope` in function:
@@ -59,3 +59,17 @@ foo() # 1
 with param_scope(param1=2): 
     foo() # 2
 ```
+
+## Predefined Parameter
+```python
+@auto_param #convert keyword arguments into hyper parameters
+def model_train(X, y, learning_rate = 1.0, penalty = 'l1'):
+    LR = LogisticRegression(C=1.0, 
+        lr=local_param('learning_rate'), 
+        penalty=local_param('penalty'))
+    LR.fit(X, y)
+
+# specify predefined parameter using `param_scope`
+with param_scope('model_train.learning_rate=0.01'):
+    model_train(X, y)
+```

examples/sparse_lr/example_mlflow.py

@@ -0,0 +1,38 @@
+from hyperparameter import param_scope, set_tracker, Tracker
+from model import sparse_lr_plot
+
+from sklearn import datasets
+from sklearn.preprocessing import StandardScaler
+
+import mlflow
+
+
+def mlflow_tracker(params):
+    for k, v in params.items():
+        mlflow.log_param(k, v)
+
+
+set_tracker(mlflow_tracker)
+
+X, y = datasets.load_digits(return_X_y=True)
+X = StandardScaler().fit_transform(X)
+
+# classify small against large digits
+y = (y > 4).astype(int)
+
+
+def run(args):
+    # run the lr model with parameter from cmdline
+    with param_scope(*args.define):  # set parameters according to cmd line
+        sparse_lr_plot(X, y)
+
+
+if __name__ == '__main__':
+    import argparse
+    parser = argparse.ArgumentParser('example')
+    parser.add_argument('-D', '--define', nargs='*', default=[], action="extend",
+        help='define a parameter `param_name=param_value`, supported parameter list: \n' + '\n  '.join(Tracker.all()))
+    args = parser.parse_args()
+    run(args)
+
+    print(Tracker.report())