Update new grid.py and README.

Author: guestwalk

tools/README

@@ -60,9 +60,28 @@ gnuplot does not support png, so you need to change "set term png
 transparent small" and use other image formats. For example, you may
 have "set term pbm small color".
 
-Usage: grid.py [-log2c begin,end,step] [-log2g begin,end,step] [-v fold]
-       [-svmtrain pathname] [-gnuplot pathname] [-out pathname] [-png pathname]
-       [additional parameters for svm-train] dataset
+Usage: grid.py [grid_options] [svm_options] dataset
+
+grid_options :
+-log2c {begin,end,step | "null"} : set the range of c (default -5,15,2)
+    begin,end,step -- c_range = 2^{begin,...,begin+k*step,...,end}
+    "null"         -- do not grid with c
+-log2g {begin,end,step | "null"} : set the range of g (default 3,-15,-2)
+    begin,end,step -- g_range = 2^{begin,...,begin+k*step,...,end}
+    "null"         -- do not grid with g
+-v n : n-fold cross validation (default 5)
+-svmtrain pathname : set svm executable path and name
+-gnuplot {pathname | "null"} :
+    pathname -- set gnuplot executable path and name
+    "null"   -- do not plot 
+-out {pathname | "null"} : (default dataset.out)
+    pathname -- set output file path and name
+    "null"   -- do not output file
+-png pathname : set graphic output file path and name (default dataset.png)
+-resume [pathname] : resume the grid task using an existing output file (default pathname is dataset.out)
+    Use this option only if some parameters have been checked for the SAME data.
+
+svm_options : additional options for svm-train
 
 The program conducts v-fold cross validation using parameter C (and gamma)
 = 2^begin, 2^(begin+step), ..., 2^end.
@@ -74,6 +93,17 @@ For windows users, please use pgnuplot.exe. If you are using gnuplot
 3.7.1, please upgrade to version 3.7.3 or higher. The version 3.7.1
 has a bug. If you use cygwin on windows, please use gunplot-x11.
 
+If the task is terminated accidentally or you would like to change the
+range of parameters, you can apply '-resume' to save time by re-using
+previous results.  You may specify the output file of a previous run
+or use the default (i.e., dataset.out) without giving a name. Please
+note that the same condition must be used in two runs. For example,
+you cannot use '-v 10' earlier and resume the task with '-v 5'.
+
+The value of some options can be "null." For example, `-log2c -1,0,1
+-log2 "null"' means that C=2^-1,2^0,2^1 and g=LIBSVM's default gamma
+value. That is, you do not conduct parameter selection on gamma.
+
 Example
 =======
 
@@ -89,6 +119,10 @@ Output: two files
 dataset.png: the CV accuracy contour plot generated by gnuplot
 dataset.out: the CV accuracy at each (log2(C),log2(gamma))
 
+The following example saves running time by loading the output file of a previous run.
+
+> python grid.py -log2c -7,7,1 -log2g -5,2,1 -v 5 -resume heart_scale.out heart_scale
+
 Parallel grid search
 ====================
 
@@ -123,6 +157,33 @@ If -log2c, -log2g, or -v is not specified, default values are used.
 If your system uses telnet instead of ssh, you list the computer names
 in telnet_workers.
 
+Calling grid in Python
+======================
+
+In addition to using grid.py as a command-line tool, you can use it as a
+Python module. 
+
+>>> rate, param = find_parameters(dataset, options)
+
+You need to specify `dataset' and `options' (default ''). See the following example.
+
+> python
+
+>>> from grid import *
+>>> rate, param = find_parameters('../heart_scale', '-log2c -1,1,1 -log2g -1,1,1')
+[local] 0.0 0.0 rate=74.8148 (best c=1.0, g=1.0, rate=74.8148)
+[local] 0.0 -1.0 rate=77.037 (best c=1.0, g=0.5, rate=77.037)
+.
+.
+[local] -1.0 -1.0 rate=78.8889 (best c=0.5, g=0.5, rate=78.8889)
+.
+.
+>>> rate
+78.8889
+>>> param
+{'c': 0.5, 'g': 0.5}
+
+
 Part III: LIBSVM format checking tools
 
 Introduction