refine

Author: LittleLittleCloud

machine-learning/Parameter and SearchSpace.ipynb

@@ -10,20 +10,21 @@
    "source": [
     "In AutoML.Net, `SearchSpace` defines the hyper-parameter searching range of a sweepable pipeline or a sweepable estimator and `Parameter` is the sampled result from a `SearchSpace`, which can be used to restore an estimator or a pipeline.\n",
     "\n",
-    "`SearchSpace` has a great impact on automl performance. In theory, it decides the upper-bound of an automl model. A larger `SearchSpace` usually means an increasing potential of finding a better model. In practice though, there's also a trade-off and a larger `SearchSpace` doesn't always mean better considering the searching complexity and increasing training cost.\n",
+    "`SearchSpace` has a great impact on automl performance. In theory, it decides the upper-bound of an automl model. A larger `SearchSpace` usually means an increasing potential of finding a better model. In practice though, there's also a trade-off and a larger `SearchSpace` doesn't always to be better considering the increasing searching complexity and higher training cost.\n",
     "\n",
-    "AutoML.Net provides a default `SearchSpace` for almost all available ML.Net trainers. However, it also allows you to provide your own search space if the default one doesn't meet your request.\n",
+    "AutoML.Net provides default `SearchSpace` for almost all available ML.Net trainers, which is well-tuned on hundreds of dataset and should be good enough in 99% situation.  However, you can also provide your own search space if the default one doesn't meet your request.\n",
     "\n",
-    "In this notebook, we will go through a series of topics on search space\n",
+    "In this notebook, we will go through the following topics on search space\n",
     "- default search space for mlnet trainers.\n",
-    "- how to customize search space"
+    "- how to customize search space\n",
+    "- how to sample from search space"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Install nuget dependency"
+    "# Install nuget dependency and import using statement"
    ]
   },
   {
@@ -256,7 +257,8 @@
     "using Microsoft.ML.AutoML.CodeGen;\n",
     "var lgbmSearchSpace = new SearchSpace<LgbmOption>();\n",
     "\n",
-    "// refine search space if necessary\n",
+    "// the default option for NumberOfLeaves is (4, 32768, logBase: true)\n",
+    "// this might be too large but you can refine it if necessary\n",
     "lgbmSearchSpace[\"NumberOfLeaves\"] = new UniformIntOption(4, 1024, true, 4);\n",
     "\n",
     "// pass lgbmSearchSpace in AutoTrainer\n",
@@ -409,7 +411,7 @@
    "metadata": {},
    "source": [
     "# create `SearchSpace<T>` which casts sampled parameter to a concrete type.\n",
-    "AutoML allows you to use attribution on property to avoid creating search space from scratch. The following code shows how to create an identical search space from above except using attribution API\n",
+    "AutoML allows you to define `SearchSpace` with class type, in which case it checks class property and build up search space using those properties with option attributions. The following code shows how to create an identical search space from above using except with a class type.\n",
     "\n",
     "`SearchSpace<T>`, comparing with `SearchSpace`, will also cast sampled parameter to a concrete type `T` instead of `Parameter`, which saves the effort of getting specific hyper-parameter value from `Parameter`."
    ]
@@ -553,9 +555,9 @@
    "metadata": {},
    "source": [
     "# Sampling `Parameter` from `SearchSpace`\n",
-    "In AutoML.Net, `SearchSpace` is associated with an `n`-dimension vector which is called `feature space`. And tuner, instead of performing sampling on original options in a `SearchSpace`, sampling from that `feature space` instead. And `SearchSpace` will then mapping the sampling result back to its options.\n",
+    "In AutoML.Net, `SearchSpace` is associated with an `n`-dimension vector which is called `feature space`. And tuner, instead of performing sampling on original options in a `SearchSpace`, sampling from that `feature space` instead. The sampling result will then mapping back to options.\n",
     "\n",
-    "The following code shows the sampling process above, which creates an `n`-d random vector and use that vector to sample from search space. Notice that because the type of created search space is `SearchSpace`, the result sampled from `n`-d vector is `Parameter` rather than a concrete type."
+    "The following code shows the sampling process above. It creates an `n`-d random vector and uses that vector to sample from search space."
    ]
   },
   {
@@ -593,7 +595,7 @@
     "    var featureVector = Enumerable.Range(0, dim).Select(x => rnd.NextDouble()).ToArray();\n",
     "    var parameter = searchSpace.SampleFromFeatureSpace(featureVector);\n",
     "\n",
-    "    // use Parameter.AsType to map parameter to a concrete type.\n",
+    "    // use Parameter.AsType<T> to map parameter to a concrete type.\n",
     "    var myParameter = parameter.AsType<MyParameter>();\n",
     "    var json = JsonConvert.SerializeObject(myParameter);\n",
     "\n",