Logo UK Logo MFF

Institute of Formal and Applied Linguistics


Charles University, Czech Republic
Faculty of Mathematics and Physics

ÚFAL
PONK

Uživatelský manuál PONKu

  1. Spuštění PONKu
  2. Webové rozhraní
  3. Odkazy

Tato sekce popisuje nástroj pro příkazovou řádku. REST API je popsáno na stránce s referencí API.

1. Spuštění PONKu

Nejjednodušší způsob, jak spustit PONK, je poskytnout prostý text jako standardní vstup a získat výsledek ve formátu HTML na standardní výstup. 

./ponk.pl --stdin

Předpokládá se, že vstup je v kódování UTF-8 a může se jednat buď o prostý text nebo (s přepínačem --input-format md) text ve formátu MarkDown.

Následující příkaz spustí PONK se vstupním souborem ve formátu MarkDown; výsledek ve formátu CoNLL-U půjde na standardní výstup. 

./ponk.pl --input-file [název_vstupního_souboru] --input-format md --output-format conllu

Vstupní soubor může být ve formátu MS Word DOCX, jako v následujícím příkladu; v takovém případě je interně převeden na MarkDown (pomocí lokálně nainstalovaného Pandoc) a zpracován jako takový. V tomto příkladu navíc nastavujeme výstupní formát na HTML a úroveň logování na 0, tj. plné logování. 

./ponk.pl --input-file ../data/pokus.docx --input-format docx --output-format html --logging-level 0

Výsledek ve zvoleném výstupním formátu je vždy odeslán na standardní výstup; pro účely logování lze navíc výsledek uložit do souboru. Následující příkaz pošle výsledek v HTML na standardní výstup a zároveň uloží výsledek ve formátu CoNLL-U do souboru. 

./ponk.pl --input-file [název_vstupního_souboru] --output-format html --store-format conllu

Úplná syntaxe příkazu pro spuštění PONKu 

Použití: ponk.pl [možnosti]
možnosti: -i|--input-file [název vstupního textového souboru]
         -si|--stdin (vstupní text poskytnutý přes stdin)
         -if|--input-format [vstupní formát: txt (výchozí), md, docx]
         -of|--output-format [výstupní formát: html (výchozí), conllu]
         -os|--output-statistics (přidat statistiky PONK k výstupu; pokud je uvedeno, výstup je JSON se dvěma položkami: data (ve výstupním formátu) a statistiky (v HTML))
        -uil|--ui-language [jazyk: lokalizovat odpověď, kdekoliv je to možné, do zadaného jazyka: en (výchozí), cs]
         -sf|--store-format [formát: uložit výstup v zadaném formátu: html, conllu]
         -ss|--store-statistics (uložit statistiky do souboru HTML)
         -ap|--apps [čárkou dělený seznam interních aplikací k volání, možné hodnoty: app1 (výchozí), app2]
         -ll|--logging-level (přepsat výchozí (anonymní) úroveň protokolování (0=plné, 1=omezené, 2=anonymní))
          -v|--version (vytiskne verzi programu a skončí)
          -n|--info (vytiskne verzi programu a podporované funkce jako JSON a skončí)
          -h|--help (vytiskne krátkou nápovědu a skončí)

1.1. Vstupní formáty

Vstupní formát lze specifikovat pomocí možnosti --input-format. Aktuálně podporované vstupní formáty jsou:

  • txt (výchozí): vstup je prostý text
  • md: vstup je text ve formátu MarkDown
  • docx: vstup je soubor MS Word DOCX

1.2. Výstupní formáty

Výstupní formát je specifikován pomocí možnosti --output-format. Aktuálně podporované výstupní formáty jsou:

  • html: výstup v HTML
  • txt: výstup v prostém textu (zatím neimplementováno)
  • md: výstup ve formátu MarkDown (zatím neimplementováno)
  • conllu: formát CoNLL-U - není dostupný přes API (a zatím neimplementováno)

2. Webové rozhraní

2.1. Celkové míry

Aktivita

Vyjadřuje míru akčnosti v textu. Vypočítá se vzorcem (a), kde V je počet sloves a A je počet přídavných jmen. Viz Cvrček et al. (2020).

(a)      Q = V / (V + A)

ARI (Automated Readability Index)

Měří čitelnost v rocích vzdělání potřebných k porozumění textu. Vypočítá se vzorcem (b). Viz Senter a Smith (1967), Bendová a Cinková (2021) pro českou adaptaci.

(b)       ARI = 3.666 * počet znaků / počet tokenů + 0.631 * počet tokenů / počet vět - 19,491

TTR – klouzavý průměr

Klouzavý průměr poměru typu a tokenu, průměrovaný přes okna o 100 slovech, vypočítaný vzorcem (c), kde V je velikost slovní zásoby a N je počet tokenů. Měřeno na lemmatech. Viz Cvrček et al. (2020).

(c)      TTR = V / N

Vzdálenost sloves

Průměrná vzdálenost mezi slovesy.

2.2. Gramatická pravidla

Anaforické odkazy

Vyhýbejte se vágním anaforickým odkazům (např. „co se týče výše uvedeného“). Viz Šamánková a Kubíková (2022, s. 42).

Opakování pádů

Shluky podstatných jmen a přídavných jmen ve stejném pádu mohou znepřehlednit text. Například v příkladu (1) se instrumentál opakuje 6krát. Doporučujeme revidovat shluky delší než 3 slova, pokud je to možné. Čárky, předložky a spojky se nepočítají. Viz Sgall a Panevová (2014, s. 88-90).

(1) Některé druhy řas se dovedou v úrodných vodách v horních vrstvách rozmnožit v ohromném množství.

Potvrzovací výrazy

Extrémní výrazy, které zbytečně potvrzují již předpokládanou jistotu autora (např. „jednoznačně“, „jasně“, „nepochybně“). Viz Šamánková a Kubíková (2022, s. 42).

Vzdálenost mezi objektem a řídícím slovem

Objekt vzdálený od přísudku (jeho lexikální složky, pokud je složený) může narušit plynulost textu. V příkladu (2) je přísudek 19 tokenů od objektu (včetně interpunkce). Doporučujeme revidovat vzdálenosti větší než 4 slova, pokud je to možné. Viz Šamánková a Kubíková (2022, s. 53-54).

(2) Dne 5. 2. 2022 jste podal proti rozhodnutí, kterým jsme Vám nepřiznali starobní důchod, protože jste nezískal potřebnou dobu důchodového pojištění, námitky a přiložil jste aktuální lékařské posudky.

Vzdálenost mezi přísudkem a podmětem

Podmět vzdálený od přísudku (jeho gramatické složky, pokud je složený) může narušit plynulost textu. V příkladu (3) je přísudek („nese“) 27 tokenů od podmětu („žalobce“), včetně interpunkce. Doporučujeme revidovat vzdálenosti větší než 5 slov, pokud je to možné. Viz Šamánková a Kubíková (2022, s. 53-54), Šváb (2023, s. 21-22).

(3) Podle rozhodnutí nese nepříznivé následky toho, že se nepodařilo doložit listinu prokazující jednoznačně existenci právního titulu, na jehož základě by některému z dědiců svědčila práva k dílu, žalobce.

Literární styl

Výrazy spojené s literárním stylem (např. „jenž“, „jestliže“, genitivní objekty). Viz Sgall a Panevová (2014, s. 42, 66-69, 79-80).

Dlouhé výrazy

Výrazy, které lze zkrátit (např. „v důsledku toho“ → „proto“, „týkající se“ → „o“, „prostřednictvím kterého“ → „kterým“). Viz Šamánková a Kubíková (2022, s. 44), Šváb (2023, s. 118).

Participiální pasiva

Počet pasivních konstrukcí s „být“. Viz Šváb (2023, s. 27), Šamánková a Kubíková (2022, s. 38-40).

Přísudek daleko ve větě

Umístění přísudku (jeho finitní složky, pokud je složený) daleko v klauzi může narušit plynulost textu. V příkladu (4) je přísudek 6. tokenem ve větě. Doporučujeme revidovat věty, kde je přídudek dále než 5 slov od začátku. Viz Šamánková a Kubíková (2022, s. 53-54).

(4) Již od roku 2001 ochránce chrání osoby před nezákonným či jinak nesprávným jednáním nebo nečinností správních úřadů a dalších institucí.

Nadbytečné výrazy

Výrazy, které nejsou potřeba k předání informace (např. „je nutné zdůraznit“). Viz Šamánková a Kubíková (2022, s. 42-43).

Relativistické výrazy

Relativistické výrazy (např. „poněkud“, „jeví se“, „patrně“). Viz Šamánková a Kubíková (2022, s. 42).

Rozptýlené složené slovesné tvary

Pomocná slova složeného slovesa (pomocná slovesa a klitiky) vzdálené od lexikální složky mohou narušit plynulost textu. V příkladu (5) jsou pomocné sloveso a příčestí pasivní 9 slov od sebe. Doporučujeme revidovat tvary, kde jsou části vzdáleny více než 4 slova. Viz Šamánková a Kubíková (2022, s. 53-54).

(5) Daný objekt není dle zveřejněných informací na webových stránkách NPÚ dlouhodobě využíván a vinou neprováděné údržby dochází k degradaci autentických stavebních konstrukcí a prvků stavební výbavy.

Příliš málo sloves

Slovesa přinášejí informace o ději a dynamizují text. Označíme věty, kde je pouze každé 16. slovo sloveso (průměrný poměr sloves k délce věty je méně než 0,06). V příkladu (6) je jedno sloveso a celkem 24 slov, tedy poměr 1/24≈0,04. Viz Šamánková a Kubíková (2022, s. 37).

(6) Vzhledem k četnosti opakování rozhodování o žádostech o rekvalifikaci mimo správní řízení pokládá Úřad práce za vhodné usměrnění a sjednocení praxe vydáním vnitřního předpisu.

Příliš dlouhé věty

Dlouhé věty jsou obtížné na zapamatování. Doporučujeme revidovat věty delší než 22 slov. Viz Šamánková a Kubíková (2022, s. 51), Šváb (2023, s. 17-18).

Příliš mnoho negací

Negativní formulace zastírají význam. Doporučujeme revidovat věty s více než 2 negacemi, pokud se opakují. V příkladu (7) jsou 3 negace a pouze 2 negovatelná slova bez negace. Viz Šamánková a Kubíková (2022, s. 40-41), Šváb (2023, s. 33).

(7) V této situaci není dodatečné povolení stavby krokem, který by nepovolenou stavbu nevyřešil, ale krokem, který nepřinese urovnání sousedského sporu.

Příliš mnoho nominálních konstrukcí

Průměrný počet podstatných jmen v klauzi. Například věta v příkladu (8) obsahuje 5 podstatných jmen. Viz Sgall a Panevová (2014, s. 41).

(8) Otázku zavinění pak nelze směšovat s otázkou porušení povinnosti.

Abstraktní podstatná jména se slabým významem

Sémanticky slabá abstraktní podstatná jména (např. „základ“, „situace“, „úvaha“). Viz Šamánková a Kubíková (2022, s. 41).

Slova se slabým významem

Semanticky slabá slova (např. „zaměřit“, „postup“, „velmi“). Viz Šamánková a Kubíková (2022, s. 37-38, 39), Sgall a Panevová (2014, s. 86), Šváb (2023, s. 32).

2.3. Lexikální překvapení

Pro výpočet lexikálního překvapení je použit model GPT2-Czech-XL.

Úroveň lexikálního překvapení je spočítána pro každý textový token (tokenem zde myslíme řetězec písmen často kratší než slovo) podle jeho pravděpodobnosti v daném kontextu relativně vzhledem k ostatním možným tokenům. Pravděpodobnosti jednotlivých tokenů jsou násobeny a výsledná hodnota je přiřazena celému slovu.

Nástroj barevně rozlišuje 16 úrovní lexikálního překvapení.

Detaily k implementaci: https://github.com/ufal/glitter/.

Vysoká míra lexikálního překvapení

Slova jsou obarvena do žluta, oranžova až červena.
Slova vyhodnocena jako vysoce překvapivá označují buď náhlou změnu kontextu nebo pro kontext nečekaný a pravděpodobně těžko srozumitelný výraz.

Střední míra lexikálního překvapení

Slova jsou obarvena do světle modra, tyrkysova až zelena.
Slova vyhodnocena jako středně překvapivá označují mírnou změnu kontextu a často označují výrazy, které jsou hlavními nositeli informace v textu.

Nízka míra lexikálního překvapení

Slova jsou obarvena do tmavě modra až fialova.
Slova s nízkou mírou překvapivosti často označují pokračování ustálených spojení a delší pasáže mohou poukazovat na nadbytečnosti v textu.

3. Odkazy

Bendová, K., & Cinková, S. (2021). Adaptation of Classic Readability Metrics to Czech. 24th International Conference on Text, Speech and Dialogue, 159–171. https://doi.org/10.1007/978-3-030-83527-9_14

Chromý, J., & Ceháková, M. (2023). Diversity of garden-path structures - SPR. https://doi.org/10.17605/OSF.IO/KSTPE

Coleman, M., & Liau, T. L. (1975). A computer readability formula designed for machine scoring. Journal of Applied Psychology, 60(2), 283–284. https://doi.org/10.1037/h0076540

Cvrček, V., Čech, R., & Kubát, M. (2020). QuitaUp – a tool for quantitative stylometric analysis. https://korpus.cz/quitaup/

Flesch, R. (1948). A new readability yardstick. Journal of Applied Psychology, 32(3), 221–233. https://doi.org/10.1037/h0057532

Gunning, R. (1952). The technique of clear writing. McGraw-Hill.

Hladká, B., Cinková, S., Kuk, M., Mírovský, J., Novotná, T., & Zahálková, K. N. (2024). KUK 1.0. https://ufal.mff.cuni.cz/grants/ponk/kuk1.0. https://lindat.mff.cuni.cz/repository/xmlui/handle/11234/1-5821

Kincaid, J. P., Fishburne Jr, R. P., Rogers, R. L., & Chissom, B. S. (1975). Derivation of new readability formulas (automated readability index, fog count and flesch reading ease formula) for navy enlisted personnel (tech. rep.). Institute for Simulation and Training, University of Central Florida.

McLaughlin, G. H. (1969). SMOG grading – a new readability formula. Journal of Reading, 12(8), 639–646.

Novotná, T., & Harašta, J. (2019). Czech Court Decisions Corpus (CzCDC 1.0). https://lindat.mff.cuni.cz/repository/xmlui/handle/11372/LRT-3052

Šamánková, J., & Kubíková, B. (Eds.). (2022). Jak psát srozumitelné úřední texty: Příručka srozumitelného psaní pro úředníky. Kancelář veřejného ochránce práv. https://www.ochrance.cz/uploads-import/ESO/p%C5%99%C3%ADru%C4%8Dka/Priru...

Senter, R., & Smith, E. A. (1967). Automated readability index (tech. rep.). AMRL-TR. Aerospace Medical Research Laboratories (U.S.)

Sgall, P., & Panevová, J. (2014). Jak psát a jak nepsat česky (2nd ed.). Nakladatelství Karolinum.

Šváb, J. (2023). Jak psát, aby se to dalo číst: Příručka přístupného psaní (2nd ed.). Leges.