***************************************
***************************************
****							   ****
****   INSTRUKCJA DLA WSDDE 0.64   ****
****							   ****
***************************************
***************************************

Word Sense Disambiguation Development Environement (WSDDE)

WSDDE to środowisko ułatwiające tworzenie i ewaluacje metod WSD w paradygmacie uczenia z nadzorem.

**************************
I. INSTALACJA
**************************

Do uruchomienia środowisko wymaga jedynie Java Runtime Environment (JRE) w wersji co najmniej 1.6. W związku z tym, środowisko powinno się uruchamiać na każdym komputerze z zainstalowanym JRE 1.6. Przetestowano na Windows XP, Vista oraz Ubuntu 9.04. Po rozpakowaniu większa część środowiska nadaje się od razu do użycia. 

***************************
II. URUCHOMIENIE
***************************

Po rozpakowaniu struktura katalogów wygląda następująco:

/wsdde.jar
/config.ini
/readme.txt
/wsdde.pdf (arktykuł z konferencji LTC'09)
/wsdde_lib (katalog z bibliotekami używanymi przez WSDDE)
/doc/gpl.txt (licencja)
/source (katalog z podkatalogami z źródłami)
/resources (katalog z zasobami)
	/corpora_raw (mały ręcznie oznakowany korpus i korpusy pseudosłów)
	/corpora_enriched (korpusy wzbogacone dodatkowymi informacjami (POS))
	/experiment_meta_descriptions (przykładowe meta opisy eksperymentu)
	/experiment_descriptions (przykładowe opisy eksperymentu)
	/results (przykładowe wyniki)
	/wsdmethods (przykładowe, metody WSD gotowe do użycia)

Środowisko w wersji 0.64 zaleca się używać głównie z lini poleceń. Wpisanie i uruchomienie:

> java -jar wsdde.jar

spowoduje wyświetlenie dostępnych opcji, które podaje się jako parametr programu, czyli:

> java -jar wsdde.jar [options]

Jeżeli pojawi się błąd braku pamięci, należy ustawić dla VM przełącznik -XmxMEMm, gdzie MEM to ilość pamięci, która ma być dostępna dla środowiska w megabajtach, np:

> java -Xmx1000m -jar wsdde.jar [options]

Wszystkie pliki wejściowe (korpusy, opisy eksperymentów, itd.) powinny być kodowane jako UTF-8.

Jeżeli jako plik wyjściowy podaje się ścieżkę, to podane katalogi muszą istnieć, żeby plik został zapisany.

Dla zapewnienia pełnej funkcjonalności środowisko korzysta z bibliotek i zewnętrznych programów. W katalogu wsdde_lib znajdują się wszystkie zewnętrzne biblioteki wymagane przez środowisko:

commons-cli.jar (1.2) -- obsługa lini poleceń
weka.jar (3.6.1)-- algorytmy selekcji cech i maszynowego uczenia

mysql.jar (5.1.10)-- connector jdbc do bazy danych MYSQL, używany jedynie w przypadku korzystania z bazy danych (MYSQL). Użytkownik powinien zapewnić dostęp do serwera MYSQL (adres, port, nazwa pustej bazy danych, użytkownik, hasło).

poliqarp.jar (1.3.7) -- biblioteka klienta dla serwera poliqarpd. Używana jedynie w przypadku korzystania z komendy tworzącej korpus pseudosłów.

W nawiasach podane są wersje, z którymi środowisko było testowane i działa poprawnie (może mieć znaczenie, gdy ktoś używa jakiejś istotnie różnej wersji serwera). W przypadku mysqla i poliqarpa, do środowiska dołączeni są jedynie klienci tych aplikacji. O tym jak skonfigurowane są odpowiednie serwery, użytkownik informuje program poprzez wybranie odpowiednich opcji w pliki config.ini (wszystkie opcje są opisane). Na serwerach bazy danych trzeba stworzyć pustą bazę danych i użytkownika, który będzie miał do niej dostęp (prawo zapisu i odczytu). Dla Mysqla zaleca się instalacje jakiegoś graficznego narzędzia do przeglądania wyników, np. MYSQL GUI TOOLS. Serwer poliqarpa dostępny jest na stronach sourceforge.net, korpusy języka polskiego obsługiwane przez poliqarpa znajdują się na stronach nkjp.pl lub korpus.pl. Instalacje obu serwerów są dość standardowe i nie powinny nikomu przysporzyć problemów.

Oprócz tego środowisko może korzystać z tagera TAKIPI (http://nlp.ipipan.waw.pl/TaKIPI/). Po zainstalowaniu, należy poinformować środowisko poprzez umieszczenie odpowiedniego wpisu w pliku config.ini.


**********************
STRUKTURA PLIKÓW XML
**********************

Ponieważ część struktury XML (np. opis eksperymentu) zależy od zaimplementowanych generatorów cech, schematy je specyfikujące są tworzone dynamicznie z lini poleceń. Aby zobaczyć aktualny schemat oraz informację o zaimplementowanych generatorach cech, należy wpisać:

> java -jar wsdde.jar -xsd

********************
TWORZENIE WŁASNYCH GENERATORÓW CECH
********************

Należy rozszerzyć abstrakcyjną klasę wsdde.generator.FeatureGenerator. Ponadto klasa powinna znaleźć się w pakiecie wsdde.generator. W pakiecie należy też umieścić fragmenty schematów XML (xsd) opisujących parametry generatora. Dobrym pomysłem jest obejrzenie wbudowanych generatorów cech.

W obecnej wersji systemu korzystanie z dodatkowych źródeł wiedzy (np. wordnet, itd) nie jest wspomagane przez architekturę. Można to oczywiście robić na własną rękę. W przyszłości, gdy środowisko zostanie przystosowane do standardu anotacji NKJP, obsługa dodatkowych źródeł wiedzy będzie w nim wspierana.



******************
SCENARIUSZ UŻYCIA
******************

W tej sekcji opisano przykładowy scenariusz, jak można używać środowiska WSDDE.

SCENARIUSZ 1

1. Stwórz korpus pseudosłów
(sprawdź ustawienia poliqarpa w pliku config.ini, serwer poliqarpa musi być włączony)

> java -jar wsdde.jar -pws -wc parlament=500 dom=500 -o pws.xml

Takie polecenie wygeneruje plik o nazwie pws.xml zawierjący 1000 kontekstów pseudosłowa parlement-dom (~izba).

2. Dodaj do korpusu dodatkowe informacje (dalsze kroki wymagają użycia plików w formacie wygenerowanym w tym kroku). Żeby użyć opcji -takipi, w systemie musi być poprawnie zainstalowane TAKIPI (1.8) oraz w pliku config.ini powinien znajdować się odpowiedni wpis.

> java -jar wsdde.jar -enr -i pws.xml -takipi -o pws.wsdc 

To polecenie wygeneruje z pliku pws.xml plik o nazwie pws.wsdc. Stworzony plik jest w formacie, który jest wymagany w dalszych krokach. Jeżeli nie chcesz lub nie mmożesz używać TAKIPI, do wzbogacenia możesz użyc proste tokenizera i stemmera, użyj wówczas przełącznika -simple.

3. Podziel korpus na korpus treningowy i testowy.

> java -jar wsdde.jar -spl -i pws.wsdc -ss 500 500 -p pws

Z korpusu pws.wsdc zostanie podzielony na dwa korpusy po 500 przykładów (losowo). Przełącznik -p mówi jaki prefiks mają mieć pliki z tymi korpusami.

4. Stwórz meta opis eksperymentu. Żeby poznać składnie (schemat XMLa opisującego opis eksperymentu) wpisz:

> java -jar wsdde.jar -xsd

Stwórz plik xml i uzupełnij go zgodnie z regułami. Możesz go nazwać dowolnie. Załóżmy, że go nazwałeś meta.desc.

5. Stwórz opis eksperymentu z meta opisu. 

> java -jar wsdde.jar -gmd -i metadesc.xml -o desc.xml

Zostanie wygenerowany opis eksperymentu i zapisany w pliku desc.xml.

6. Przeprowadź eksperyment zgodnie z opisem.

> java -Xmx1000m -jar wsdde.jar -coe -i desc.xml -o result.xml -sm -db

Przełącznik -Xmx1000m zapewnia JVM 1000m pamięci. Wyniki eksperymentu zostaną zapisane do pliku result.xml -- do opisu poszczególnych metod z pliku desc.xml dołączone zostaną elementy <results> i <time_elapsed>. Przełącznik -db (pamiętaj o podaniu ustawień bazy danych w pliku config.ini) sprawia, że wyniki zostaną zapisane w bazie danych. Przełącznik -sm sprawia, że zbudowane metody WSD zostaną zapisane na dysku. W przypadku walidacji krzyżowej, model, który będzie zapisany trenowany jest na WSZYSTKICH przykładach (i nie testowany).

7. Podłącz się do bazy danych i zapoznaj się z wynikami. Każdy istotny parametr zapisywany jest w osobnej kolumnie; dzięki grupowaniu i sortowaniu, możesz sprawdzić, które ustawienia są ważne, a które nie, oraz jak przekładają się na skuteczność dezambiguacji.

8. Na podstawie obserwacji wgraj wybraną metodę spośród tych zapisanych w punkcie 6. I użyj ją do oznakowania korpusu. Wpisanie:

> java -jar wsdde.jar -clu -c pws2.wsdc -m 1.wsdmeth -o pws2_tagged.wsdc

wgra model zapisany w pliku 1.wsdmeth, wgra korpus pws2.wsdc, oznakuje go i zapisze jako pws2_tagged.wsdc.


************************************************************************
ENGLISH
************************************************************************

*****************************************
*****************************************
****					  		     ****
****   THE WSDDE 0.64 INSTRUCTION    ****
****							     ****
*****************************************
*****************************************

Word Sense Disambiguation Development Environement (WSDDE)

The current development version of the environment facilitates the construction and evaluation of WSD methods in the supervised Machine Learning (ML) paradigm.



**************************
I. INSTALLATION 
**************************

To install the WSDDE only Java Runtime Environement (at least 1.6) (JRE) is required. Hence, the WSDDE should work on every computer with installed JRE. It was tested on Windows XP, Windows Vista and Ubuntu 9.04. One only needs to unpack the zipped file to use most of the environment.


***************************
II. GETTING STARTED
***************************

The structure of directories after unzipping looks as follows:

/wsdde.jar
/config.ini
/readme.txt
/wsdde.pdf (an article from LTC'09)
/wsdde_lib (external libraries used by the WSDDE)
/doc/gpl.txt (the gpl license)
/source
/resources
	/corpora_raw (a small, hand-annotated corpus and pseudowords corpora)
	/corpora_enriched (corpora enriched with extra information (e.g. POS))
	/experiment_meta_descriptions (some experiment's meta descriptions)
	/experiment_descriptions (some experiment's meta descriptions)
	/results
	/wsdmethods (some WSD methods ready to load and use)


The use of the WSDDE v. 0.64 mainly from the command line is recommended. Command:

> java -jar wsdde.jar

shows available options, which should be passed as the program's parameter(s):

> java -jar wsdde.jar [options]

In case of a no-memory error, one should use the -XmxMEMm (MEM = memory in megabytes) switch for JVM, e.g.

> java -Xmx1000m -jar wsdde.jar [options]

All input files (corpora, experiments' descriptions, etc.) should be UTF-8 encoded.

If you give the output path, all the given directories must exist.

To achieve the full functionality, the WSDDE uses external libraries. All the necessary  libraries are in wsdde_lib directory:


commons-cli.jar (1.2) -- command line
weka.jar (3.6.1)-- algorithms of selection and machine learning

mysql.jar (5.1.10)-- jdbc connector to the MYSQL; it is required only if you use the MYSQL. The WSDDE user should have access to the MYSQL server and provide (config.ini) server address, port, DB name, DB user and password.

poliqarp.jar (1.3.7) -- client library for poliqarpd. It is used only if you want to generate pseudowords corpora.

The numbers in brackets are the versions which are currently used and work properly. In the case of MySQL and Poliqarp only the client-part is bundled with the WSDDE. One should give the servers' settings in config.ini file. The newest version of poliqarp is accessible at sourceforge.net. Corpora which are used by poliqarp server are at nkjp.pl or korpus.pl. 

The environment can also use the TAKIPI tagger (http://nlp.ipipan.waw.pl/TaKIPI/). If you want to use it, you should install TAKIPI and edit config.ini (you should put the path to TaKIPI's executable file).


**********************
STRUCTURE OF XML FILES
**********************

The part of the XML structure (e.g. experiment's description) depends on implemented feature generators, therefore XML schemas must be created dynamically. To obtain the current one, you should use the command line:

> java -jar wsdde.jar -xsd

********************
CREATING YOUR OWN GENERATORS
********************

One should extend the abstract class wsdde.generator.FeatureGenerator. Moreover, the extending class should be in the package wsdde.genearator. You should also put XML schemas (xsd) describing generator's parameters into the wsdde.generator package. It is a good idea to look at built-in feature generators.

In the current version, using extra knowledge sources (e.g. wordnet, shallow parsing) is not supported by the architecture. Of course, you can do it on your own. In the future, when the environment accepts NKJP annotation standards, supporting of extra knowledge sources will be part of the architecture.

***************
USAGE SCENARIO
***************

The following sections describe some example scenarios on how to use WSDDE.

SCENARIO1

1. create a pseudowords corpus

(check poliqarp properites in config.ini, run poliqarp server)

> java -jar wsdde.jar -pws -wc parlament=500 dom=500 -o pws.xml

This generates file named pws.xml with 1000 context of pseudoword parlement-dom (~izba).

2. convert corpus to the enriched format

(check if takipi propeties is configured in config.ini or use -simple option)

> java -jar wsdde.jar -enr -i pws.xml -takipi -o pws.wsdc 

3. split the corpus into train and test corpora

> java -jar wsdde.jar -spl -i pws.wsdc -ss 500 500 -p pws

4. create the experiment's description from the metadescription
(edit meta.desc; to obtain syntax, just run "java -jar wsdde.jar -xsd")

>java -jar wsdde.jar -gmd -i metadesc.xml -o desc.xml

5. conduct the experiment

>java -Xmx1000m -jar wsdde.jar -coe -i desc.xml -o result.xml


