small doc fixes

README.md

@@ -7,9 +7,8 @@
 A package for controlling iterative algorithms.
 
 Not registered and still experimental.
-But well tested, with complete doc-strings.
 
-To do: Add data interface point.
+To do: Add interface point for online learning
 
 
 ## Installation
@@ -69,6 +68,12 @@ julia> IterationControl.train!(model, Train(2), NumberLimit(3), Info(m->m.root))
 [ Info: Early stop triggered by NumberLimit(3) stopping criterion.
 ```
 
+Here each control is repeatedly applied until one of them triggers a
+stop. The first control `Train(2)` says "train the model two more
+iterations"; the second says "stop after 3 repetitions" (of the
+sequence of control applications); and the third, "log the value of
+the root to `Info`".
+
 If `model` admits a method returning a loss (for example, the
 difference between `x` and the square of `root`), then we can lift
 that method to `IterationControl.loss` to enable control using
@@ -87,9 +92,9 @@ IterationControl.loss(model::SquareRooter) = loss(model) # lifting
 losses = Float64[]
 callback(model) = push!(losses, loss(model))
 
-julia> IterationControl.train!(model, 
-                               Train(1), 
-                               Threshold(0.0001), 
+julia> IterationControl.train!(model,
+                               Train(1),
+                               Threshold(0.0001),
                                Callback(callback));
 [ Info: Early stop triggered by Threshold(0.0001) stopping criterion.
 
@@ -114,6 +119,17 @@ above.
  "Early Stopping - But When?", in *Neural Networks: Tricks of the
  Trade*, ed. G. Orr, Springer.
 
+The interface just described is sufficient for controlling
+conventional machine learning models with an iteration parameter, as
+this [tree boosting example](/examples/iris/) shows. An extension of
+the interface to handle online learning is planned.
+
+
+## Verbose logging
+
+The `IterationControl.train!` method can be given the keyword argument
+`verbosity=...`, defaulting to `1`. The larger `verbosity`, the noisier.
+
 
 ## Controls provided
 
@@ -151,15 +167,9 @@ wrapper                                            | description
 > Table 2. Wrapped controls
 
 
-## Verbose logging
-
-The `IterationControl.train!` method can be given the keyword argument
-`verbosity=...`, defaulting to `1`. The larger `verbosity`, the noisier.
-
-
 ## Access to model through a wrapper
 
-Note that predicates ordinarily applied to `model` by some control
+Note that functions ordinarily applied to `model` by some control
 (e.g., a `Callback`) will instead be applied to
 `IterationControl.expose(model)` if `IterationControl.expose` is
 appropriately overloaded.
@@ -183,7 +193,7 @@ Here's how `IterationControl.train!` calls these methods:
 ```julia
 function train!(model, controls...; verbosity::Int=1)
 
-    control = CompositeControl(controls...)
+    control = composite(controls...)
 
     # before training:
     verbosity > 1 && @info "Using these controls: $(flat(control)). "

examples/iris/iris.ipynb

@@ -124,7 +124,7 @@
   {
    "cell_type": "markdown",
    "source": [
-    "Binding data and hyper"
+    "Creating a machine:"
    ],
    "metadata": {}
   },
@@ -209,7 +209,7 @@
     {
      "output_type": "execute_result",
      "data": {
-      "text/plain": "((Train(5), NamedTuple()), (GL(2.0), (done = true, log = \"Early stop triggered by GL(2.0) stopping criterion. \")), (Info{typeof(Main.##258.logging)}(Main.##258.logging), NamedTuple()))"
+      "text/plain": "((Train(5), NamedTuple()), (GL(2.0), (done = true, log = \"Early stop triggered by GL(2.0) stopping criterion. \")), (Info{typeof(Main.##260.logging)}(Main.##260.logging), NamedTuple()))"
      },
      "metadata": {},
      "execution_count": 7
@@ -267,7 +267,7 @@
     {
      "output_type": "execute_result",
      "data": {
-      "text/plain": "((Train(5), NamedTuple()), (NumberLimit(10), (done = true, log = \"Early stop triggered by NumberLimit(10) stopping criterion. \")), (Info{typeof(Main.##258.logging)}(Main.##258.logging), NamedTuple()))"
+      "text/plain": "((Train(5), NamedTuple()), (NumberLimit(10), (done = true, log = \"Early stop triggered by NumberLimit(10) stopping criterion. \")), (Info{typeof(Main.##260.logging)}(Main.##260.logging), NamedTuple()))"
      },
      "metadata": {},
      "execution_count": 8

examples/iris/iris.md

@@ -61,7 +61,7 @@ hyper-parameters. The objects we will iterate here are MLJ
 these bind the model to train/test data and, in the case of
 iterative models, can be trained using a warm-restart.
 
-Binding data and hyper
+Creating a machine:
 
 ```julia
 mach = MLJ.machine(Booster(nrounds=1), X, y);
@@ -100,7 +100,7 @@ IterationControl.train!(mach,
 ```
 
 ```
-((Train(5), NamedTuple()), (GL(2.0), (done = true, log = "Early stop triggered by GL(2.0) stopping criterion. ")), (Info{typeof(Main.##257.logging)}(Main.##257.logging), NamedTuple()))
+((Train(5), NamedTuple()), (GL(2.0), (done = true, log = "Early stop triggered by GL(2.0) stopping criterion. ")), (Info{typeof(Main.##259.logging)}(Main.##259.logging), NamedTuple()))
 ```
 
 Continuing iteration with a different stopping criterion:
@@ -113,7 +113,7 @@ IterationControl.train!(mach,
 ```
 
 ```
-((Train(5), NamedTuple()), (NumberLimit(10), (done = true, log = "Early stop triggered by NumberLimit(10) stopping criterion. ")), (Info{typeof(Main.##257.logging)}(Main.##257.logging), NamedTuple()))
+((Train(5), NamedTuple()), (NumberLimit(10), (done = true, log = "Early stop triggered by NumberLimit(10) stopping criterion. ")), (Info{typeof(Main.##259.logging)}(Main.##259.logging), NamedTuple()))
 ```
 
 ---