====== Specifikace spam filtru ======

Úloha "Spam filter" má definovány 2 kontrolní body.

<WRAP important round>
Spam filtr musíte vypracovat v **Pythonu 3.4.x**, který bude nainstalován na strojích pro automatické hodnocení! 
Pokud této podmínce nevyhovíte, může se stát, že váš filtr nebude správně fungovat!
</WRAP>


===== Specifikace =====

Vaším úkolem je vytvořit třídu ''MyFilter'' v modulu ''filter.py'', která 
  * převezme trénovací korpus metodou ''train(train_corpus_dir)'',
  * naučí filtr na trénovacích emailech (pokud se tak rozhodnete) a
  * ohodnotí všechny emaily testovacího korpusu po zavolání metody ''test(test_corpus_dir)'', tj. vytvoří v adresáři testovacího korpusu soubor ''!prediction.txt''. Metoda by měla být schopná pracovat i tehdy, když předtím nedojde k natrénování filtru metodou ''train()''.
V korpusech se mohou vyskytovat **speciální soubory**, jejichž název vždy začíná znakem ''!'' (např. ''!truth.txt''). Tyto soubory **neobsahují maily - ignorujte je**!
  * filtr má za úkol detekovat spamy, očekáváse se tedy pozitivní reakce na spam a negativní na ham, detaily viz [[courses:a4b99rph:cviceni:spam:krok3|]]

/*
**Vstupem** filtru tedy budou
  * adresář s trénovacími emaily, t.j. trénovací korpus, a
  * adresář(e) s testovacími emaily, t.j. testovací korpus(y).

**Výstupem** (nebo spíš efektem) filtru bude
  * soubor **!prediction.txt** v každém z testovacích korpusů, obsahující predikce filtru pro jednotlivé emaily.
*/

Detailnější informace v následujících sekcích.

===== Použití třídy MyFilter =====
Třída bude definována v modulu s názvem ''filter.py''. Typické použití třídy bude následující:

<code python>
from filter import MyFilter

filter = MyFilter()
filter.train('/path/to/training/corpus')  # Tento adresář bude obsahovat soubor !truth.txt
filter.test('/path/to/testing/corpus')    # V tomto adresáři metoda vytvoří soubor !prediction.txt
</code>

Protože by ale metoda ''test()'' měla být schopná pracovat i bez předchozího volání metody ''train()'', je přípustné i toto použití:
<code python>
from filter import MyFilter

filter = MyFilter()
filter.test('/path/to/testing/corpus')    # V tomto adresáři metoda vytvoří soubor !prediction.txt
</code>

Při hodnocení kvality predikcí filtru samozřejmě budeme vždy volat metodu ''train()'' před metodou ''test()''.

==== Poznámky ====
/*  - **Počet testovacích korpusů**. Ačkoli jsou v ukázkách volání filtrů uvedeny jen 2 testovací korpusy, ve skutečnosti jich může být i více. Minimálně bude uveden jeden.
*/
  - **Časový limit**. Učení a ohodnocení testovacího korpusu by celkem nemělo zabrat více než 5 minut; filtru by mělo stačit i výrazně méně času.

===== Trénování =====
  * Pokud se váš spam filtr nebude umět učit, můžete trénovací corpus ignorovat. Pokud jste se rozhodli držet našich doporučení, měli byste ve třídě ''MyFilter'' implementovat metodu ''train()'', která ovšem může být prázdná. 
  * V trénovacím korpusu zcela jistě bude soubor ''!truth.txt'' s informací o skutečné třídě emailů v daném korpusu.

===== Testování =====
  * Váš filtr **musí** v adresáři testovacího korpusu **vytvořit soubor ''!prediction.txt''**, v němž pro každý soubor s emailem v testovacím korpusu uvede řádek ''nazevsouboru OK'', jedná-li se (podle mínění filtru) o korektní email, nebo ''nazevsouboru SPAM'', jedná-li se (podle mínění filtru) o spam.
  * //Váš filtr nesmí při testování v žádném případě využívat soubor ''!truth.txt'' v adresářích testovacích korpusů. Testy budou probíhat tak, že tam žádný takový soubor nebude!//

===== Možné varianty filtrů =====
  - Natvrdo "zadrátovaný" filtr, který se neumí učit. Takový filtr bude mít patrně prázdnou metodu ''train()''. V metodě ''test()'' pak bude nějakým způsobem využívat postupy zvolené autorem, podle nichž pro každý testovací email určí, jedná-li se o spam nebo ham.
  - Filtr využívající předem připravené externí informace (např. předem naučený filtr). Filtr bude mít asi také prázdnou metodu ''train()''. V metodě ''test()'' se pak bude rozhodovat na základě externích informací uložených v souboru (souborech) uploadovaných spolu se zdrojovým kódem filtru. Důvodem k takovéto "architektuře" může být např. to, že proces učení filtru je časově náročný - filtr byl studentem naučen offline a předem. (Pokud chce student v tomto případě body za to, že se filtr umí učit, musí na cvičení svého cvičícího přesvědčit, že předem připravené informace skutečně pocházejí z procesu učení.) Jiným důvodem použití této varianty může být využití nějakého externího slovníku, apod.
  - Učicí se filtr. Filtr nemá prázdnou metodu ''train()'' a ta je dostatečně rychlá, že zvládne extrahovat potřebné znalosti z informací uložených v řádově stovkách emailů (velikost trénovací sady). 

===== Odevzdání 1 =====
Odevzdávat budete ZIP archív s vaším modulem ''quality.py'' a případně se všemi moduly, které tento modul importuje. **Tyto soubory musí být v kořeni archívu, archív nesmí obsahovat žádné adresáře!** Pokud jste postupovali podle návodu, měl by váš archív obsahovat nejspíše soubory ''quality.py'', ''confmat.py'', ''utils.py'', příp. další.

Předmětem testování v této fázi bude pouze funkce ''compute_quality_for_corpus()'', tedy výstup z [[courses:a4b99rph:cviceni:spam:krok3|kroku 3]], kde najdete i její specifikace. Chceme tím zajistit, abyste všichni měli po ruce funkci, která vám snadno a správně vypočte, jak dobře vaše filtry pracují (jak kvalitní predikce poskytují).

===== Odevzdání 2 =====
Odevzdávat budete ZIP archív s vaším filtrem a všemi soubory, které váš filter potřebuje. **Tyto soubory musí být v kořeni archívu, archív nesmí obsahovat žádné adresáře!** Pokud jste postupovali podle návodu, měl by váš archív obsahovat následující soubory:

  - ''filter.py''. Implementace vašeho filtru.
  - ''basefilter.py''. Pokud jste našli nějakou funkcionalitu, která je společná všem filtrům a extrahovali jste ji např. do třídy ''BaseFilter'' v modulu ''basefilter.py'', od které třída vašeho filtru dědí, musíte do archívu zařadit i soubor ''basefilter.py''. 
  - ''corpus.py'' a ''trainingcorpus.py''. Pravděpodobně jste si uvědomili, že v metodě ''train()'' vašeho filtru s výhodou využijete třídu ''TrainingCorpus'', zatímco v metodě ''test()'' využijete zase třídu ''Corpus''. Pokud je využíváte, musíte je odevzdat v archivu spolu s vaším filtrem. 
  - ''utils.py''. Vaše třída ''TrainingCorpus'' pravděpodobně využívá funkci ''read_classsification_from_file'' z modulu ''utils.py'', musíte tedy do archívu zahrnout i tento soubor.
  - případné další soubory, které váš filtr potřebuje k činnosti.
  - **Neodevzdávejte** moduly, které váš filtr přímo nevyužívá, např. moduly ''quality'' nebo ''confmat''.
  - **Neodevzdávejte** testy k jednotlivým krokům!