pySnow Documentation

0.5

pySnow is a minimal python interface to the SNoW - Sparse Network of Winnows learning architecture. It is meant to be faithful to the original command line interface and as such doesn't provide any additional features (nor does it attempt to fix any outstanding issues). The rest of the README details how to build and install pySnow and its requirments, and provides a few simple examples. Note, this is a fairly early and untested release so your mileage may vary. Please report any questions or problems to nnshah2@uiuc.edu.

Files and Directories

• pySnow.h - Main header declaring types,objects and functions used by pySnow.cpp and pySnowSession.cpp.

• pySnow.cpp - Implementation of train,test,evaulate functions and registers module with python.

• pySnowSession.cpp - Implementation of SnowSession type.

• setup.py - setup script for building and installing using python distutils.

• examples/ - examples showing basic usage.

• examples/orangeSnow/ - a SNoW learner and classifier integrated into the orange framework. More details on orange can be found at: http://www.ailab.si/orange .

• README_html/ - this web page.

• Doxyfile - doxygen configuration file for creating README_html

• README.doxyen - doxygen source for creating README_html

Requirements

To build pySnow you'll need to download and compile SNoW Version 3.2.0 from http://l2r.cs.uiuc.edu/~cogcomp/asoftware.php?skey=SNOW . As pySnow depends on the classes provided in 3.2, it is not compatible with SNoW Version 3.1.8.

Building pySnow

• Build SNoW

See SNoW documentation.

Note: if for whatever reason you modify or rebuild the SNoW library, you will need to rebuild pySnow by first removing the build directory and then running "python setup.py build" again.

• Edit "setup.py"

Modify the variables:

PATHTOSNOWLIB     = "//home/nshah/ids/sandbox/active_ids/lib/Snow_v3.2"
PATHTOSNOWHEADERS = PATHTOSNOWLIB

to point to your installation of Snow_v3.2

• Build pySnow

You should now be able to run the command:

python setup.py build

This in turn should create the directory "build" and a couple sub-directories "lib.linux-i686-2.4" and "temp.linux-i686-2.4" (the names may be different). If all goes well, there will be a dynamically linked library 'snow.so' within "lib.linux-i686-2.4".

Installing

Either run the command

python setup.py install 

(for which you will most probably need super user priviledges) or simply copy the library "snow.so" to somewhere in your PYTHONPATH.

Fire up your python interpreter and try typing

import snow

Running

The pySnow module provides 3 functions (train,test,evaluate) and 1 type (SnowSession) corresponding to the different modes of the original command line SNoW.

Functions

• train (args)

Equivalent to running SNoW in training mode. Command line arguments are passed in as a dictionary of key,value pairs. In addition to the supported output modes of SNoW the command can also redirect output to a string that is returned as the result of the command. This is the default.

Example:

	original snow command:

	## ../snow -train -I $train_file -F $net_file -A $arch_file

	becomes:

	import snow

	args = {'I':train_file,
		'F':net_file,
		'A':arch_file}

	result = snow.train(args)

	

• test (args)

Equivalent to running SNoW in testing mode. Command line arguments are passed in as a dictionary of key,value pairs. In addition to the supported output modes of SNoW the command can also redirect output to a string that is returned as the result of the command. This is the default.

	Example:

	original snow command:

	## ../snow -test -I $test_file -F $net_file 


	becomes:

	import snow

	args = {'I':test_file,
		'F':net_file}

	result = snow.test(args)

	

• evaluate (args)

Equivalent to running SNoW in evaluate mode. Command line arguments are passed in as a dictionary of key,value pairs. In addition to the supported output modes of SNoW the command can also redirect output to a string that is returned as the result of the command. This is the default.

	Example:

	TBD
	

SnowSession

In addition to the basic "one-shot" modes described above pySnow also provides an interface to SNoW's "interactive" and "server" modes through the SnowSession type. The SnowSession constructor takes two arguments, the runMode and the command line arguments (as above). SnowSession provides two methods "update" (for interactive mode) and "evaluateExample" (for server mode).

Interactive Mode

To use SNoW's interactive mode, instantiate SnowSession type as follows:

	args = {'I':test_file,
       		'F':net_file}
	
	session = snow.SnowSession(snow.MODE_INTERACTIVE,args)

To update the network or evaluate an example use the "update" method:

	testdata = open(test_file,"r")

	for ex in testdata:
    		result=session.update('e,'+ex)
    		print result

Server Mode

To use SNoW's server mode, instantiate SnowSession type as follows:

	args = {'I':test_file,
       		'F':net_file}
	
	session = snow.SnowSession(snow.MODE_SERVER,args)

To evaluate and example use the "evaluateExample" method:

	testdata = open(test_file,"r")

	for ex in testdata:
    		result=session.evaluateExample(ex)
    		print result

Note while this mode has the semantics of the traditional server mode, there is no socket communication and no additional thread.

Output Types

One final note about output types. When an output file is not specified SNoW traditionally directs output to the console. In pySnow the default is instead to direct output to a string. Each method (train,test,evaluate,update,evaluateExample) takes an optional argument that can be set to either OUTPUT_STRING, or OUTPUT_CONSOLE.

Author:

Neelay Shah

---