Specifikace spam filtru

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

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 krok3

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

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

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

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í:

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

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

1. Č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.

• 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.

• 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!

1. 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.
2. 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.
3. 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á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 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á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:

1. filter.py. Implementace vašeho filtru.
2. 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.
3. 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.
4. 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.
5. případné další soubory, které váš filtr potřebuje k činnosti.
6. Neodevzdávejte moduly, které váš filtr přímo nevyužívá, např. moduly quality nebo confmat.
7. Neodevzdávejte testy k jednotlivým krokům!