diff --git a/lang/zh/gklearn/gedlib/lib/libsvm.3.22/python/README b/lang/zh/gklearn/gedlib/lib/libsvm.3.22/python/README new file mode 100644 index 0000000..cfa6420 --- /dev/null +++ b/lang/zh/gklearn/gedlib/lib/libsvm.3.22/python/README @@ -0,0 +1,367 @@ +---------------------------------- +--- Python interface of LIBSVM --- +---------------------------------- + +Table of Contents +================= + +- Introduction +- Installation +- Quick Start +- Design Description +- Data Structures +- Utility Functions +- Additional Information + +Introduction +============ + +Python (http://www.python.org/) is a programming language suitable for rapid +development. This tool provides a simple Python interface to LIBSVM, a library +for support vector machines (http://www.csie.ntu.edu.tw/~cjlin/libsvm). The +interface is very easy to use as the usage is the same as that of LIBSVM. The +interface is developed with the built-in Python library "ctypes." + +Installation +============ + +On Unix systems, type + +> make + +The interface needs only LIBSVM shared library, which is generated by +the above command. We assume that the shared library is on the LIBSVM +main directory or in the system path. + +For windows, the shared library libsvm.dll for 32-bit python is ready +in the directory `..\windows'. You can also copy it to the system +directory (e.g., `C:\WINDOWS\system32\' for Windows XP). To regenerate +the shared library, please follow the instruction of building windows +binaries in LIBSVM README. + +Quick Start +=========== + +There are two levels of usage. The high-level one uses utility functions +in svmutil.py and the usage is the same as the LIBSVM MATLAB interface. + +>>> from svmutil import * +# Read data in LIBSVM format +>>> y, x = svm_read_problem('../heart_scale') +>>> m = svm_train(y[:200], x[:200], '-c 4') +>>> p_label, p_acc, p_val = svm_predict(y[200:], x[200:], m) + +# Construct problem in python format +# Dense data +>>> y, x = [1,-1], [[1,0,1], [-1,0,-1]] +# Sparse data +>>> y, x = [1,-1], [{1:1, 3:1}, {1:-1,3:-1}] +>>> prob = svm_problem(y, x) +>>> param = svm_parameter('-t 0 -c 4 -b 1') +>>> m = svm_train(prob, param) + +# Precomputed kernel data (-t 4) +# Dense data +>>> y, x = [1,-1], [[1, 2, -2], [2, -2, 2]] +# Sparse data +>>> y, x = [1,-1], [{0:1, 1:2, 2:-2}, {0:2, 1:-2, 2:2}] +# isKernel=True must be set for precomputed kernel +>>> prob = svm_problem(y, x, isKernel=True) +>>> param = svm_parameter('-t 4 -c 4 -b 1') +>>> m = svm_train(prob, param) +# For the format of precomputed kernel, please read LIBSVM README. + + +# Other utility functions +>>> svm_save_model('heart_scale.model', m) +>>> m = svm_load_model('heart_scale.model') +>>> p_label, p_acc, p_val = svm_predict(y, x, m, '-b 1') +>>> ACC, MSE, SCC = evaluations(y, p_label) + +# Getting online help +>>> help(svm_train) + +The low-level use directly calls C interfaces imported by svm.py. Note that +all arguments and return values are in ctypes format. You need to handle them +carefully. + +>>> from svm import * +>>> prob = svm_problem([1,-1], [{1:1, 3:1}, {1:-1,3:-1}]) +>>> param = svm_parameter('-c 4') +>>> m = libsvm.svm_train(prob, param) # m is a ctype pointer to an svm_model +# Convert a Python-format instance to svm_nodearray, a ctypes structure +>>> x0, max_idx = gen_svm_nodearray({1:1, 3:1}) +>>> label = libsvm.svm_predict(m, x0) + +Design Description +================== + +There are two files svm.py and svmutil.py, which respectively correspond to +low-level and high-level use of the interface. + +In svm.py, we adopt the Python built-in library "ctypes," so that +Python can directly access C structures and interface functions defined +in svm.h. + +While advanced users can use structures/functions in svm.py, to +avoid handling ctypes structures, in svmutil.py we provide some easy-to-use +functions. The usage is similar to LIBSVM MATLAB interface. + +Data Structures +=============== + +Four data structures derived from svm.h are svm_node, svm_problem, svm_parameter, +and svm_model. They all contain fields with the same names in svm.h. Access +these fields carefully because you directly use a C structure instead of a +Python object. For svm_model, accessing the field directly is not recommanded. +Programmers should use the interface functions or methods of svm_model class +in Python to get the values. The following description introduces additional +fields and methods. + +Before using the data structures, execute the following command to load the +LIBSVM shared library: + + >>> from svm import * + +- class svm_node: + + Construct an svm_node. + + >>> node = svm_node(idx, val) + + idx: an integer indicates the feature index. + + val: a float indicates the feature value. + + Show the index and the value of a node. + + >>> print(node) + +- Function: gen_svm_nodearray(xi [,feature_max=None [,isKernel=False]]) + + Generate a feature vector from a Python list/tuple or a dictionary: + + >>> xi, max_idx = gen_svm_nodearray({1:1, 3:1, 5:-2}) + + xi: the returned svm_nodearray (a ctypes structure) + + max_idx: the maximal feature index of xi + + feature_max: if feature_max is assigned, features with indices larger than + feature_max are removed. + + isKernel: if isKernel == True, the list index starts from 0 for precomputed + kernel. Otherwise, the list index starts from 1. The default + value is False. + +- class svm_problem: + + Construct an svm_problem instance + + >>> prob = svm_problem(y, x) + + y: a Python list/tuple of l labels (type must be int/double). + + x: a Python list/tuple of l data instances. Each element of x must be + an instance of list/tuple/dictionary type. + + Note that if your x contains sparse data (i.e., dictionary), the internal + ctypes data format is still sparse. + + For pre-computed kernel, the isKernel flag should be set to True: + + >>> prob = svm_problem(y, x, isKernel=True) + + Please read LIBSVM README for more details of pre-computed kernel. + +- class svm_parameter: + + Construct an svm_parameter instance + + >>> param = svm_parameter('training_options') + + If 'training_options' is empty, LIBSVM default values are applied. + + Set param to LIBSVM default values. + + >>> param.set_to_default_values() + + Parse a string of options. + + >>> param.parse_options('training_options') + + Show values of parameters. + + >>> print(param) + +- class svm_model: + + There are two ways to obtain an instance of svm_model: + + >>> model = svm_train(y, x) + >>> model = svm_load_model('model_file_name') + + Note that the returned structure of interface functions + libsvm.svm_train and libsvm.svm_load_model is a ctypes pointer of + svm_model, which is different from the svm_model object returned + by svm_train and svm_load_model in svmutil.py. We provide a + function toPyModel for the conversion: + + >>> model_ptr = libsvm.svm_train(prob, param) + >>> model = toPyModel(model_ptr) + + If you obtain a model in a way other than the above approaches, + handle it carefully to avoid memory leak or segmentation fault. + + Some interface functions to access LIBSVM models are wrapped as + members of the class svm_model: + + >>> svm_type = model.get_svm_type() + >>> nr_class = model.get_nr_class() + >>> svr_probability = model.get_svr_probability() + >>> class_labels = model.get_labels() + >>> sv_indices = model.get_sv_indices() + >>> nr_sv = model.get_nr_sv() + >>> is_prob_model = model.is_probability_model() + >>> support_vector_coefficients = model.get_sv_coef() + >>> support_vectors = model.get_SV() + +Utility Functions +================= + +To use utility functions, type + + >>> from svmutil import * + +The above command loads + svm_train() : train an SVM model + svm_predict() : predict testing data + svm_read_problem() : read the data from a LIBSVM-format file. + svm_load_model() : load a LIBSVM model. + svm_save_model() : save model to a file. + evaluations() : evaluate prediction results. + +- Function: svm_train + + There are three ways to call svm_train() + + >>> model = svm_train(y, x [, 'training_options']) + >>> model = svm_train(prob [, 'training_options']) + >>> model = svm_train(prob, param) + + y: a list/tuple of l training labels (type must be int/double). + + x: a list/tuple of l training instances. The feature vector of + each training instance is an instance of list/tuple or dictionary. + + training_options: a string in the same form as that for LIBSVM command + mode. + + prob: an svm_problem instance generated by calling + svm_problem(y, x). + For pre-computed kernel, you should use + svm_problem(y, x, isKernel=True) + + param: an svm_parameter instance generated by calling + svm_parameter('training_options') + + model: the returned svm_model instance. See svm.h for details of this + structure. If '-v' is specified, cross validation is + conducted and the returned model is just a scalar: cross-validation + accuracy for classification and mean-squared error for regression. + + To train the same data many times with different + parameters, the second and the third ways should be faster.. + + Examples: + + >>> y, x = svm_read_problem('../heart_scale') + >>> prob = svm_problem(y, x) + >>> param = svm_parameter('-s 3 -c 5 -h 0') + >>> m = svm_train(y, x, '-c 5') + >>> m = svm_train(prob, '-t 2 -c 5') + >>> m = svm_train(prob, param) + >>> CV_ACC = svm_train(y, x, '-v 3') + +- Function: svm_predict + + To predict testing data with a model, use + + >>> p_labs, p_acc, p_vals = svm_predict(y, x, model [,'predicting_options']) + + y: a list/tuple of l true labels (type must be int/double). It is used + for calculating the accuracy. Use [0]*len(x) if true labels are + unavailable. + + x: a list/tuple of l predicting instances. The feature vector of + each predicting instance is an instance of list/tuple or dictionary. + + predicting_options: a string of predicting options in the same format as + that of LIBSVM. + + model: an svm_model instance. + + p_labels: a list of predicted labels + + p_acc: a tuple including accuracy (for classification), mean + squared error, and squared correlation coefficient (for + regression). + + p_vals: a list of decision values or probability estimates (if '-b 1' + is specified). If k is the number of classes in training data, + for decision values, each element includes results of predicting + k(k-1)/2 binary-class SVMs. For classification, k = 1 is a + special case. Decision value [+1] is returned for each testing + instance, instead of an empty list. + For probabilities, each element contains k values indicating + the probability that the testing instance is in each class. + Note that the order of classes is the same as the 'model.label' + field in the model structure. + + Example: + + >>> m = svm_train(y, x, '-c 5') + >>> p_labels, p_acc, p_vals = svm_predict(y, x, m) + +- Functions: svm_read_problem/svm_load_model/svm_save_model + + See the usage by examples: + + >>> y, x = svm_read_problem('data.txt') + >>> m = svm_load_model('model_file') + >>> svm_save_model('model_file', m) + +- Function: evaluations + + Calculate some evaluations using the true values (ty) and predicted + values (pv): + + >>> (ACC, MSE, SCC) = evaluations(ty, pv) + + ty: a list of true values. + + pv: a list of predict values. + + ACC: accuracy. + + MSE: mean squared error. + + SCC: squared correlation coefficient. + + +Additional Information +====================== + +This interface was written by Hsiang-Fu Yu from Department of Computer +Science, National Taiwan University. If you find this tool useful, please +cite LIBSVM as follows + +Chih-Chung Chang and Chih-Jen Lin, LIBSVM : a library for support +vector machines. ACM Transactions on Intelligent Systems and +Technology, 2:27:1--27:27, 2011. Software available at +http://www.csie.ntu.edu.tw/~cjlin/libsvm + +For any question, please contact Chih-Jen Lin , +or check the FAQ page: + +http://www.csie.ntu.edu.tw/~cjlin/libsvm/faq.html