Decipher NER

Obsah

1 Decipher NER
2 Knowledge Base
- 2.1 Umístění souborů nutných k vygenerování KB
3 Specifikace hlavičky HEAD-KB
- 3.1 Sloupce v HEAD-KB
4 Program a knihovny pro KB ve sdílené paměti
- 4.1 Použití
  - 4.1.1 Spuštění daemona
5 Nástroj ner.py
6 Jak funguje ner.py?
7 Tvorba Knowledge Base
8 Tvorba slovníků
9 Automatizace tvorby Knowledge Base a automatů
10 Matchovanie entít z dvoch rôznych Knowledge Baseov
11 Skript dates.py pro vytažení dat různých formátů z čistého textu
12 Testování skriptu start.sh
- 12.1 Sady testů
- 12.2 Porovnání výstupu z NERu s ruční anotací
  - 12.2.1 Aktuální výsledky shody ke dni 24. 3. 2015 pro soubory ze secapi/NER/data/input:
13 Rozpoznávanie mien osôb v texte
14 Integrace projektu Ner4
15 Porovnávání změn ve dvou různých KB

1 Decipher NER

Nástroj Decipher NER byl vytvořen v rámci projektu Decipher a slouží k vyhledávání a zjednoznačňování entit (např. osoba, umělec, lokace, ...) v textu. Ke své činnosti využívá znalostní bázi, která vznikla extrakcí a následným sloučením relevantních informací o entitách z mnoha zdrojů jako např. Wikipedia, Freebase, Geonames nebo Getty ULAN. Vlastní vyhledávání entit je prováděno nástrojem figa, který je založen na konečných automatech.

Nástroj NER je součástí většího celku projektu Decipher, který se nazývá secapi. Větší část nástroje je uložena v git repozitáři minerva1.fit.vutbr.cz/mnt/minerva1/nlp/repositories/decipher/secapi/, takže jsou na této stránce uváděny relativní cesty v tomto repozitáři. Nicméně, některé části (např. extrakce informací o entitách z různých zdrojů) zatím v repozitáři nejsou. Pro tyto případy jsou vždy uváděny absolutní cesty umístění na školních serverech.

Pro získání základní představy o tom, co vlastně NER dělá, můžete navštívit demo aplikaci na serveru knot24. Na tom samém serveru je také dostupný nástroj autocomplete, který dokáže efektivně nabízet entity ze znalostní báze.

2 Knowledge Base

Znalostní báze (Knowledge Base, zkráceně KB) projektu DECIPHER je uložena ve formátu TSV (Tab-separated values). Tento soubor obsahuje informace o entitách, přičemž na každém řádku je uložena vždy pouze jedna entita. Počet sloupců na řádku je závislý na typu dané entity. Typ entity je určen prefixem sloupce ID (první sloupec, zastaralé) nebo sloupcem TYPE (druhý sloupec) a popř. i sloupcem SUBTYPE (pokud je, pak je to třetí sloupec). Do budoucna se počítá se zrušením prefixů, proto je vhodné k identifikaci typu využívat sloupec TYPE. Podtypy rozšiřují rodičovský typ o další sloupce. (Proto jsou číslovány se znaménkem plus.) Sloupce, které mohou obsahovat více hodnot jsou označeny jako MULTIPLE VALUES. Pro oddělování vícenásobných hodnot se používá znak svislítko |. Kompletní přehled možných typů včetně popisu příslušných sloupců je možné nalézt níže. Sloupce, které mají název napsaný kurzívou jsou v KB.all prázdné, naplněné jsou v KBstatsMetrics.all.

Aktuální verzi KB je možno stáhnout ze serveru athena3 (popř. KBstatsMetrics.all) nebo je dostupná přímo na serveru athena3 v /mnt/data/kb/KB.all.

 PERSON (prefix: p)
 ==========================================
 01 ID
 02 TYPE
 03 SUBTYPE (MULTIPLE VALUES)
 04 NAME
 05 ALIAS (MULTIPLE VALUES)
 06 ROLE (MULTIPLE VALUES)
 07 NATIONALITY (MULTIPLE VALUES)
 08 DESCRIPTION (MULTIPLE VALUES)
 09 DATE OF BIRTH
 10 PLACE OF BIRTH
 11 DATE OF DEATH
 12 PLACE OF DEATH
 13 GENDER
 14 PERIOD OR MOVEMENT (MULTIPLE VALUES)
 15 PLACE LIVED (MULTIPLE VALUES)
 16 WIKIPEDIA URL
 17 FREEBASE URL
 18 DBPEDIA URL
 19 IMAGE (MULTIPLE VALUES)
 20 WIKI BACKLINKS
 21 WIKI HITS
 22 WIKI PRIMARY SENSE
 23 SCORE WIKI
 24 SCORE METRICS
 25 CONFIDENCE

 ARTIST (podtyp typu PERSON) (prefix: a)
 ==========================================
 +01 ART FORM (MULTIPLE VALUES)
 +02 INFLUENCED (MULTIPLE VALUES)
 +03 INFLUENCED BY (MULTIPLE VALUES)
 +04 ULAN ID
 +05 OTHER URL (MULTIPLE VALUES)

 LOCATION (prefix: l)
 ==========================================
 01 ID
 02 TYPE
 03 SUBTYPE (MULTIPLE VALUES)
 04 NAME
 05 ALTERNATIVE NAME (MULTIPLE VALUES)
 06 LATITUDE
 07 LONGITUDE
 08 FEATURE CODE
 09 COUNTRY
 10 POPULATION
 11 ELEVATION
 12 WIKIPEDIA URL
 13 DBPEDIA URL
 14 FREEBASE URL
 15 GEONAMES ID (MULTIPLE VALUES)
 16 SETTLEMENT TYPE (MULTIPLE VALUES)
 17 TIMEZONE (MULTIPLE VALUES)
 18 DESCRIPTION
 19 IMAGE (MULTIPLE VALUES)
 20 WIKI BACKLINKS
 21 WIKI HITS
 22 WIKI PRIMARY SENSE
 23 SCORE WIKI
 24 SCORE METRICS
 25 CONFIDENCE

 ARTWORK (prefix: w)
 ==========================================
 01 ID
 02 TYPE
 03 SUBTYPE (MULTIPLE VALUES)
 04 NAME
 05 ALIAS (MULTIPLE VALUES)
 06 DESCRIPTION
 07 IMAGE (MULTIPLE VALUES)
 08 ARTIST (MULTIPLE VALUES)
 09 ART SUBJECT (MULTIPLE VALUES)
 10 ART FORM
 11 ART GENRE (MULTIPLE VALUES)
 12 MEDIA (MULTIPLE VALUES)
 13 SUPPORT (MULTIPLE VALUES)
 14 LOCATION (MULTIPLE VALUES)
 15 DATE BEGUN
 16 DATE COMPLETED
 17 OWNER (MULTIPLE VALUES)
 18 HEIGHT
 19 WIDTH
 20 DEPTH
 21 WIKIPEDIA URL
 22 FREEBASE URL
 23 DBPEDIA URL
 24 PAINTING ALIGNMENT (MULTIPLE VALUES)
 25 MOVEMENT
 26 WIKI BACKLINKS
 27 WIKI HITS
 28 WIKI PRIMARY SENSE
 29 SCORE WIKI
 30 SCORE METRICS
 31 CONFIDENCE

 MUSEUM (prefix: c)
 ==========================================
 01 ID
 02 TYPE
 03 SUBTYPE (MULTIPLE VALUES)
 04 NAME
 05 ALIAS (MULTIPLE VALUES)
 06 DESCRIPTION
 07 IMAGE (MULTIPLE VALUES)
 08 MUSEUM TYPE (MULTIPLE VALUES)
 09 ESTABLISHED
 10 DIRECTOR
 11 VISITORS (MULTIPLE VALUES)
 12 CITYTOWN
 13 POSTAL CODE
 14 STATE PROVINCE REGION
 15 STREET ADDRESS
 16 LATITUDE
 17 LONGITUDE
 18 WIKIPEDIA URL
 19 FREEBASE URL
 20 ULAN ID
 21 GEONAMES ID (MULTIPLE VALUES)
 22 WIKI BACKLINKS
 23 WIKI HITS
 24 WIKI PRIMARY SENSE
 25 SCORE WIKI
 26 SCORE METRICS
 27 CONFIDENCE

 EVENT (prefix: e)
 ==========================================
 01 ID
 02 TYPE
 03 NAME
 04 ALIAS (MULTIPLE VALUES)
 05 DESCRIPTION
 06 IMAGE (MULTIPLE VALUES)
 07 START DATE
 08 END DATE
 09 LOCATION (MULTIPLE VALUES)
 10 NOTABLE TYPE
 11 WIKIPEDIA URL
 12 FREEBASE URL
 13 WIKI BACKLINKS
 14 WIKI HITS
 15 WIKI PRIMARY SENSE
 16 SCORE WIKI
 17 SCORE METRICS
 18 CONFIDENCE

 VISUAL ART FORM (prefix: f)
 ==========================================
 01 ID
 02 TYPE
 03 NAME
 04 ALIAS (MULTIPLE VALUES)
 05 DESCRIPTION
 06 IMAGE (MULTIPLE VALUES)
 07 WIKIPEDIA URL
 08 FREEBASE URL
 09 WIKI BACKLINKS
 10 WIKI HITS
 11 WIKI PRIMARY SENSE
 12 SCORE WIKI
 13 SCORE METRICS
 14 CONFIDENCE

 VISUAL ART MEDIUM (prefix: d)
 ==========================================
 01 ID
 02 TYPE
 03 NAME
 04 ALIAS (MULTIPLE VALUES)
 05 DESCRIPTION
 06 IMAGE (MULTIPLE VALUES)
 07 WIKIPEDIA URL
 08 FREEBASE URL
 09 WIKI BACKLINKS
 10 WIKI HITS
 11 WIKI PRIMARY SENSE
 12 SCORE WIKI
 13 SCORE METRICS
 14 CONFIDENCE

 VISUAL ART GENRE (prefix: g)
 ==========================================
 01 ID
 02 TYPE
 03 NAME
 04 ALIAS (MULTIPLE VALUES)
 05 DESCRIPTION
 06 IMAGE (MULTIPLE VALUES)
 07 WIKIPEDIA URL
 08 FREEBASE URL
 09 WIKI BACKLINKS
 10 WIKI HITS
 11 WIKI PRIMARY SENSE
 12 SCORE WIKI
 13 SCORE METRICS
 14 CONFIDENCE

 ART PERIOD MOVEMENT (prefix: m)
 ==========================================
 01 ID
 02 TYPE
 03 NAME
 04 ALIAS (MULTIPLE VALUES)
 05 DESCRIPTION
 06 IMAGE (MULTIPLE VALUES)
 07 WIKIPEDIA URL
 08 FREEBASE URL
 09 WIKI BACKLINKS
 10 WIKI HITS
 11 WIKI PRIMARY SENSE
 12 SCORE WIKI
 13 SCORE METRICS
 14 CONFIDENCE

 NATIONALITY (prefix: n)
 ==========================================
 01 ID
 02 TYPE
 03 NAME
 04 ALIAS (MULTIPLE VALUES)
 05 DESCRIPTION
 06 IMAGE (MULTIPLE VALUES)
 07 SHORT NAME
 08 COUNTRY NAME
 09 ADJECTIVAL FORM (MULTIPLE VALUES)
 10 WIKIPEDIA URL
 11 FREEBASE URL
 12 WIKI BACKLINKS
 13 WIKI HITS
 14 WIKI PRIMARY SENSE
 15 SCORE WIKI
 16 SCORE METRICS
 17 CONFIDENCE

 MYTHOLOGY (prefix: y)
 ==========================================
 01 ID
 02 TYPE
 03 NAME
 04 ALTERNATIVE NAME (MULTIPLE VALUES)
 05 WIKIPEDIA URL
 06 IMAGE (MULTIPLE VALUES)
 07 DESCRIPTION
 08 WIKI BACKLINKS
 09 WIKI HITS
 10 WIKI PRIMARY SENSE
 11 SCORE WIKI
 12 SCORE METRICS
 13 CONFIDENCE

 FAMILY (prefix: i)
 ==========================================
 01 ID
 02 TYPE
 03 NAME
 04 ALTERNATIVE NAME (MULTIPLE VALUES)
 05 WIKIPEDIA URL
 06 IMAGE (MULTIPLE VALUES)
 07 ROLE (MULTIPLE VALUES)
 08 NATIONALITY
 09 DESCRIPTION
 10 MEMBERS (MULTIPLE VALUES)
 11 WIKI BACKLINKS
 12 WIKI HITS
 13 WIKI PRIMARY SENSE
 14 SCORE WIKI
 15 SCORE METRICS
 16 CONFIDENCE

 GROUP (prefix: r)
 ==========================================
 01 ID
 02 TYPE
 03 NAME
 04 ALTERNATIVE NAME (MULTIPLE VALUES)
 05 WIKIPEDIA URL
 06 IMAGE (MULTIPLE VALUES)
 07 ROLE (MULTIPLE VALUES)
 08 NATIONALITY
 09 DESCRIPTION
 10 FORMATION
 11 HEADQUARTERS
 12 WIKI BACKLINKS
 13 WIKI HITS
 14 WIKI PRIMARY SENSE
 15 SCORE WIKI
 16 SCORE METRICS
 17 CONFIDENCE

 OTHER (prefix: o) 
 ==============================================================
 01 ID
 02 TYPE
 03 TITLE
 04 ALIAS (MULTIPLE VALUES)
 05 DESCRIPTION
 06 IMAGE (MULTIPLE VALUES)
 07 WIKIPEDIA URL
 08 WIKI BACKLINKS
 09 WIKI HITS
 10 WIKI PRIMARY SENSE
 11 SCORE WIKI
 12 SCORE METRICS
 13 CONFIDENCE

2.1 Umístění souborů nutných k vygenerování KB

V této sekci jsou uvedeny dílčí soubory nutné k vygenerování KB. Soubory jsou uvedeny pro každý typ zvlášť. Pokud některý typ není uveden, je to z toho důvodu, že pro generování dílčí KB daného typu nejsou potřeba žádné skripty a není proto pro ni vytvořen žádný adresář na gitu. Namísto toho se sloučení děje přímo ve skriptu prepare_data (viz níže). U jednotlivých typů je vždy v závorce uveden adresář na gitu, kde je možné najít skripty a konfigurační soubory nutné pro vytvoření KB daného typu.

 PERSON (secapi/NER/KnowBase/persons)
 ==========================================
 /mnt/minerva1/nlp/projects/decipher_freebase/data/freebase.persons 
 /mnt/minerva1/nlp/projects/decipher_wikipedia/Ludia_Wikipedia/outputs/categories_death_birth_data.csv

 ARTIST (secapi/NER/KnowBase/artists)
 ==========================================
 /mnt/minerva1/nlp/datasets/art/artbiogs/artbiogs.tsv
 /mnt/minerva1/nlp/datasets/art/bbc/bbc.tsv
 /mnt/minerva1/nlp/datasets/art/council/council.tsv
 /mnt/minerva1/nlp/datasets/art/distinguishedwomen/distinguishedwomen.tsv
 /mnt/minerva1/nlp/datasets/art/artists2artists/artists2artists.tsv
 /mnt/minerva1/nlp/datasets/art/the-artists/the-artists.tsv
 /mnt/minerva1/nlp/datasets/art/nationalgallery/nationalgallery.tsv
 /mnt/minerva1/nlp/datasets/art/wikipaint/final_data/wikipaint_artist.tsv
 /mnt/minerva1/nlp/datasets/art/davisart/davisart.tsv
 /mnt/minerva1/nlp/datasets/art/apr/apr.tsv
 /mnt/minerva1/nlp/datasets/art/rkd/rkd.tsv
 /mnt/minerva1/nlp/datasets/art/open/open.tsv
 /mnt/minerva1/nlp/projects/decipher_freebase/data/freebase.artists
 /mnt/minerva1/nlp/projects/decipher_ner/ULAN/ulan_rel_13/KB.artists
 /mnt/minerva1/nlp/projects/decipher_wikipedia/wiki_template/artists_extended
 /mnt/minerva1/nlp/datasets/art/artrepublic/artrepublic.tsv
 /mnt/minerva1/nlp/datasets/art/biography/biography.tsv
 /mnt/minerva1/nlp/datasets/art/englandgallery/englandgallery.tsv
 /mnt/minerva1/nlp/datasets/art/infoplease/infoplease.tsv
 /mnt/minerva1/nlp/datasets/art/nmwa/nmwa.tsv

 LOCATION (secapi/NER/KnowBase/locations)
 ==========================================
 /mnt/minerva1/nlp/projects/decipher_dbpedia/extraction_results/v39/v39_location_finall.tsv
 /mnt/minerva1/nlp/projects/decipher_freebase/data/freebase.locations
 /mnt/minerva1/nlp/projects/decipher_geonames/geonames.locations

 ARTWORK (secapi/NER/KnowBase/artworks)
 ==========================================
 /mnt/minerva1/nlp/projects/decipher_dbpedia/extraction_results/v39/v39_artwork_finall.tsv
 /mnt/minerva1/nlp/projects/decipher_freebase/data/freebase.artworks

 MUSEUM (secapi/NER/KnowBase/museums)
 ==========================================
 /mnt/minerva1/nlp/projects/decipher_dbpedia/extraction_results/v39/v39_museum_finall.tsv
 /mnt/minerva1/nlp/projects/decipher_freebase/data/freebase.museums
 /mnt/minerva1/nlp/projects/decipher_ner/ULAN/ulan_rel_13/KB.corporations
 /mnt/minerva1/nlp/projects/decipher_geonames/geonames.museums

 MYTHOLOGY (secapi/NER/KnowBase/mythology)
 ==========================================
 /mnt/minerva1/nlp/projects/extrakce_z_wikipedie/xgraca00/MythologyKB.txt 

 FAMILY (secapi/NER/KnowBase/artist_families)
 ==========================================
 /mnt/minerva1/nlp/projects/extrakce_z_wikipedie/xdosta40/final/finalFamilies.xml

 GROUP (secapi/NER/KnowBase/artist_group_or_collective)
 ==========================================
 /mnt/minerva1/nlp/projects/extrakce_z_wikipedie/xdosta40/final/finalGroupsAndCollectives.xml

 OTHER (secapi/NER/KnowBase/other)
 ==========================================
 /mnt/minerva1/nlp/projects/wikify/wikipedia/data/new_KB/KB.all

 Ostatní dílčí KB, které jsou integrovány do výsledné KB (viz skript secapi/NER/prepare_data)
 ==========================================
 /mnt/minerva1/nlp/projects/decipher_ner/KnowBase/PERSONS
 /mnt/minerva1/nlp/projects/decipher_ner/KnowBase/ARTISTS
 /mnt/minerva1/nlp/projects/decipher_ner/KnowBase/LOCATIONS
 /mnt/minerva1/nlp/projects/decipher_ner/KnowBase/ARTWORKS
 /mnt/minerva1/nlp/projects/decipher_ner/KnowBase/MUSEUMS
 /mnt/minerva1/nlp/projects/decipher_ner/KnowBase/MYTHOLOGY
 /mnt/minerva1/nlp/projects/decipher_ner/KnowBase/ARTIST_FAMILIES
 /mnt/minerva1/nlp/projects/decipher_ner/KnowBase/ARTIST_GROUP_OR_COLLECTIVE
 /mnt/minerva1/nlp/projects/decipher_freebase/data/freebase.events
 /mnt/minerva1/nlp/projects/decipher_freebase/data/freebase.visual_art_forms
 /mnt/minerva1/nlp/projects/decipher_freebase/data/freebase.visual_art_mediums
 /mnt/minerva1/nlp/projects/decipher_freebase/data/freebase.art_period_movements
 /mnt/minerva1/nlp/projects/decipher_freebase/data/freebase.visual_art_genres
 /mnt/minerva1/nlp/projects/decipher_freebase/data/freebase.nationalities
 /mnt/minerva1/nlp/projects/ie_foreign_wikipedia/xbajan01/wiki/output/es_only_data.tsv
 /mnt/minerva1/nlp/projects/ie_foreign_wikipedia/xklima22/wiki/outputs/de-wiki_only_people_data.tsv

 Soubor se statistikami
 ==========================================
 /mnt/minerva1/nlp/projects/decipher_wikipedia/wikipedia_statistics/wikipedia_statistics_2014-12-09.tsv

3 Specification of HEAD-KB header

Soubor HEAD-KB v /mnt/minerva1/nlp/repositories/decipher/secapi/ (odtud berme jako pracovní cestu) slouží jako konfigurační soubor pro načítání KB. Obsahuje kompletní specifikaci všech typů a sloupců v KB (viz kapitola Knowledge Base). U všech sloupců jsou uvedeny jejich datové typy, případně prefixy. Jednotlivé sloupce hlavičky jsou odděleny tabulátory tak, aby seděli k datovým sloupcům.

Používá se při generování KB ve skriptu NER/metrics_knowledge_base.py a vytváření souboru KB-HEAD.all.

3.1 Sloupce v HEAD-KB

Hlavička KB má syntaxi:

 <hlavička KB> ::= <řádek> "\n"
               | <řádek> <hlavička KB>
 <row> ::= <první sloupec> "\n"
         | <první sloupec> "\t" <ostatní sloupce> "\n"
 <první sloupec> ::= "<" <jméno typu> ">" <sloupec>
                  | "<" <jméno typu> ":" <jméno podtypu> ">" <sloupec>
 <ostatní sloupce> ::= <sloupec>
                   | <sloupec> "\t" <other_columns>
 <sloupec> ::= <název sloupce>
            | "{" <příznaky> "}" <název sloupce>
            | "{[" <prefix hodnoty> "]}" <název sloupce>
            | "{" <příznaky> "[" <prefix hodnoty> "]}" <název sloupce>

kde:

jméno typu - je řetězec označující typ (viz Knowledge Base)
jméno podtypu - je řetězec označující podtyp
příznaky - jsou znaky které určují datový typ (s – string, …), více hodnot v datech ve sloupci (m – multivalue) a identifikátor (i – identifier)
- Datové typy jsou pro vnitřní potřebu → suggestion formát SXML → ten používají programy navazující na SEC API(SEC LINK)
- Datové typy:
  - s - string (je použit implicitně při SXML)
  - d - decimal (reálná čísla)
  - e - date (datum v ISO 8601 formátu – přesněji formát YYYY-MM-DD)
  - g - image (URI na obrázek)
  - r - integer
  - u - uri (odkaz)
- Když sloupec může obsahovat více hodnot v datech, má příznak 'm'. Tento příznak se nastavuje podle MULTIPLE VALUES v kapitole Knowledge Base.
- Identifikátor (příznak 'i') je sloupec jehož hodnota je unikátní na každém řádku v celé tabulce daného sloupce. Pokud je na řádku identifikátorů více, vybírá se první neprázdný zleva.
prefix_hodnoty - je řeťezec, který bude připojen k datům v tomto sloupci
název_sloupce - je řeťezec se jménem sloupce

 příklad prvního sloupce v hlavičce: <location>ID
 příklad prvního sloupce v datech: l:21931315183

 epříklad ostatních sloupců v hlavičce: {iu[http://en.wikipedia.org/]}WIKIPEDIA URL
 příklad ostatních sloupců v datech: wiki/city_of_london

Regulární výraz pro získání jednotlivých položek sloupce v hlavičce v jazyce Python:

 PARSER = re.compile(r"""(?ux)
	 ^
	 (?:<(?P<TYPE>[^:>]+)(?:[:](?P<SUBTYPE>[^>]+))?>)?
	 (?:\{(?P<FLAGS>(?:\w|[ ])*)(?:\[(?P<PREFIX_OF_VALUE>[^\]]+)\])?\})?
	 (?P<NAME>(?:\w|[ ])+)
	 $
 """)
 column = u"<jméno typu:jméno podtypu>{flagy[prefix_hodnoty]}název_sloupce"
 PARSER.search(column).groupdict()
 {
 	 'TYPE': u'jmeno typu',
	 'SUBTYPE': u'jmeno podtypu',
	 'FLAGS': u'typov\xe9 prefixy',
	 'PREFIX_OF_VALUE': u'adresov\xfd prefix',
	 'NAME': u'jm\xe9no sloupce'
 }
 PARSER.search(column).group("TYPE")
 u'jmeno typu'

4 Program a knihovny pro KB ve sdílené paměti

Úkolem bylo vytvořit program v jazyku C, který načte KB jako prostý řetězec (string) do sdílené paměti. Program a knihovny jsou uloženy v Git repositáři /mnt/minerva1/nlp/repositories/decipher/secapi/ (odtud berme jako pracovní cestu). KB pro tento účel musí obsahovat hlavičku, která dává jednotlivým sloupcům v KB význam. Hlavička KB je oddělena od dat pomocí jednoho volného řádku.

Byli vytvořeny tři varianty:

1. varianta (SharedKB/var1) bere jako dělící znak pouze '\n', tedy jeden řádek KB je jeden string.
2. varianta (SharedKB/var2) dělí KB nejen na řádky, ale i na sloupce oddělené pomocí '\t'.
3. varianta (SharedKB/var3) vychází z 2. varianty, ale navíc vytvoří tabulku z "namelist.ASCII". Byla vytvořena za účelem snížení nároků na RAM při sestavování automatů pro figu.

První dvě varianty byly vytvořeny pro původní úkol. Bylo třeba zjistit, která z nich bude rychlejší. Jako rychlejší se ukázala druhá varianta.

Ke každé variantě je vytvořena dynamická knihovna libKB_shm.so a její nadstavba v Pythonu KB_shm.py. Nyní je ovšem nadstavba v Pythonu udržována pouze pro 2. variantu, o které vím, že se používá.

4.1 Použití

Daemon načte do sdílené RAM KB, popř. i namelist. Kopii této paměti uloží na disk vedle KB, dá ji stejné jméno jako je KB a příponu ".bin". Tato kopie slouží k urychlení příštího načtení a neměla přenášet mezi různými architekturami. Změna KB a namelist se sleduje a jsou-li novější než kopie SHM, znovu se načtou a znovu se vytvoří i kopie.

Jakmile daemon načetl do SHM data, vypíše na stdout "./decipherKB-daemon: Waiting for signal...". V tomto stavu pouze čeká na signál SIGTERM, SIGINT nebo SIGQUIT a když jeden z těchto tří signálů dostane, odstraní z SHM načtenou KB a ukončí se.

Pro práci s daty v SHM slouží zmíněná dvojice libKB_SHM.so a KB_shm.py. Popisovat je ale zde nebudu, jelikož jsou okomentovány v libKB_shm.h a KB_shm.py.

4.1.1 Spuštění daemona

1. varianta:

 decipherKB-daemon [{path_to_KB | -b path_to_KB_bin}]

2. varianta:

 decipherKB-daemon [-s SHM_NAME] [{path_to_KB | -b path_to_KB_bin}]

3. varianta:

 decipherKB-daemon [{path_to_KB path_to_namelist | -b path_to_KB_bin}]

path_to_KB - cesta ke KB (výchozí hodnota "./KB-HEAD.all")
path_to_namelist - cesta k namelist (výchozí hodnota "./namelist.ASCII")
-b path_to_KB_bin - načtení zmíněné kopie SHM
-s SHM_NAME - specifikace jména objektu ve sdílené paměti (výchozí je "/decipherKB-daemon_shm")

5 Nástroj ner.py

Nástroj pro rozpoznávání a disambiguaci jmenných entit je implementován ve skriptu ner.py. V této kapitole se nachází pouze informace o jeho spouštění. Bližší informace o tom, jak to funguje je možné nalézt zde.

Skript ner.py využívá ke své činnosti KB, která je nahrána ve sdílené paměti pomocí SharedKB.

5.1 Prerekvizity

Aktuální verze nástroje je dostupná na gitu ve větvi D114-NER (username je potřebné změnit za váš login).

 git clone ssh://username@minerva1.fit.vutbr.cz/mnt/minerva1/nlp/repositories/decipher/secapi/
 git checkout -b D114-NER origin/D114-NER

Před spuštěním je aktuálně nutné provést následující posloupnost příkazů:

  ./downloadKB.sh
 make

Je potřeba si dát pozor na to, aby se při použití skriptu downloadKB.sh, nenacházely v adresářích secapi/NER a secapi/NER/figa KB a automaty (*.fsa). Je proto vhodné je ještě předtím smazat pomocí skriptu deleteKB.sh.

5.2 Skript ner.py

Nástroj pracuje s knowledge base s pridanými stĺpcami obsahujúcmi štatistické dáta z Wikipedie a predpočítaným skóre pre disambiguáciu. Vyhľadávanie entít v texte a ich disambiguáciu potom umožňuje skript:

 secapi/NER/ner.py

Použití:

 ner.py [-h] [-a | -s] [-d] [-f FILE]

-h --help - vypíše nápovědu a skončí
-a --all - vypíše všechny entity ze vstupu bez rozpoznání
-s --score - vypíše pro každou entitu v textu všechny její možné významy a ohodnocení každého z těchto významů
-d --daemon-mode - "mód Daemon" (viz níže)
-f FILE --file FILE - použije zadaný soubor jako vstup
-r --remove-accent - odstraní diakritiku ze vstupu
-l --lowercase - převod vstupu na malá písmena a použití zvláštního automatu pouze s malými písmeny

Je také možné vstup načítat ze standardního vstupu (možnost využití přesměrování).

Testovací texty pro ner.py naleznete ve složce:

 secapi/NER/data/input

5.3 Daemon mode

Režim činnosti aktivovaný prítomnosťou prepínača -d umožňuje hromadné spracovanie viacerých textov s jednou inicializáciou. Text je očakávaný na štandardnom vstupe, ukončený na samostatnom riadku príkazom.

 NER_NEW_FILE - vypíše nalezené entity s disambiguací
 NER_NEW_FILE_ALL - vypíše nalezené entity bez disambiguace
 NER_NEW_FILE_SCORE - vypíše nalezené entity bez disambiguace, včetně skóre pro jednotlivé entity

Po zadaní príkazu nástroj vypíše zoznam entít nájdených v zadanom texte a výstup ukončí zopakovaním príkazu. Na vstupe potom očakáva ďalší text. Spracovanie textu zadaného od posledného príkazu a ukončenie programu spôsobí na samostatnom riadku príkaz:

 NER_END - ukončí program a vypíše nalezené entity s disambiguací
 NER_END_ALL - ukončí program a vypíše nalezené entity bez disambiguace
 NER_END_SCORE - ukončí program a vypíše nalezené entity bez disambiguace, včetně skóre pro jednotlivé entity

5.4 Výstup

Na štandardný výstup nástroj vypisuje zoznam nájdených entít v poradí, v akom sa vyskytujú vo vstupnom texte. Každej entite patrí jeden riadok, a stĺpce sú oddelené tabulátormi.

Riadky výstupu majú formát:

 BEGIN_OFFSET    END_OFFSET      TYPE    TEXT    OTHER

BEGIN_OFFSET a END_OFFSET vyjadrujú pozíciu začiatku a konca entity v texte.

TYPE označuje typ entity: kb pre položku knowledge base, date a interval pre datum a interval, coref pre koreferenciu zámenom alebo časťou mena osoby.

TEXT obsahuje textovú podobu entity tak, ako sa vyskytla vo vstupnom texte.

OTHER pre typy kb a coref má podobu zoznamu zodpovedajúcich čísel riadku v knowledge base oddelených znakom ";". Ak je zapnutá disambiguácia, zvolený je len jeden riadok zodpovedajúci najpravdepodobnejšiemu významu. Při použití skriptu s parametrem -s se zobrazí dvojice číslo řádku a ohodnocení entity, dvojice jsou od sebe odděleny středníkem. Pre typy date a interval obsahuje údaj v normalizovanom ISO formáte.

6 Jak funguje ner.py?

Konečný automat figa v texte nachádza rôzne druhy entít (person, location, artwork, museum, event, art form, art medium, art period movement, art genre, nationality) z KB, pričom ich textová podoba môže zodpovedať viacerým možnostiam významu. Úlohou bolo disambiguovať nájdené entity, vybrať spomedzi možných významov jeden, ktorý s čo najväčšou pravdepodobnosťou zodpovedá skutočnosti.

Pre každý možný význam entity v texte je vypočítané číselné skóre, pričom za výsledok disambiguácie sa vyberie význam s najvyšším skóre. Výsledné skóre je súčtom statickej zložky a kontextovej zložky.

6.1 Statické skóre

Statické skóre vyjadruje významnosť danej položky v knowledge base. Je vypočítané na základe štatistických údajov o článku o položke na Wikipedii: počet spätných odkazov, počet návštev článku, údaj, či má článok pre dané heslo primárny význam. Ak tieto nie sú dostupné, používajú sa iné metriky položky knowledge base. Pre skóre využívajúce štatistiky z Wikipedie aj druhý typ skóre je pre každú zložku vypočítané čiastkové skóre z intervalu 0 až 100. Čiastkové hodnoty sú rovnomerne spriemerované do výsledného skóre.

6.2 Čiastočné zhody mien

Aby bolo možné čo najlepšie určiť význam entít v texte, ktoré zodpovedajú len časti mena osoby (mena alebo priezviska), sú pre každú entitu nájdenú figou tieto možné významy dohľadávané.

Pred samotnou disambiguáciou sa pre každú osobu v knowledge base stĺpce DISPLAY TERM a PREFERRED TERM a každá hodnota OTHER TERMS rozdelí na jednotlivé mená (pôvodne oddelené medzerou). Ku všetkým sa zaznamená príslušný riadok knowledge base. Výsledkom procesu je slovník všetkých častí mien vyskytujúcich sa v knowledge base, ktorý ku každému menu priraďuje množinu riadkov knowledge base, kde je takéto meno použité.

Každá entita nájdená v texte sa potom rozdelí na slová, pre každé z nich sa nájde príslušná množina riadkov v knowledge base a vypočíta sa ich prienik. Takto sa získajú osoby, ktorých mená obsahujú všetky slová nájdené v rámci entity v texte. Tieto významy sa pridajú k tým nájdeným figou.

6.3 Kontextová disambiguácia

Kontextová disambiguácia pridáva kritérium context významu entity s významom zvyšku dokumentu.

U lokácií sa po prvom kole disambiguácie, ktoré prebehne bez ohľadu na kontext, zaznamenajú regions, kde ležia lokácie, ktoré sa stali výsledkom disambiguácie. Pre každú krajinu sa potom vypočíta podiel počtu lokácií patriacich danej krajine nájdených v lokáciách na vstupe. Pri druhom kole disambiguácie je táto hodnota použitá ako nová zložka skóre významov.

U osôb sa po prvom kole disambiguácie spočítajú výskyty jednotlivých osôb medzi výsledkami. Do skóre v druhom kole sa potom zarátava podiel počtu výskytov osoby spomedzi osôb nájdených v prvom kole.

6.4 Určovanie významu zámen – coreference resolution

Nástroj okrem entít z knowledge base a dátumov označuje aj anglické zámená. Následne sa snaží určiť, na čo odkazujú. Za význam zámena je určená posledná nájdená entita vhodného gramatického rodu. Osobám mužského pohlavia zodpovedajú zámená he, him, himself a his, osobám ženského pohlavia she, her, hers a herself, osobám ktoréhokoľvek pohlavia who, whom a whose. Dále se pracuje se zájmeny here, there, where.

6.5 Odstraňovanie prekrývajúcich sa entít

Konečný automat figa a skript dates.py môžu produkovať pre jedno miesto v texte viac výsledkov. Údaj o dátume môže byť zároveň názvom položky KB. V takom prípade je preferovaný dátum. V prípade, že viacero prekrývajúcich sa entít nájde figa, je preferovaná najdlhšia.

6.6 Odstraňovanie entít susediacich so slovom, ktoré začína veľkým písmenom

Pokiaľ najbližšie slovo pred začiatok alebo za koncom entity v texte začína veľkým písmenom je pravdepodobné, že označený text je súčasťou dlhšieho názvu a jeho význam tak nemusí zodpovedať významu označenej časti. Preto takéto entity nie sú vypisované. Výnimkou sú prípady keď sú susediace slová oddelené interpunkcou, alebo veľké písmeno označuje začiatok vety (predošlé slovo končí bodkou, otáznikom alebo výkričníkom).

6.7 Výkonnostné charakteristiky (zastaralé)

Rýchlosť spracovania textu nástrojom zabezpečujúcim vyhľadanie entít označujúcich osoby, miesta a umelecké diela a disambiguáciu ich významu a vyhľadanie dátumov a časových intervalov v texte bola meraná na serveri athena1, pričom meranie bolo opakované trikrát.

Testovací data obsahují názvy entit (tzn. 1 název = 1 řádek) v rozmezí 10,000 - 10,000,000.

Testovací data lze najít na tomto umístění v pracovní verzi NERu:

 secapi/NER/data/performance

Inicializácia nástroja trvá 4.902 s. V nasledujúcich časových údajoch je zarátaná.

Výkonnostné charakteristiky NERu - bez disambiguácie

Počet entit na vstupu	Veľkosť vstupu	Dĺžka spracovania
10,000	146 kB	5.6 s
100,000	1.5 MB	13.221 s
1,000,000	15.8 MB	89.282 s
10,000,000	152.8 MB	815.583 s

Výkonnostné charakteristiky NERu - s disambiguáciou

Počet entit na vstupu	Veľkosť vstupu	Dĺžka spracovania
10,000	146 kB	5.822 s
100,000	1.5 MB	18.197 s
1,000,000	15.8 MB	240.959 s
10,000,000	152.8 MB	2,533.679 s

7 Tvorba Knowledge Base

7.1 Tvorba dílčích KB

Tvorba dílčích KB PERSONS, ARTISTS, ARTWORKS, LOCATIONS, MUSEUMS, MYTHOLOGY, ARTIST_FAMILIES, ARTIST_GROUP_OR_COLLECTIVE a OTHER se odehrává v adresáři:

 secapi/NER/KnowBase

Jednotlivé KB jsou vytvářeny pomocí skriptu:

start.sh

který pro každý typ jednotlivě spouští skripty start.sh v příslušném podadresáři daného typu (artworks, locations, museums, persons, mythology, artist_families a artist_group_or_collective). e tedy možné spustit přegenerování pouze určitého typu samostatně. Vlastní tvorba dílčí KB se děje pomocí skriptu kb_compare.py (popsáno blíže zde). V tomto kroce se rovněž pro typ ARTIST a PERSON doplňují alternativní jména z JRC-NAMES.

V adresáři secapi/NER/KnowBase se nachází ještě několik dalších užitečných skriptů. Skript backupKB.sh provádí zálohovaní vstupních souborů pro tvorbu dílčích KB do umístění /mnt/data-in/knot/iotrusina/KB_data_backups. Skript copyKB.sh provádí nahrání nově vytvořených dílčích KB do umístění /mnt/minerva1/nlp/projects/decipher_ner/KnowBase. Skript deleteKB.sh smaže vytvořené dílčí KB. Skripty copyKB.sh a deleteKB.sh se spouštějí v rámci skriptu secapi/NER/start.sh.

7.1.1 Tvorba dílčí KB OTHER

KB vychází z KB.all projektu Wikify:

 /mnt/minerva1/nlp/projects/wikify/wikipedia/data/new_KB/KB.all

Její tvorba probíhá tak, že se postupně odfiltrují již použitá jména entit z předchozích vytvořených dílčích KB. Tedy skript projde dílčí KB PERSONS, ARTISTS, atd.., načte jména jednotlivých entit a postupně tato jména odfiltrovává z přípravné KB.all projektu Wikify. Entity, které zbydou a nejsou použity v žádné z dílčích KB, budou tvořit novou dílčí KB OTHER. Je proto nutné, aby byla OTHER tvořena jako poslední z daných dílčích KB (při přidání nějaké nové dílčí KB je nutné tuto KB připsat do skriptu secapi/NER/KnowBase/other/kb_filter_entity_out.py).

7.2 Tvorba KB.all

Knowledge Base KB.all vznikne sloučením dílčích KB s daty z Freebase a některých cizojazyčných Wikipedií.

Toto spojení probíhá ve skriptu:

 secapi/NER/prepare_data

Při použití parametru -i se zároveň stáhnou chybějící obrázky do databáze obrázků /mnt/athena3/kb/images (nyní pouze wikimedia obrázky).

Nově vzniklá Knowledge Base se nachází v souboru:

 secapi/NER/KB.all

7.3 Tvorba KBstatsMetrics.all

Knowledge Base KBstatsMetrics.all je de facto původní KB.all rozšířená o několik sloupců se statistikami. Vytváří se také ve skriptu prepare_data, kde se pomocí skriptů wiki_stats_to_KB.py a metrics_to_KB.py doplní na každý řádek příslušné statistiky.

Oproti popsanému formátu KB.all je každý řádek rozšířený o 6 sloupců: první tři tvoří statistiky příslušného článku na Wikipedii (backlinks, hits, primary sense). Získání těchto statistik je popsáno v projektu Decipher wikipedia. Čtvrtý tvoří skóre pro disambiguaci výpočítané na základě předešlých třech sloupců. Pátý sloupec obsahuje skóre pro disambiguaci vypočítané pomocí metrik jako jsou délka popisu, počet vyplněných sloupců v KB a nebo počet obyvatel dané lokace. Šestý sloupec obsahuje confidence skóre, které kombinuje všechny předchozí hodnoty do jedné.

Takto vzniklá Knowledge Base se nachází v souboru:

 secapi/NER/KBstatsMetrics.all

8 Tvorba slovníků

Nástroj ner.py ke své činnosti využívá nástroje figa, který pomocí několika slovníků dokáže v textu rozpoznávat entity. Popis nástroje figa i slovníků je možné najít na stránce projektu Ner4. V této kapitole je popsána pouze jejich tvorba. (Dříve byly ke stejnému účelu používané konečné automaty popsané na stránce projektu Decipher fsa).

Tvorba slovníků pro NER i pro autocomplete je prováděna pomocí skriptů create_cedar.sh a create_cedar_autocomplete.sh. Tyto skripty pracují se souborem KBstatsMetrics.all, z něhož získají seznam jmen, který se následně předloží nástrojem figav1.0, který dané automaty vytvoří.

 secapi/NER/figa/make_automat/create_cedar.sh

Použití:

 create_fsa.sh [-h] [-l|-u] [-c|-d] --knowledge-base=KBstatsMetrics.all

Povinné argumenty:

-k KB --knowledge-base=KB - path to KBstatsMetrics.all

Nepovinné argumenty:

-h --help - vypíše nápovědu a skončí
-l --lowercase - všechna jména budou převedena na malá písmena
-u --uri - vygeneruje seznam URI
-c --cedar (default) - vygeneruje slovníky CEDAR (přípona .ct)
-d --darts - vygeneruje slovníky DARTS (přípona .dct)

Pomocí skriptu create_cedar.sh jsou vygenerovány následující slovníky:

 automata.[ct|dct]       - základní automat pro ner.py
 automata-lower.[ct|dct] - automat pro lowercase variantu rozpoznávání
 automata-uri.[ct|dct]   - automat pro URI

Pomocí skriptu create_cedar_autocomplete.sh jsou vygenerovány následující slovníky:

 art_period_movement_automata.[ct|dct] - slovník pro autocomplete (typ ART PERIOD MOVEMENT)
 artwork_automata.[ct|dct]             - slovník pro autocomplete (typ ARTWORK)
 event_automata.[ct|dct]               - slovník pro autocomplete (typ EVENT)
 family_automata.[ct|dct]              - slovník pro autocomplete (typ FAMILY)
 group_automata.[ct|dct]               - slovník pro autocomplete (typ GROUP)
 location_automata.[ct|dct]            - slovník pro autocomplete (typ LOCATION)
 museum_automata.[ct|dct]              - slovník pro autocomplete (typ MUSEUM)
 mythology_automata.[ct|dct]           - slovník pro autocomplete (typ MYTHOLOGY)
 nationality_automata.[ct|dct]         - slovník pro autocomplete (typ NATIONALITY)
 person_automata.[ct|dct]              - slovník pro autocomplete (typ PERSON i s podtypem ARTIST)
 visual_art_form_automata.[ct|dct]     - slovník pro autocomplete (typ VISUAL ART FORM)
 visual_art_genre_automata.[ct|dct]    - slovník pro autocomplete (typ VISUAL ART GENRE)
 visual_art_medium_automata.[ct|dct]   - slovník pro autocomplete (typ VISUAL ART MEDIUM)
 x_automata.[ct|dct]                   - slovník pro autocomplete (typ všechny typy dohromady)

Oba tyto skripty jsou spouštěny uvnitř skriptu secapi/NER/start.sh.

9 Automatizace tvorby Knowledge Base a automatů

Proces tvorby Knowledge Base i všech potřebných automatů (včetně těch pro autocomplete) je automatizován. Proces je možné spustit pomocí skriptu:

 secapi/NER/start.sh

Tento skript postupně vytvoří dílčí KB, provede jejich sloučení do KB.all, vytvoří KBstatsMetrics.all, vytvoří automaty pro NER i autocomplete a umožní je nahrát na server athena3 (parametr -u nebo --upload) do umístění athena3:/mnt/data/kb, odkud se pak dají jednoduše stáhnout.

Kromě skriptu start.sh se na gitu v adresáři NER nacházejí některé další užiteční skripty. Skript deleteKB.sh provede smazání všech vytvořených KB a automatů. Skript uploadKB.sh nahraje vytvořené KB a automaty na server athena3 do umístění athena3:/mnt/data/kb. Skript downloadKB.sh provede stažení poslední stabilní verze KB a automatů ze serveru athena3. Skript TestAndRunStart.sh provede test všech prerekvizit potřebných pro generování automatů a KB a umožňuje spustit jejich řízené generování (více informací zde) s výpisem chyb, které při generování vznikly.

Proces tvorby KB a automatů by měly provádět pouze oprávněné osoby. Studentům je zakázáno spouštět skript start.sh s parametrem -u nebo --upload, protože by mohli způsobit nefunkčnost celého nástroje NER.

V případě, že někdo nahraje na server athena3 nefunkční verzi KB nebo automatů, je možné se manuálně vrátit vrátit k poslední funkční verzi. Jednotlivé verze se nacházejí v umístění athena3:/mnt/data/kb/kb a jsou číslovány pomocí Unix timestamp (např. 1413053397). Stačí tedy překopírovat všechny soubory v adresáři dané verze do umístění /mnt/data/kb/. Pokud se tedy chceme vrátit k verzi 1413053397, uděláme to pomocí následujícího příkazu:

 cp /mnt/data/kb/kb/1413053397/* /mnt/data/kb/.

10 Matchovanie entít z dvoch rôznych Knowledge Baseov

Cieľom bolo namatchovať entity z dvoch Knowledge Baseov. Z namatchovaných entít potom vytvoriť nový Knowledge Base. Skript funguje na "akúkoľvek" KB, zloženú z jedného typu entít (person alebo location, prípadne iné), podľa konfiguračných súborov. Matchování je implementováno ve skriptu kb_compare.py, který je dostupný na gitu:

 secapi/NER/KnowBase/kb_compare.py

Skript kb_compare.py nyní navíc umí na požádání deduplikovat vstupní KB pomocí atributu --deduplicate_kb1 či --deduplicate_kb2. Tuto funkci je možné provést zvlášť pomocí skriptu kb_dedup.py, který je také na gitu:

 secapi/NER/KnowBase/kb_dedup.py

10.1 Skript kb_compare.py

Použití:

 kb_compare.py [-h] --first FIRST --second SECOND [--first_fields FIRST_FIELDS] [--second_fields SECOND_FIELDS] --rel_conf REL_CONF 
 [--output_conf OUTPUT_CONF] [--other_output_conf OTHER_OUTPUT_CONF] [--first_sep FIRST_SEP] [--second_sep SECOND_SEP] 
 [--id_prefix ID_PREFIX] [--output OUTPUT]

Optional arguments:

-h --help - vypíše nápovědu a skončí
--first FIRST - název souboru první KB (použito jako prefix pro konfigurační soubory)
--second SECOND - název souboru druhé KB (použito jako prefix pro konfigurační soubory)
--first_fields FIRST_FIELDS - název souboru se seznamem fieldů první KB (default '(--first option).fields')
--second_fields SECOND_FIELDS - název souboru se seznamem fieldů druhé KB (default '(--second option).fields')
--rel_conf REL_CONF - název souboru s konfigurací vztahů
--output_conf OUTPUT_CONF - formát výstupu
--other_output_conf OTHER_OUTPUT_CONF - formát výstupu
--first_sep FIRST_SEP - první oddělovač více hodnot (default: '|')
--second_sep SECOND_SEP - druhý oddělovač více hodnot (default: '|')
--id_prefix ID_PREFIX - prefix pro ID
--deduplicate_kb1 - deduplicate_kb1 (default: False)
--deduplicate_kb2 - deduplicate_kb2 (default: False)
--id_fields ID_FIELD [ID_FIELD ...] - název fieldů s unikátním id pro deduplikaci(default: ['WIKIPEDIA URL', 'FREEBASE URL', 'DBPEDIA URL', 'ULAN ID', 'GEONAMES ID'])
--output OUTPUT - název výstupního souboru
--second_output SECOND_OUTPUT - název výstupního souboru s nenamatchovanými entitami z druhé KB
--treshold TRESHOLD - matchovací hladina

10.1.1 Description of parameters

--first_fields a --second_fields – Obsahujú štreku k súborom s názvy fieldov daných KB oddelené znakom nového riadku.
--output_conf – Konfiguračný súbor obsahujúci formát novo vytváranej KB (vytvára sa z UNIQUE a AMBIGUOUS_OK). Obsahuje názov_kb.názov_fieldu oddelené znakom nového riadku. Prázdne fieldy z prvej KB sa podľa --rel_conf, dohľadajú v druhej KB, a naopak.
--other_output_conf – Keďže KB je potrebné vytvoriť aj z dát, ktoré matchnuté neboli, existuje podobný konfiguračný súbor ako u --output_conf. V tomto súbore budú fieldy vždy s prefixom --first (okrem stĺpcov None). Field None je špeciálny typ fieldu, ktorý vytvára prázdny field. Je to potrebné kvôli zachovaniu konzistencie formátu novej KB (to znamená, že ak vo --first neexistujú niektoré fieldy zo --second, tak sa miesto nich dáva None).
--first_sep a --second_sep – Niektoré datové zdroje nevyužívaju konvenciu rozdeľovania MULTIPLE VALUES pomocou znaku '|'. Pre tieto prípady je možné tento separátor nastaviť týmito prepínačmi.
--id_prefix – V súboroch --output_conf a --other_output_conf je možné naraziť ešte na jeden typ. A tým je ID. ID je generované interne v skripte. Pomocou --id_prefix sa nastavuje prefix tohoto ID. Napríklad --id_prefix='p' znamená, že všetky ID budú začínať reťazcom "p:" (všeobecne používaný pre entity typu person).
--rel_conf – Tyto soubory popisují vztahy (relace) mezi dvěma porovnávanými databázemi. Řádky, na kterých jsou definovány jednotlivé vztahy, musí začínat tabulátorem. Konfigurační soubor může obsahovat následující návěští:
- UNIQUE: Vztah s unikátními, jedinečnými hodnotami. Typicky Wikipedia url nebo Freebase url.
- NAME: Vztah jmen, alternativních jmen, apod.
- OTHER: Ostatní vztahy, podle kterých nelze přiřazovat entity k sobě, ale které se použijí pro ohodnocení jednotlivých kandidátů.
--treshold – Je to bodová hranice, kterou musí entita dosáhnout, aby byla namatchována. Hodnota této hranice byla určena experimentálně, tak aby skript dával pokud možno co nejlepší výsledky. Hodnota závisí na počtu polí v KB a množství informací v nich. Např. v locations je nastavena na 4. Kvůli této změně bylo tento paramter nutné přidat do shellových skriptů start.sh. Parametr --threshold je povinný.
--second_output=filename – Umožňuje vypsat entity z KB2, které nebyly přiřazeny k žádné entitě z KB1, do zvláštního souboru. Při použití tohoto parametru se tyto entity už neobjeví v souboru zadaném parametrem --output !! Skript s tímto parametrem se používá při vzájemném porovnání již vygenerovaných KB typu ARTISTS a PERSONS.
--deduplicate_kb1 and deduplicate_kb2 - Povolí deduplikaci KB1, popř. KB2, dle sloupců s identifikátory. Tyto sloupce lze změnit pomocí atributu --id_fields.

10.1.2 Příklad spuštění

 ./kb_compare.py --first=DBPEDIA --second=GEONAMES --rel_conf=dbpedia_geonames_rel.conf --output_conf=DG_output.conf --output=DG
  --id_prefix=l --other_output_conf=DG_other_output.conf --treshold=4

10.2 Skript kb_dedup.py

Použití:

kb_dedup.py [-h] --kb KB [--kb_fields KB_FIELDS] [--kb_sep KB_SEP] [--id_fields ID_FIELDS [ID_FIELDS ...]] --output OUTPUT

Odstranění duplicit z KB.

Nepovinné argumenty:

-h --help - vypíše nápovědu a skončí
--kb KB - název souboru KB (užité jako prefix konfiguračního souboru)
--kb_fields KB_FIELDS - název souboru se seznamem fieldů KB (default '(--kb option).fields')
--kb_sep KB_SEP - oddělovač více hodnot (default: '|')
--id_fields ID_FIELD [ID_FIELD ...] - název fieldů s unikátním id pro deduplikaci (default: ['WIKIPEDIA URL', 'FREEBASE URL', 'DBPEDIA URL', 'ULAN ID', 'GEONAMES ID'])
--output OUTPUT - název výstupního souboru

10.2.1 Popis parametrů

--kb_fields - Cesta k souboru, jenž obsahuje názvy sloupců dané KB oddělené znakem nového řádku.
--kb_sep - Určí oddělovač hodnot ve vícehodnotových sloupcích značených řetězcem "MULTIPLE VALUES".
--id_fields - Deduplikace probíhá dle sloupců s identifikátory, které lze změnit pomocí tohoto atributu.

10.3 Popis konfiguračních souborů *_output.conf

Syntaxe (BNF):

 <soubor> ::= <řádek> | <řádek> <soubor>
 <řádek> ::= <zdroj sloupce> "\n"
 <zdroj sloupce> ::= "ID" | "None" | '"' <zdroj sloupce< '"' | <sloupec z kb>
 <sloupec z kb> ::= <název kb> "." <název sloupce>
 <název kb> ::= <název kb1> | <název kb2>

kde:

ID - vygeneruje na výstupní sloupec identifikátor jako prefix zadaný parametrem --id_prefix a hexadecimálně zapsaný hash sha224 z aktuální hodnoty počítadla
None - vygeneruje výstupní sloupec prázdný
<obsah sloupce> - vyplní daný sloupec tímto řetězcem
<sloupec z kb> - určuje který sloupec se použije pro výstup
- je-li zadaný sloupec prázdný, popř. má-li příznak "(MULTIPLE VALUES)" v odpovídajícím *.fields souboru, použije se jedna hodnota, popř. všechny hodnoty, z přiřazených sloupců dle vztahů v zadaném *_rel.conf
<název sloupce> je z odpovídajícího *.fields souboru KB <název kb> bez případného příznaku "(MULTIPLE VALUES)"
<název kb1> zadán parametrem --first
<název kb2> zadán parametrem --second

10.3.1 Příklad konfiguračního souboru artists/ARTISTS_output.conf:

 ID
 WF.TYPE
 WF.SUBTYPE
 ULAN.DISPLAY TERM
 WF.ALIAS
 WF.PROFESSION
 WF.NATIONALITY
 WF.DESCRIPTION
 ULAN.DATE OF BIRTH
 ULAN.PLACE OF BIRTH
 ULAN.DATE OF DEATH
 ULAN.PLACE OF DEATH
 ULAN.GENDER
 WF.PERIOD OR MOVEMENT
 WF.PLACE LIVED
 WF.WIKIPEDIA URL
 WF.FREEBASE URL
 WF.DBPEDIA URL
 WF.IMAGE
 WF.ART FORM
 WF.INFLUENCED
 WF.INFLUENCED BY
 ULAN.ID

10.4 Popis konfiguračních souborů *_other_output.conf

Syntaxe (BNF):

 <soubor> ::= <řádek> | <řádek> <soubor>
 <řádek> ::= <zdroj sloupce> "\n"
 <zdroj sloupce> ::= "ID" | "None" | '"' <obsah sloupce< '"' | <seznam sloupců z kb>
 <seznam sloupců z kb> ::= <sloupec z kb> | <sloupec z kb> "|" <seznam sloupců z kb>
 <sloupec z kb> ::= <název kb> "." <název sloupce>
 <název kb> ::= <název kb1>

kde:

ID vygeneruje na výstupní sloupec identifikátor jako prefix zadaný parametrem --id_prefix a hexadecimálně zapsaný hash sha224 z aktuální hodnoty počítadla
None vygeneruje výstupní sloupec prázdný
<obsah sloupce> vyplní daný sloupec tímto řetězcem
obsahuje-li <seznam sloupců z kb> více než jeden sloupec, pak předpokládáme že výstupní sloupec má příznak "(MULTIPLE VALUES)"
<sloupec z kb> určuje který sloupec se použije pro výstup
<název sloupce> je z odpovídajícího *.fields souboru KB <název kb> bez případného příznaku "(MULTIPLE VALUES)"
<název kb1> zadán parametrem --first

10.4.1 Příklad konfiguračního souboru artists/artrepublic/OUT_other_output.conf:

 ID
 "person"
 "artist"
 ARTREPUBLIC.NAME
 None
 None
 None
 ARTREPUBLIC.DESCRIPTION|ARTREPUBLIC.ABOUT
 None
 None
 None
 None
 None
 None
 None
 None
 None
 None
 ARTREPUBLIC.LOCAL IMAGE
 None
 None
 None
 None
 ARTREPUBLIC.PROFILE LINK

10.5 Popis konfiguračních souborů *_rel.conf

Syntaxe (BNF):

 <soubor> ::= <unique> <name> <other>
 <unique> ::= "UNIQUE:" "\n" <seznam vztahů>
 <name> ::= "NAME:" "\n" <seznam vztahů>
 <other> ::= "OTHER:" "\n" <seznam vztahů>
 <seznam vztahů> ::= "" | <vztah> <seznam vztahů>
 <vztah> ::= "\t" <sloupec z kb1> "=" <sloupec z kb2> "\n"
 <sloupec z kb1> ::= <název kb1> "." <název sloupce>
 <sloupec z kb2> ::= <název kb2> "." <název sloupce>

kde:

<unique> jsou vztahy mezi unikátními, jedinečnými hodnotami. Jsou to identifikátory entity. Typicky Wikipedia url nebo Freebase url.
<name> jsou vztahy jmen, alternativních jmen, apod.
<other> jsou ostatní vztahy, podle kterých nelze přiřazovat entity k sobě, ale které se použijí pro ohodnocení jednotlivých kandidátů.
<vztah> je vztah mezi sloupci <sloupec z kb1> and <sloupec z kb2>
- pokud je v *.fields upřednostněn sloupec, jenž je prázdný nebo má příznak "(MULTIPLE VALUES)" v odpovídajícím *_output.conf souboru, pak má vliv i na obsah výstupního sloupce
<název kb1> zadán parametrem --first
<název kb2> zadán parametrem --second

10.5.1 Příklad konfiguračního souboru artists/wikipedia_freebase_rel.conf:

 UNIQUE:
	 WIKIPEDIA.WIKIPEDIA URL=FREEBASE.WIKIPEDIA URL
	 WIKIPEDIA.FREEBASE URL=FREEBASE.FREEBASE URL
 NAME:
 	 WIKIPEDIA.NAME=FREEBASE.NAME
	 WIKIPEDIA.NAME=FREEBASE.ALIAS
	 WIKIPEDIA.ALTERNATIVE NAME=FREEBASE.NAME
	 WIKIPEDIA.ALTERNATIVE NAME=FREEBASE.ALIAS
 OTHER:
	 WIKIPEDIA.DATE OF BIRTH=FREEBASE.DATE OF BIRTH
	 WIKIPEDIA.DATE OF DEATH=FREEBASE.DATE OF DEATH
	 WIKIPEDIA.PLACE OF BIRTH=FREEBASE.PLACE OF BIRTH
	 WIKIPEDIA.PLACE OF DEATH=FREEBASE.PLACE OF DEATH
	 WIKIPEDIA.WORK=FREEBASE.PROFESSION
	 WIKIPEDIA.NATIONALITY=FREEBASE.NATIONALITY
	 WIKIPEDIA.INFLUENCED=FREEBASE.INFLUENCED
	 WIKIPEDIA.INFLUENCED BY=FREEBASE.INFLUENCED BY
	 WIKIPEDIA.PERIOD OR MOVEMENT=FREEBASE.PERIOD OR MOVEMENT
	 WIKIPEDIA.IMAGE=FREEBASE.IMAGE

10.6 Tvorba KB typu Artworks

Datové zdroje dostupné z:

 secapi/NER/KnowBase/artworks

V priečinku artworks je niekoľko súborov. Tými sú:

 DBPEDIA (datový zdroj získaný z DBPEDIE)
 DBPEDIA.fields (formát datového zdroja DBPEDIE – všimnite si hlavne postfix " (MULTIPLE VALUES)" potrebný pre rozlíšenie viacerých hodnôt vo fielde)
 FREEBASE (datový zdroj získaný z FREEBASE)
 FREEBASE.fields (formát datového zdroja FREEBASE)
 ARTWORKS (novo vytvorená KB – ktorú chceme vytvoriť odznova)
 ARTWORKS.fields (formát novej KB potrebný pre ostatných členov podieľajúcich sa na Decipheri)
 ARTWORKS_other_output.conf (konfiguračný súbor pre prepínač --conf_other_output)
 ARTWORKS_output.conf (konfiguračný súbor pre prepínač --conf_output)
 dbpedia_freebase_rel.conf (konfiguračný súbor určujúci relácie medzi fieldami DBPEDIE a FREEBASE)
 start.sh (príkaz pre spustenie tvorby novej KB so všetkými potrebnými prepínačmi)

10.7 Ako to funguje?

Skript si po zapnutí získa prepínače z príkazovej riadky a otvorí potrebné súbory (trieda Init).
Snaží sa spracovať všetky konfiguračné súbory (trieda kb_config.Config).
Načíta datové zdroje do internej datovej štruktúry (každý riadok je objekt typu kb_data.Data).
Vytvára indexy zo --second – potrebné kvôli redukcii časovej zložitosti matchovania (trieda kb_index.Index).
Nastáva samotné matchovanie (kb_match.Match). Matchovanie je jeden veľký cyklus, ktorý vezme riadok z datového zdroja --first a porovnáva ho so všetkými údajmi zo --second na základe relácií definovaných v --rel_conf. Využíva pri tom indexovaný --second datový zdroj.
Poslednou úlohou je samotné generovanie KB z interných datových štruktúr (trieda kb_match.Output).

10.8 Popis hledání odpovídajících si entit

Porovnávají se vždy dvě Knowledge base – KB1 a KB2. KB1 se postupně prochází po jednotlivých řádcích a ke každému řádku se hledá odpovídající záznam v KB2. Nejprve se hledá v KB2 položka se stejným unikátním identifikátorem (typicky wikipedia url). Porovnávají se pole určené návěštím UNIQUE. Může se hledat i podle více takovýchto identifikátorů. Pokud je nějaký takový záznam v KB2 nalezen, je hned přiřazen k záznamu v KB1 a vyhledávání končí. Pokud nic nebylo nalezeno nebo pokud záznam v KB1 neobsahuje identifikátor, probíhá vyhledávání kandidátů podle vztahů určených návěštím NAME. Typicky se porovnávají jména, pseudonymy, alternativní jména apod. Výsledkem hledání je seznam kandidátů vhodných k přiřazení. Každý kandidát je ohodnocen podle počtu shodných řetězců. Následuje hodnocení na základě vztahů za návěštím OTHER. K přiřazení je vybrán kandidát s nejlepším ohodnocením, pokud je ohodnocení větší nebo rovno stanovenému prahu (treshold), jinak se nevybere nic. Entita z KB2 se označí příznakem „used“, aby již dále nemohla být použita.

10.9 Případy, kdy se entity nepřiřadí k sobě

V některých případech může dojít k tomu, že dvě entity se nespárují, i když by měly. Ukázkou takového případu jsou například následující dva záznamy:

 a:8b4f4e2666	artist	Charles Alexander Smith	Charles Alexander Smith	Charles Alexander Smith	Canadian
 	 Charles Alexander Smith was a Canadian painter from Ontario.	1864	1915	M	
 http://www.freebase.com/m/0269dw5 http://en.wikipedia.org/wiki/Charles_Alexander_Smith	http://dbpedia.org/page/Charles_Alexander_Smith freebase/02cy_gx.jpg

 a:3f368917fe	artist	Charles Alexander	Alexander, Charles	Alexander Charles Smith	artist	
 photographer|painter	British	Canadian British painter, 1864-1915	1864	Ontario 
 (Canada) (province)	1915	London (Greater London, England, United Kingdom) (inhabited place)	M	500026312

Tyto dva záznamy nebylo možné k sobě přiřadit. Především, druhý záznam neobsahuje žádný unikátní identifikátor, jako např. wiki URL, podle kterého by mohl být jednoznačně přiřazen k prvnímu záznamu. Přiřazení podle shody jmen bohužel také nebylo úspěšné, jelikož první záznam obsahuje pouze jméno "Charles Alexander Smith" a druhý záznam obsahuje "Charles Alexander", "Alexander, Charles" a "Alexander Charles Smith". Všimněte si, že zde jsou křestní jména v opačném pořadí, řetězce se neshodují, tudíž entity nebyly vzájemně přiřazeny.

11 Skript dates.py pro vytažení dat různých formátů z čistého textu

Úkolem je vytvořit regulární výraz, který bude umět vytáhnout všechny běžně se vyskytující formáty dat v textu (2004-04-30, 02/30/1999, 31 January 2003 atd.). Regulární výraz by měl být komplexní (pouze jeden reg. výraz) a měl by umět vytáhnout co nejvíce bežných formátů (časy nás nezajímají, pouze roky, měsíce a dny).

Po vytáhnutí dat se provede jejich normalizace (do ISO 8601), aby bylo možné s daty dále pracovat.

Kromě regulárního výrazu bylo třeba napsat kód (funkci a třídu) pro jeho zpracování a předání zpracovaných dat dalším skriptům.

Vstupem je prostý text v anglickém jazyce (typ str) a výstupem je seznam (typ list) položek třídy Date.

Pokud by měl být skript dokonalý musel by obsahovat sémantickou analýzu anglického textu, která by rozeznala co je a co není datum popř. rok.

Skript se nachází na gitu v umístění:

 secapi/NER/dates.py

11.1 Třídy

Class Date

Třída pro nalezená data. Kromě roku, měsíce a dnu obsahuje také místo nalezení ve zdrojovém řetězci a řetězec, ze kterého bylo toto datum převedeno. Po vytvoření nové instance je nutné zavolat init_date() nebo init_interval() pro inicializaci atributů.

Má dva typy, DATE pro prosté datum a INTERVAL pro interval mezi dvěma daty. Zde je příklad s komentáři:

 class_type: DATE          # Atribut značící typ nalezeného data (prosté datum či interval).
 source:     April 2, 1918 # Řetězec source ze zdrojového textu.
 iso8601:    1918-04-02    # Datum v **ISO_date**
 s_offset:   265           # Začátek řetězce source ve zdrojovém textu
 end_offset: 278           # Konec řetězce source ve zdrojovém textu (vypočítaný z """s_offset + len(source)""")
 ---------------------------------
 class_type: INTERVAL
 source:     1882-83
 date_from:  1882-00-00    # Počáteční datum v **ISO_date**
 date_to:    1883-00-00    # Koncové datum v **ISO_date**
 s_offset:   467        
 end_offset: 474

Třída ISO_date

Třída uchovávající datum (tedy rok, měsíc a den). Obsahuje atributy day, month a year. Vytvořena pro nahrazení datetime.date v situacích kdy známe jen rok. V takovém případě se neznámé údaje nahradí hodnotou nula (např. 1881-00-00).

11.2 Vlastnosti

Vytažení data ze zdrojového textu
Vytažení datového intervalu ze zdrojového textu
Pro normalizaci (do ISO 8601) se používá dateutil.parser
Pokud je nalezeno číslo, pak se jako rok bere pouze když má 4 číslice
Pokud bude v textu neúplné datum, bere se jen měsíc a rok popř. jen rok

11.3 Podporované formáty

11.3.1 Datum

Sept. 12, 2007
Jul 18 '10
1999-12-28
12-11-1694, 12/11/1694
12.11.1694, 12. 11. 1694
12th Nov. 1694, 8th of November 2003, 27 May 1859

Pouze měsíc a rok:

November 2003

Pouze rok:

1694, 1690s

11.3.2 Interval

June 6-Sept. 23, 2007
Aug. 4-31, 2007
June. 6, 2005 – Sept. 12, 2007
20 March 1856 – 10 January 1941
1694-99
1693-1734, 1693 to 1734

11.4 Problémy a nejasnosti

Při použití dateutil.parser:

 str(dateutil.parser.parse("Jul 18 '30").date()) -> '2030-07-18' # automaticky doplní aktuální první dvojčíslí - považuji za správné
 str(dateutil.parser.parse("Jul 18 30").date()) -> '2030-07-18' # co když to rok 30?
 str(dateutil.parser.parse("0030-01-01").date()) -> '2001-01-30' # vypadá to, že dateutil.parser nebere rok menší než sto
 str(dateutil.parser.parse("0099-01-01").date()) -> '1999-01-01' # nedoplní vždy aktuální první dvojčíslí, ale nejbližší
 str(dateutil.parser.parse("Jul 18 '62").date()) -> '2062-07-18' # jelikož je rok 2013
 str(dateutil.parser.parse("Jul 18 '63").date()) -> '1963-07-18' # jelikož je rok 2013
 str(dateutil.parser.parse("0100-01-01").date()) -> '0100-01-01' # správné
 
 když dostanu DD/MM/YYYY, pak dateutil.parser vezme toto datum jako MM/DD/YYYY pokud DD < 13 jinak jako DD/MM/YYYY
 str(dateutil.parser.parse("10/1/2000").date()) -> '2000-10-01'
 str(dateutil.parser.parse("13/1/2000").date()) -> '2000-01-13'

11.5 Statistické údaje

Při prohledání 45,764,556 slov bylo nalezeno 561,744 údajů (z toho 177,336 interavalů) za 11m 17.836s, tedy rychlostí 67,515.6764 slov za sekundu.

12 Testování skriptu start.sh

Úkolem bylo vytvoření sady testů pro skript start.sh uložený v secapi/NER.

Seznam vytvořených souborů:

 secapi/NER/TestAndRunStart.sh - testovací skript
 secapi/NER/AllKB.txt - seznam souborů potřebných k tvorbě nové KB
 secapi/NER/fields.txt - seznam field souborů
 secapi/NER/MatchKBAndFields.py - skript, který spojí k jednotlivým KB příslušný fields soubor

12.1 Test sets

Pokud je skript spuštěn s parametrem -t jako první skript TestAndRunStart.sh testuje dostupnost souborů, se kterými pracuje start.sh a skripty, které start.sh spouští. Dále se provádí kontrola, zda mají *.py a *.sh soubory nastavená patřičná práva. Následuje testování správného formátu, respektive počtu sloupců, souborů, které jsou potřebné k tvorbě nové KB (seznam v souboru AllKB.txt). Počet sloupců musí být shodný s počtem sloupců ve fields souborech uložených v NER/KnowBase.

Při spuštění s parametrem -r je volán skript start.sh a stderr je přesměrován do souboru. Po skončení skriptu je stderr analyzována a vypíší se jména chybějící souborů, pokud nějaké jsou, počet chyb vzniklých za běhu a počet varování. Po vytvoření nových automatů a KB dochází ke srovnávání se starými verzemi automatů a souborů KB.all a KBstatsMetrics.all. Skript hlásí chybu pokud je rozdíl nově vytvořeného souboru a starší verze větší než 5% nebo když je nový soubor menší o více než 10%. Skript také hlásí chybu v případě, že nedošlo k vytvoření nějakého automatu nebo KB.

K testování skriptů ner.py dochází při spuštění s parametrem -n a nástroje figav08 při spuštění s parametrem -f. Testování probíhá ze 75% na datech uložených v secapi/NER/data/input. V ostatních případech je testována konkrétní entita. "Paris 1984" u ner.py a "A Alewijn" u figav08. Dále je nástroj ner.py (také při spuštění s parameterem -n) testován s různými přepínači. Dochází ke spuštění nástroje bez přepínačů, s přepínačem -l (převod vstupu na malá písmena), s přepínačem -r (s chybou v diakritice na vstupu) a spuštění s přepínači -l a -r se špatným vstupním textem.

Příklady spuštění:

 ./TestAndRunStart.sh -t -> spustí testování existence souborů, jejich oprávnění a testování formátu souboru potřebných k tvorbě KB
 
 ./TestAndRunStart.sh -r -> spustí skript start.sh
 
 ./TestAndRunStart.sh -f -> spustí se testování nástroje figa

 ./TestAndRunStart.sh -n -> spustí se testování nástroje ner

 ./TestAndRunStart.sh -h -> spuštění nápovědy k programu

 ./TestAndRunStart.sh -c -> spustí skript CheckNerOut.py - testování výstupu z Neru s ruční anotací

12.2 Porovnání výstupu z NERu s ruční anotací

Pro porovnání slouží skript CheckNerOut.py, který na výstup vypíše procentuální shodu. Do složky secapi/NER/CheckNerOut ukládá soubor s entitami z anotace, které nebyly spárované. Totéž provádí s entitami ze souboru, který obsahuje výstup z NERu. Skript byl zakomponován do skriptu TestAndRunStart.sh, kde testuje soubory, ke kterým existuje ruční anotace.

Příklad spuštění:

 python CheckNerOut.py -a SouborSAnotaci.tsv -o NerOutput.txt

12.2.1 Aktuální výsledky shody ke dni 24. 3. 2015 pro soubory ze secapi/NER/data/input:

 Paul_Kane: 56.6037735849%
 travelling_artist_part2: 69.0909090909%
 travelling_artist_part3: 81.6513761468%
 Dossier_and_OS_texts.docx: 56.5020576132%

13 Rozpoznávanie mien osôb v texte

Účelom skriptu je rozpoznávanie krstných a rodných mien osôb vo zvolenom texte pomocou zoznamu mien. Nástroj sa nachádza v git repozitári v priečinku secapi/NameRecognizer v branchi D114-NER.

13.1 Postup

1. krok - Zostavenie zoznamu mien

Najprv bolo potrebné zostaviť zoznam mien pre konečný automat. Preto som vytvoril nástroj Name Collector, ktorý je popísaný nižšie. Z výstupných textových súborov nástroja je pre konečný automat podstatný len súbor outputs/all.txt.

2. krok - Kompilácia nástroja figa:

Najprv je potrebné stiahnuť git repozitár nástroja figa (viď. Decipher_fsa) to:

 /mnt/minerva1/nlp/projects/decipher_ner/xklima22

a následne spustiť skript:

 /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/create_figa.sh

Skript skompiluje nástroj a skopíruje ho do priečinku:

/mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/data

3. krok - Zostavenie konečného automatu:

Rovnako ako v 2. kroku je potrebné aby bol stiahnutý git repozitár figy a potom treba spustiť skript:

 /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/create_fsa.sh

Skript zostaví konečný automat automat.fsa pomocou zoznamu mien z prvého kroku a umiestni ho do priečinku:

 /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/data

4. krok - Spracovanie výstupov figy:

Výstupy figy upravujem pomocou sort -u a potom ďalej skriptom process_outputs.py script:

 /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/process_outputs.py

Skript prijíma 2 parametre - vstupný a výstupný súbor - a spája získané mená na základe offsetov.

Skript process_outputs.py využíva pri filtrovaní zoznamy, ktoré sú uložené v priečinku data/lists a sú to (abecedne):

 blist_locations.txt  - zoznam lokácií, vytváraný skriptom kb_locations
 custom_names.txt     - zoznam manuálne doplnených mien
 custom_surrnames.txt - zoznam manuálne doplnených priezvisk
 names.txt            - zoznam mien, z výsledkov skriptov name_collector a kb_list
 nationalities.txt    - zoznam národností
 notfirst.txt         - zoznam slov, ktoré nemôžu byť na prvej pozícii
 replace.txt          - zoznam slov alebo slovných spojení, ktoré majú byť z mien odstránené 
 surrnames.txt        - zoznam priezvisk, z výsledkov skriptov name_collector a kb_list

Celý krok je zautomatizovaný pomocou skriptu run.sh, ktorý načítava data zo stdin a výsledky vypisuje na stdout.

Skript okrem mien vyhľadá v texte aj iniciálky (dvojznakové slová zložené z kapitálky a bodky) zistí ich začiatočné a koncové offsety a potom ich pridá do zoznamu mien z výstupu nástroja figa. Po získaní zoznamu mien sa z mien končiacich "'s" táto časť odstráni a prepočíta sa koncový offset.

Použitie:

 bash /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/run.sh [--show-filtered]

Nepovinný parameter --show-filtered spôsobí, že sa odfiltrované mená zapíšu do súboru.

Príklad použitia:

 bash /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/run.sh < /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/test_data/test.txt

Výstup vyššie uvedeného príkladu:

 0	26	39	Nathaniel Hill
 0	41	54	Nathaniel Hill
 1	202	224	Joseph Malachy Kavanagh
 1	226	248	Joseph Malachy Kavanagh
 0	328	341	Walter Osborne
 0	347	360	Nathaniel Hill
 0	539	552	Edward McGuire
 0	554	567	Edward McGuire

Formát výstupu:

 1. stĺpec - Typ mena podľa spôsob, akým bolo meno v texte nájdené (0 - všetky mená boli nájdené nástrojom figa, 1 - mená, v ktorých bola časť nájdená zhodou a časť doplnená skriptom).
 2. stĺpec - Začiatočný offset
 3. stĺpec - Koncový offset
 4. stĺpec - Meno

Zoznam získaných mien môže obsahovať aj nevalidné mená (napr. Post Office) alebo mená, ktoré sú podreťazce iných nájdených mien. Toto je spôsobené tým, že pre zvýšenie počtu získaných mien sa nekontroluje, či priezvisko je obsiahnuté v zozname surnames.txt. Spôsob akým bolo meno nájdené indikuje prvý stĺpec výsledkov, možné značenia sú:

 0 - všetky mená boli nájdené nástrojom figa
 1 - mená, v ktorých bola časť nájdená zhodou a časť doplnená skriptom
 4 - mená vzniknuté spojením mien typu 0 a 1
 7 - mená, ktorých priezvisková časť nebola nájdená v surnames.txt
 8 - mená, ktoré sú podreťazcom iného nájdeného mena

Mená označené číslom 4 vznikajú spojením mien typu 0 a 1. Najprv sa zistí, ktoré zo spájaných mien má nižší start offset, potom sa z tohoto mena vezmú všetky slová, ktoré sú doplnené o slová z druhého mena (len také, ktoré sa vo výslednom mene ešte nevyskytujú). Nakoniec sú prepočítané offsety a prvé meno je nahradené novým a druhé odstránené.

Skript je schopný sa naučiť nové slová z mien typu 1 (popis viď. odsek vyššie). Takto naučené slová sú uložené do:

 /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/outputs/learned.txt

U týchto slov nemožno jednoznačne určiť, či sa jedná o meno alebo priezvisko, preto sú zahrnuté len do všeobecného zoznamu a nie sú v zoznamoch names.txt a surrnames.txt (popis zoznamov je na začiatku kroku).

Mená, ktoré boli odfiltrované z určitého dôvodu sú uložené v:

 /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/outputs/filtered.txt

Uložené sú len výsledky posledného spracovania. Zapisovanie odfiltrovaných mien je potrebné povoliť nepovinným parametrom --show-filtered. Číslo na začiatku riadku značí dôvod odfiltrovania (v zátvorkách uvádzam zoznamy, ktoré zapríčinili odfiltrovanie mena):

 0 - Meno obsahovalo menej ako 2 slová
 1 - Meno obsahovalo názov lokácie (zoznam blist_locations.txt)
 2 - Meno malo na ako prvé slovo slovo, ktoré na tejto pozícii nemôže byť (zoznam notfirst.txt)
 3 - Meno obsahovalo ako prvé slovo slovo, ktoré nie je meno (names.txt)
 4 - Meno obsahovalo ako posledné slovo slovo, ktoré nie je priezvisko (surrnames.txt) [ODSTRÁNENÉ]
 5 - Meno obsahovalo národnosť (nationalities.txt)

5. krok - Zvýraznenie nájdených mien v texte:

Výstupy figy ďalej využíva skript:

 /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/highlight_names.py

Skript vyžaduje výstupy predošlého kroku uložené v súbore figa.out a prijíma text na stdin a na stdout vypisuje text vo formáte HTML s farebne zvýraznenými menami:

 zelené           Mená označené 0 v prvom stĺpci výstupov figy, t.j. mená nájdené úplnou zhodou s menami v names.txt a surrnames.txt
 červené          Mená označené 1 v prvom stĺpci výstupov figy, t.j. mená, u ktorých bolo aspoň jedno meno doplnené skriptom, tým pádom sa nemusí jednať o validné meno
 modré            Mená, ktoré boli v texte nájdené viackrát ako je ich počet vo výstupoch figy.
 fialové          Koreferencie mien zvýraznených vyššie uvedenými farbami
 limetkové (lime) Mená, ktorých priezvisko sa nenachádza v zozname surrnames.txt
 olivové (olive)  Mená, ktoré sú podreťazcom dlhšieho mena (zeleného, červeného alebo modrého)

Kde prvý stĺpec určuje spôsob akým bolo meno v texte nájdené (viď 4. krok). Mená označené modrou môžu naznačovať chybu pri spracovaní výstupov skriptom process_outputs.py alebo chybu pri vyhľadávaní nástrojom figa.

Použitie:

 python /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/highlight_names.py

Príklad použitia:

 bash /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/run.sh < /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/test_data/test.txt > figa.out
 python /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/highlight_names.py < /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/test_data/test.txt > outputs/examples/example.html

Súbor s ukážkovým výstupom je uložený v:

 /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/outputs/example.html

Výsledky

Mená rozpoznané nástrojom v testovacích textoch:

 Richard Moynan
 Mary Magdalene
 Jack B.
 Lawrence J.

13.2 Obalovací skript

Pre využitie NameRecognizeru v iných skriptoch je pripravený obalovací skript name_recognizer.py, ktorý sprístupňuje funkcionalitu skriptov process_outputs.py a highlight_names.py pomocou dvoch funkcií - process(text) a highlight(text, vystup_fce_process), ktoré vracajú spracované výstupy nástroja figa alebo text so zvýraznenými menami.

Pred použitím treba instancovať triedu NameRecognizer s dvoma povinnými parametrami konštruktoru - cesta k spustiteľnému súboru figa (figav08) a cesta ku konečnému automatu (*.fsa).

Na vyskúšanie funkcionality možno skript spustiť, ako vstupný text je použitý :

 /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/test_data/example_input.txt

výstup je vypísaný na stdout:

 python /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/name_recognizer.py

13.3 Pomocné nástroje

13.3.1 Name Collector

Nástroj, ktorý získava zoznam mien z niekoľkých webových stránok, je umiestnený v:

 /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/name_collector

Štruktúra adresára:

 main.py                  - spúšťací skript nástoja
 base.py                  - definuje triedu, z ktorej dedia triedy zdrojov (webov), ktoré majú dopredu známy počet stránok
 base_pagination.py       - definuje triedu, z ktorej dedia triedy zdrojov (webov), ktoré používajú stránkovanie (t.j. majú tlačítko "next")
 rsrc_*_base.py           - triedy, ktoré definujú spoločné rozhranie pre určité zdroje
 rsrc_*.py                - triedy zdrojov
 outputs/names.txt        - abecedne zoradený zoznam získaných mien
 outputs/surrnames.txt    - abecedne zoradený zoznam získaných priezvisk
 outputs/all_raw.txt      - abecedne zoradený zoznam získaných mien a prizevisk
 outputs/all.txt          - súbor all_raw.txt upravený do formátu vhodného pre nástroj figa
 outputs/name/*.txt       - výstupy zdrojov s menami
 outputs/surrname/*.txt   - výstupy zdrojov s priezviskami

Weby implementované ako zdroje:

 http://german.about.com/library/blname_Girls.htm
 http://german.about.com/library/blname_Boys.htm
 http://babynames.net
 http://surname.sofeminine.co.uk/w/surnames/most-common-surnames-in-great-britain.html
 http://www.surnamedb.com/Surname
 http://en.wikipedia.org/wiki/Old_Frisian_given_names
 http://en.wikipedia.org/wiki/List_of_biblical_names
 http://en.wikipedia.org/wiki/Slavic_names
 http://genealogy.familyeducation.com/browse/origin/

Použitie:

 python /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/name_collector/main.py

Skript sa automaticky spúšťa pri použití skriptu run.sh v pomocnom nástroji KB List.

13.3.2 KB List

Nástroj na extrakciu mien z KB.all, výsledky zlučuje s výsledkami z Name Collectoru, je umiestnený v:

 /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/kb_list

Kompletné spracovanie, zlúčenie a kategorizácia dát na mená a priezviská sa vykonáva pomocou run.sh.

Použitie:

 bash /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/kb_list/run.sh

13.3.3 KB Locations

Nástroj, ktorý vytvára zoznam lokácií použitý pri filtrovaní výstupov figy. Výsledkom skriptu je zoznam:

 data/lists/blist_locations.txt

Skript je umiestnený v:

 /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/kb_locations

a spúšťa sa pomocou:

 bash /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/kb_locations/run.sh

13.3.4 SWN

Skript, ktorý v KB.all. vyhľadá všetky jednoslovné mená. Skript je umiestnený v priečinku:

 /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts

Spúšťa sa pomocou:

 python /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/swn.py

Výstupom skriptu sú jednoslovné mená spolu s informáciami o výskyte v KB.all. Na prvom riadku sa nachádza verzia KB.all. Formát druhého a ostatných nasledovných riadkov je nasledovný:

 1. stĺpec - číslo riadku KB.all, na ktorom bolo meno nájdené
 2. stĺpec - ID osoby v KB.all
 3. stĺpec - meno

13.4 Ukážkové výstupy

Ukážkové výstupy skriptov process_outputs.py (súbory s príponou .out), highlight_names.py (súbory s príponou .html) a swn.py (swn.txt) sú uložené v:

 /mnt/minerva1/nlp/projects/decipher_ner/xklima22/scripts/outputs/examples/

14 Integrace projektu Ner4

Cílem projektu je kompletní nahrazení FSA automatů v projektu FIGA za CEDAR (implemented in project Ner4).

Tento projekt má vlastní větev na gitu NER-figa_cedar.

V následujících kapitolách budou stručně popsány změny provedené při migraci fsa figa na cedar figa.

14.1 NER

Pro projekt Ner se skripty většinou pouze mírně aktualizovaly, aby využívaly/podporovaly novou verzi Figy.

Ponechány následující soubory, přestože ani ve staré verzi nebyly využívány:

 NER/figa/sources/kb_loader_fast.cc
 NER/figa/sources/kb_loader_slow.cc

Aktualizovány skripty, aby využívaly novou verzi figy:

 NER/start.sh
 NER/uploadKB.sh
 NER/deleteKB.sh
 NER/ner.py

14.2 FIGA

V projektu Figa byly provedeny velké změny. Nejdůležitější je náhrada FSA automatů za CEDAR tries. Byla snaha novou Figa co nejméně modifikovat - většinou byly jen opraveny triviální bugy. Pro potřeby nové figy bylo mírně upraveno rozhraní Figa (c++) <-> Ner (python). Nová automaty Figy zabírají mnohem více místa na disku, ale jejich zpracování je rychlejší (viz stránka nové Figa).

Nástroje FSA byly z repozitáře odstraněny
Odstraněn automat pro spellchecking - nová figa nevyžaduje (nová Figa nemá spellchecking plně doimplementovaný)
Odstraněn převod ASCII reprezentace čísel na binární - knihovna cedar umí dělat interně, tudíž není třeba (rovněž byl odstraněn skript str2bin)
create_fsa[_autocomplete].sh přepsán a upraven na create_cedar[_autocomplete].sh
kompatibilní vstup a výstup se starou figou
mírně upraveno rozhraní SWIG
aktualizován skript autocomplete.py

14.3 Výkonnostní srovnání (FIGA)

Následuje srovnání nároků na prostředky tvorby a vyhledávání v automatech jednotlivých knihoven. Všechny testy probíhaly na serveru athena1.

Pro tvorbu namelistů byly použity Knowledge Base z projektu Ner: KB.all (5400067 entit) a jeho menší verze KB.11 (490915 entit - obsahuje každý 11. řádek z KB.all).

Pro vyhledávání entit byly použity vstupní texty example_input2 (3693 slov) a testing_data.txt (17931 slov).

Tvorba automatu (FSA) a slovníku (CEDAR/DARTS). Předpokládá se již připravený namelist, měří se tedy jen čas generování samotného automatu pomocí figav1.0/fsa_build (nikoliv celý proces create_[cedar|fsa].sh):

	Čas	Čas	Čas	Využití paměti	Využití paměti	Využití paměti	Velikost automatu	Velikost automatu	Velikost automatu
	FSA	CEDAR	DARTS	FSA	CEDAR	DARTS	FSA	CEDAR	DARTS
KB.11	56s	31s	30s	2.4 GB	331,1 MB	251,1 MB	24,3 MB	98,4 MB	31,3 MB
KB.all	115m	4m 46s	4m 50s	8,8 GB	2,8 GB	2,9 GB	237,1 MB	921,1 MB	334,3 MB

Tvorba automatu pro spellcheck (FSA), pro CEDAR a DARTS není speciální slovník potřeba:

	Čas	Využití paměti	Velikost automatu
KB.11	12s	329,4 MB	11,6 MB
KB.all	3m 42s	4,0 GB	90,8 MB

Vyhledávání ve vytvořených automatech/slovnících:

		Čas	Čas	Čas	Využití paměti	Využití paměti	Využití paměti
		FSA	CEDAR	DARTS	FSA	CEDAR	DARTS
KB.11	example_input2	0,11s	0,49s	0,16s	36,8 MB	110,9 MB	43,9 MB
KB.11	testing_data.txt	0,15s	0,51s	0,18s	36,8 MB	110,9 MB	43,9 MB
KB.all	example_input2	1,21s	4,74s	1,89s	249,7 MB	933,7 MB	346,8 MB
KB.all	testing_data.txt	1,27s	4,84s	1,93s	249,7 MB	933,7 MB	346,8 MB

Vyhledávání se zapnutým spellcheckem ve vytvořených automatech/slovnících:

		Čas	Čas	Čas	Využití paměti	Využití paměti	Využití paměti
		FSA	CEDAR	DARTS	FSA	CEDAR	DARTS
KB.11	example_input2	0,12s	4,3s	3,4s	48,4 MB	110,9 MB	43,8 MB
KB.11	testing_data.txt	0,17s	20,8s	17,1s	48,5 MB	110,9 MB	43,8 MB
KB.all	example_input2	1,64s	23,5s	17,3s	340,5 MB	934,1 MB	347,9 MB
KB.all	testing_data.txt	1,67s	2m 26s	2m	340,5 MB	934,8 MB	347,3 MB

Závěr

DAR a DARTS knihovny vytvoří automat oproti FSA mnohem rychleji, navíc s mnohem menším požadavkem na paměť (pro tvorbu některých opravdu velkých namelistů z projektu Wikify ani nestačila paměť serveru athena1, navíc se ani na athena3 nepodařilo vytvořit FSA slovník bez chyby). CEDAR ani DARTS dále nepotřebují speciální automaty pro spellchecking. Naproti tomu vytvořený FSA automat zabírá na disku méně místa na disku a vyhledávání v něm probíhá mnohem rychleji.

15 Porovnávání změn ve dvou různých KB

Pro porovnávání změn, entit s wikipedia linkem, různých verzí KB je vytvořen skript secapi/NER/KB_changes_comparator.py ve větvi "wikipedia_update".

Povinné argumenty:

oldKB_path - cesta ke staré KB
newKB_path - cesta k nové KB

Nepovinné argumenty:

-h --help - vypíše nápovědu a skončí
-w --word - pokud nastaveno, změny budou zobrazeny v kontextu celých slov, ne jen jejich částí
-e CATEGORY --exclude CATEGORY - vyřezení kategorií z porovnání. Použití: --exclude "ALIAS,DATE OF DEATH" a z výstupu budou vyřezeny kategorie ALIAS a DATE OF DEATH. Dá se použít následovně: --exclude WIKI a všechny kategorie s WIKI v názvu budou vyřazeny. Názvy kategorií jsou v souboru HEAD-KB.
-c CATEGORY --category CATEGORY - explicitně nastaví kategorii pro testování. Názvy kategorií jsou v souboru HEAD-KB.

Příklad spuštení:

 python ./KB_changes_comparator.py oldKB.tsv newKB.tsv -w -e "GENDER,NATIONALITY"
 # Porovná oldKB s newKB s tím že bude vypisovat celá slova a bude vynechávat kategorie GENDER a NATIONALITY

 python ./KB_changes_comparator.py oldKB.tsv newKB.tsv -c DESCRIPTION
 # Porovná oldKB s newKB s tím že bude porovnávat pouze kategorii DESCRIPTION

Příklad výstupu s argumentem -w a bez:

 without -w
 4116    4116    DESCRIPTION     http://en.wikipedia.org/wiki/Štepán_Wagner      replace .       ->      er
 
 with -w
 4116    4116    DESCRIPTION     http://en.wikipedia.org/wiki/Štepán_Wagner      replace  jump.  ->       jumper

Struktura výstupu:

 číslo_řádku_v_newKB \t číslo_řádku_v_oldKB \t kategorie_sloupce \t wiki_link \t typ_změny \t původní_hodnota \t -> \t nová_hodnota

Vyjímka v případě nalezení nové entity:

 číslo_rádku \t wiki_link \t new \t obsah řádku entity

Příklad:

 452196	3323492	{e}PLACE OF BIRTH	http://en.wikipedia.org/wiki/Jan_van_der_Heyden	insert		->	Gorinchem (South Holland, Netherlands) (inhabited place)
17641   17641   PLACE OF BIRTH  http://en.wikipedia.org/wiki/African_Spir       replace Elisabethgrad,  ->      Elizabethgrad,
278171  http://en.wikipedia.org/wiki/Erjon_Vucaj        new     p:6fa1cac12f    person  Erjon Vucaj             footballer                      Albania, Shkodër                1990-12-25                      
                      http://en.wikipedia.org/wiki/Erjon_Vucaj        http://www.freebase.com/m/0b__zy7       http://dbpedia.org/page/Erjon_Vucaj

Vygenerované výstupy spuštěné příkazem:

 python KB_changes_comparator.py /mnt/data/kb/1455196205/KB.all /mnt/data/kb/1476090552/KB.all

je možné najít v adresáři:

 /mnt/minerva1/nlp/projects/wikipedia_update/output.out

Doba běhu pro asi 4500000 řádků je asi 5-6 minut. Skript využívá pro získávaní označení sloupců různých druhů entit soubor:

 /mnt/minerva1/nlp/repositories/decipher/secapi/HEAD-KB