1. About
--------

peewit a agnostic experimentation framework that wants to facilitate  the employment of 
straight-lined machine learning experiments.

For documentation we currently can only refer to a report that describes the model and the 
serivces in general terms (linked on the homepage of peewit 
[http://www.ke.tu-darmstadt.de/resources/peewit]) and to the comments in the examples that
are shipped with this distribution.


2. Contents of the Distribution
-------------------------------

This distribution of peewit comes with six directories:

python/
All files that belong to the the peewit framework are included in this directory. 

stuff/ 
Mixed files. From stuff/peewit_first_run.sh you can see how to it run.
As replacement for user-documentation we have to refer to the modules exmample_X.py in 
example_project/. They contain comments that roughly explain what happens. 

example_project/ 
is an example on how one would use peewit. The top level experimentation code is given
 in the module of the package project_package. 

example_user_packages/ 
contains packages that are used by in example_project/. It represent the packages a
peewit user employs for running experiments. Those packages are not part of peewit 
but their are shipped with peewit to illustrate the usage of peewit. 

example_data_sets/ 
contains data sets which the example project works on.

unittests/
Some simple tests that might also be instructive for users to learn about peewits features. 



3. Make it Run
--------------

In order to make the examples run apply the following instructions:


-- install python 3.x along with the packages numpy, matplotlib >=1.2, graphviz and libsvm

-- load the current peewit from project homepage, unpack it 

-- add peewit to python search path (see peewit/stuff/python_with_peewit_paths)

-- go to example_project/project_package/

-- set paths in project_conf.py 

-- run example_X.py  

For a quick start you may chose example_0 that does not need matplotlib nor libsvm.

If you want to try the parallelization services, you further need unison for synchronization 
purpose (look for package 'unison' or go to [http://www.cis.upenn.edu/~bcpierce/unison/]).  

If you want to use archiving services you also need to install git, a distributed version 
control system.

Peewit is written to be platform independent. By now, we do not know whether it really is 
because we dont test it. Note that, in any case, peewit wants the paths in the configuration 
module (project_conf.py) to be given in posix notation. 

You can also run, or at least look at, doc/peewit_first_run.sh. The script 
uses the a base-dir-overwrite functionality. If the file project-dir/.peewit/base_dir contains 
a dir-path, this path overwrite the base-dir setting made in project_conf.py.



4. Licenses
-----------

The odict module in peewit/pw_toolbox is written by Nicola Larosa and Michael Foord and published 
under BSD licence as it can found at [http://www.voidspace.org.uk/python/license.shtml].
The package mlpy in example_user_packages/ is part of mlpy and owned by the mlpy Developers, 
see [http://mlpy.sourceforge.net/].

The remaining modules in the directories given above are published by the peewit developers 
under GNU General Public License version 3 (GPLv3). The terms and conditions of this license 
are given in doc/licence.txt or at [http://www.opensource.org/licenses/gpl-3.0.html]. 



5. Contact 
----------

Peewit is developed and maintained by Lorenz Weizsäcker. For comments and questions feel free send  
a mail to [lorenz@ke.tu-darmstadt.de]. There are many different interesting directions of further 
development.

