The same thing we do every night, Pinky - try to take over the world!

README.md

@@ -1,2 +1,81 @@
-# cognitive-system-postagger
-A pos-tagging library with Viterbi, CYK and SVO -> XSV translator made as part of my final exam for the Cognitive System course in Department of Computer Science.
+# Cognitive System - POS Tagger
+
+A pos-tagging library with Viterbi, CYK and SVO -> XSV translator made (English to Yodish) as part of my final exam for the Cognitive System course in Department of Computer Science. This README is a really bad translation of README_ita.md, made in ```nightly-build``` mode, so please excuse me for typos. The entire project is fully commented using italian, as log and cli because I'm from Italy and I was a newbie. One day I will translate this, promised :D :D :D !!!
+
+###Contents:
+
+[[1] Execution](#execution)
+
+[[2] Main files](#main-files)
+
+[[3] Deliveries and reports](#deliveries-and-reports)
+
+[[4] Notes](#notes)
+
+[[5] Contacts](#contacts)
+
+### <a name="execution"></a>Execution
+Run on Python v2. It has following dependencies:
+
+- nltk==3.2.4
+- numpy==1.13.1
+- scipy==0.19.1
+- six==1.10.0
+
+To run the exercises run the following (eventually in virtualenv) from a shell:
+
+```shell
+git clone https://github.com/made2591/cognitive-system-postagger.git
+cd cognitive-system-postagger
+pip install -r requirements.txt
+python main.py
+```
+The main program will guide you. Choose the number of exercise and configuration to run.
+
+The default program use a logger, which shows the main steps of the execution of the various procedures.
+To change the configuration of the file locations, enable file logging, change the verbosity please refer to the config file.
+
+### <a name="main-files"></a>Main files
+
+The files with core algorithm of are:
+
+- viterbi.py
+- cky.py
+- xsv.py
+
+### <a name="deliveries-and-reports"></a>Deliveries and reports
+
+In the delivery / report folders / there is a copy of the delivery pdf (without course slides) and the relationships with the three exercises. The reports contain a detailed description of what has been implemented and the results obtained plus some reflection on the latter and some attempts to justify what was expected and what was not.
+
+### <a name="notes"></a>Notes
+
+__NOTE 1__: Some of the config parameters do not have to be explained because they are required during run time. Non required parameters are listed within the config and mainly concern paths of files involved in the dumping of data structures and logging.
+
+__NOTE 2__: Viterbi training, with certain configurations, can be very long. In the dump folder / there is a file named:
+
+```shell
+v.1.3.2.viterbi_training.lst
+```
+
+This file contains the training dump for Viterbi with configuration 1.3.2 (runtimes and reports explain what these numbers mean).
+
+Viterbi execution is done with this configuration: if not explicitly requested the training is not re-executed. Instead, testing is performed at each run using the training uploaded / newly recreated. Testing does not take too much (over 400 phrases) but its execution is marked by messages that ensure its progress: in any case we are in the order of a couple of minutes.
+
+Training, however, takes a lot to be run, especially to calculate the distribution of words that appear once only. In any case, you can always overwrite the training with a new file: for each run with configuration X.x.x, if explicit, the program overwrites (if any) the dump of the old training structure for a future reload of the same in a file named:
+
+```shell
+x.x.x.viterbi_training.lst
+```
+
+It is therefore possible to maintain more dump of configurations of Viterbi in the same folder.
+
+__NOTE 3__: The CKY algorithm run using Viterbi output, assuming that there is a dump of training with configuration 1.3.2. That means that in order to function properly, the algorithm looks for the file ```v.1.3.2.viterbi_training.lst``` in the dump folder mentioned before. CYK method used to to extract the PCFG (Probabilistic context free grammars) in CNF (Chomsky Normal Form) from the training set of the second exercise takes a few seconds to calculate the grammar. So it has not been set up dump a specific dump. Instead, some test dump files have been prepared for CKY: testing CKY takes lot of time, and with certain configurations it can take us many days to complete the tests. For this reason, the method which delegates the evalb evaluation program is able to recover dumps
+of previously executed tests in the dump folder.
+
+Precisely, in the dump root / we find 4 files: these are the result of the execution of CKY with Viterbi and without Viterbi on 110 sentences limiting themselves to long sentences with no more than 25 terms (about 55 sentences). Respectively, gld and tst are the gold and test files (generated by CKY) with and without viterbi (no and with prefix).
+
+__NOTE 4__: In the corpora folder / we find the corpora used and the changes implemented for specific executions (CKY + Viterbi).
+
+### <a name="contacts"></a>Contacts
+
+If something goes wrong, please write to matteo.madeddu@gmail.com

README_ita.md

@@ -0,0 +1,105 @@
+##########################################################################################################
+########################## README - ESERCITAZIONI MODULO 1 - MATTEO MADEDDU ##############################
+##########################################################################################################
+
+Contenuti:
+
+    [1] Esecuzione
+    [2] File principali
+    [3] Consegne e relazioni
+    [4] Note
+    [5] Contatti
+
+[1] - Esecuzione
+
+    Per eseguire le esercitazioni: posizionarsi nella root
+    ed eseguire:
+
+    > python main.py
+
+    Il programma nel main contiene delle stampe a video per
+    scegliere quale esercitazione eseguire e con quale configurazione.
+
+    Il programma di default stampa a video tramite un logger,
+    che si limita a mostrare i passi principali dell'esecuzione dei vari
+    metodi.
+
+    Per cambiare le configurazioni inerenti le posizioni dei file
+    o per abilitare il logging su file, o modificare la verbosità
+    fare riferimento al file Config.
+
+[2] - File principali
+
+    I file che implementano i rispettivi core dei tre algoritmi implementati
+    con le rispettive varianti sono:
+
+        - viterbi.py
+        - cky.py
+        - xsv.py
+
+[3] - Consegne e relazioni
+
+    Nel cartelle consegne/ e relazioni/ c'è una copia del pdf delle consegne
+    (senza le slide) e delle relazioni svolte riguardo le tre esercitazioni.
+    Le relazioni contengono una descrizione dettagliata di cosa è stato implementato
+    e dei risultati ottenuti più qualche riflessione su questi ultimi e alcuni
+    tentativi di giustificazione di cosa è stato atteso e cosa no.
+
+[4] - Note
+
+    NOTA 1: alcuni dei parametri del Config non è necessario che siano
+    esplicitati nella classe poiché vengono richiesti in fase di esecuzione.
+    I parametri non richiesti e modificabili SOLO offline sono
+    indicati all'interno del Config e riguardano principalmente
+    path di dei file coinvolti nel dumping delle strutture dati o altro.
+
+    NOTA 2: l'addestramento di Viterbi, con determinate configurazioni,
+    può essere molto lungo. Nella cartella dump/ è presente un file
+
+        v.1.3.2.viterbi_training.lst
+
+    Questo file contiene il dump del training per Viterbi con configurazione
+    1.3.2 (a runtime e nelle relazioni è spiegato cosa vogliono dire questi numeri).
+
+    Di default, l'esecuzione di Viterbi viene fatta con questa configurazione
+    e se non esplicitamente richiesto l'addestramento non viene rieseguito.
+    Il testing viene invece effettuato ad ogni esecuzione sfruttando il file di
+    training caricato / appena ricreato. Anche il testing non impiega poco (su 400 frasi)
+    ma la sua esecuzione è scandita da messaggi che ne garantiscono l'avanzamento
+    e comunque siamo nell'ordine di un paio di minuti al massimo.
+
+    L'addestramento, invece, impiega molto ad essere eseguito, specialmente
+    per a calcolare la distribuzione delle parole che compaiono una volta sola.
+    In ogni caso, è sempre possibile sovrascrivere l'addestramento
+    con un nuovo file: per ogni esecuzione con configurazione
+    x.x.x se esplicitato, il programma sovrascrivere (se esiste) il dump della
+    vecchia struttura d'addestramento per un futuro reload della stessa in un file
+    x.x.x.viterbi_training.lst. E' quindi possibile mantenere più dump di configurazioni
+    di Viterbi distinte nella stessa cartella.
+
+    NOTA 3: l'algoritmo CKY che esegue facendo uso di Viterbi, parte dal presupposto
+    che esista un dump del training di viterbi con configurazione 1.3.2. Vale a dire
+    che per funzionare correttamente, l'algoritmo prevede la presenza del file
+
+        v.1.3.2.viterbi_training.lst
+
+    nella cartella dump/. Contrariamente all'addestramento di Viterbi, il metodo che si
+    preoccupa di estrarre la PCFG in CNF dal training set della seconda esercitazione
+    impiega pochi secondi a calcolare la grammatica. Quindi non è stato predisposto
+    dump per questa struttura. Sono stati predisposti dei file di dump del testing
+    di CKY: questo impiega DIVERSE ORE AD ESEGUIRE, e con determinate configurazioni
+    può metterci anche tanti giorni ad ultimare i test. Per questo motivo, il metodo
+    che sfrutta il programma di valutazione evalb, è in grado di recuperare dei dump
+    di test preventivamente eseguiti presenti nella cartella dump.
+
+    Precisamente, nella root di dump/ troviamo 4 file: questi sono il risultato dell'esecuzione
+    di CKY con Viterbi e senza Viterbi su 110 sentence limitandosi alle sentence lunghe
+    non più di 25 termini: ovvero circa 55 sentence. Rispettivamente, gld e tst sono i file
+    gold e test (generati da CKY) con e senza viterbi (no e with)
+
+    NOTA 4: nella cartella corpora/ troviamo i corpora usati e le modifiche attuate
+    per esecuzioni specifiche (CKY + Viterbi).
+
+[5] - Contatti
+
+    Se qualcosa non va, matteo.madeddu@gmail.com