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)

Automatizovaný index čitelnosti (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

Slovní bohatství (MATTR - Moving Average Type-Token Ratio)

Poměr lemmat a tokenů, průměrovaný nad okny o 100 slovech. Hodnota v každém okně se vypočítá vzorcem (c), kde V je počet lemmat a N je počet tokenů v daném okně. Viz Cvrček et al. (2020).

(c)      TTR = V / N

Vzdálenost sloves

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

2.2. Gramatická pravidla

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

Knižní styl

Knižní výrazy (např. jenž, jestliže nebo předměty ve 2. pádu). Viz Sgall a Panevová (2014, s. 42, 66-69, 79-80).

Nedostatek sloves

Slovesa nesou nejvíc informací o ději a pomáhají text dynamizovat. PONK zvýrazňuje slovesa ve větných celcích, kde je sloveso pouze každé šestnácté slovo (poměr počtu sloves k délce věty je menší než 0.06). Příklad (1) obsahuje celkem 24 slov, ale
pouze jedno sloveso. Poměr je 1/24 ≈ 0,04. Viz Šamánková et al. (2022, s. 37).

(1) 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.

Odkazovací výrazy

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

Opakování pádů

Text s velkými shluky podstatných a přídavných jmen ve stejném pádu může působit nepřehledně. Například v příkladu (2) se 7. pád opakuje 6krát. Doporučujeme zkontrolovat shluky větší než 3 slova. Viz Sgall et al. (2014, s. 88–90).

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

Opisná pasiva

Opisná pasiva (pasivní konstrukce s „být“) se špatně čtou a často zakrývají původce děje. Viz Šváb (2023, s. 27), Šamánková a Kubíková (2022, s. 39-40).

Přemíra negací

Záporné formulace zastírají význam. Doporučujeme revidovat věty s více než 2 negacemi, pokud jsou příliš časté. V příkladu (3) jsou 3 negace a pouze 2 negovatelná slova bez negace. Viz Šamánková et al. (2022, s. 40–41), Šváb (2023, s. 33).

(3) 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řemíra podstatných jmen

Přemíra podstatných jmen snižuje přirozenost a čtivost textu. Podstatná jména často vyjadřují děj, který je vyjádřitelný slovesem. Například věta v příkladu (4) obsahuje 5 podstatných jmen. Viz Sgall et al. (2014, s. 41).

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

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řísudek daleko ve větě

Umístění přísudku (jeho neplnovýznamové složky, pokud je víceslovný) daleko ve větě může narušit plynulost textu. V příkladu (5) je přísudek 6. slovo ve větě. Doporučujeme zkontrolovat přísudky, které jsou ve větě dál než 5 slov. Viz Šamánková et al. (2022, s. 53–54).

(5) 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í.

Relativizující výrazy

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

Roztroušené složené slovesné tvary

Pomocná slova složeného slovesa (pomocná slovesa a příklonky) příliš vzdálené od plnovýznamové složky mohou narušit plynulost textu. V příkladu (6) jsou pomocné sloveso a trpné příčestí 9 slov od sebe. Doporučujeme zkontrolovat tvary, jejichž části jsou od sebe vzdálené více než 5 slov. Viz Šamánková et al. (2022, s. 53–54).

(6) 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.

Slovní vata

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

Utvrzující 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).

Vyprázdněná abstraktní jména

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

Vyprázdněná slova

Sémanticky 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).

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

Podmět vzdálený od přísudku (jeho neplnovýznamové části, pokud je víceslovný) může narušit plynulost textu. V příkladu (7) je
přísudek („nese“) 25 slov od podmětu („žalobce“). Doporučujeme zkontrolovat podměty vzdálené od přísudku víc než 6 slov. Viz Šamánková et al. (2022, s. 53–54), Šváb (2023, s. 21–22).

(7) 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.

Vzdálenost předmětu od řídícího členu

Předmět příliš vzdálený od přísudku (jeho plnovýznamové části, pokud je víceslovný) může narušit plynulost textu. V příkladu (8) je
přísudek od předmětu vzdálený 16 slov. Doporučujeme zkontrolovat předměty vzdálené od svého řídícího členu víc než 6 slov. Viz Šamánková et al. (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.

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.