{"id":1196,"date":"2026-05-20T10:07:57","date_gmt":"2026-05-20T08:07:57","guid":{"rendered":"https:\/\/openscience.bc.cas.cz\/?page_id=1196"},"modified":"2026-09-03T08:53:46","modified_gmt":"2026-09-03T06:53:46","slug":"soubor-readme","status":"publish","type":"page","link":"https:\/\/openscience.bc.cas.cz\/en\/fair-data\/soubor-readme\/","title":{"rendered":"README file"},"content":{"rendered":"\n
\"\"<\/span>
\n
\n
\n
\n

<\/span><\/mark><\/a>Biologick\u00e9 Centrum AV \u010cR, v.v.i.<\/span><\/mark><\/a><\/strong><\/strong><\/strong><\/strong><\/p>\n\n\n\n

Gener\u00e1tor souboru README<\/h2>\n\n\n\n

README je stru\u010dn\u00fd, ale z\u00e1sadn\u00ed \u201epr\u016fvodce datasetem\u201c. Popisuje, co data obsahuj\u00ed, jak vznikla, jak jsou soubory uspo\u0159\u00e1dan\u00e9, jak\u00e9 jsou prom\u011bnn\u00e9\/jednotky a jak data spr\u00e1vn\u011b interpretovat. Jeho \u00fa\u010delem je, aby bylo snadn\u00e9 dataset pochopit a znovu pou\u017e\u00edt kolegy v t\u00fdmu, extern\u00edmi partnery a v\u011bdeckou komunitou bez s\u00e1hodlouh\u00e9ho vysv\u011btlov\u00e1n\u00ed. Koneckonc\u016f se to m\u016f\u017ee hodit i Tob\u011b, kdyby ses k datasetu vr\u00e1til za n\u011bkolik let.<\/p>\n\n\n\n


README je obvykle textov\u00fd soubor (README.md nebo README.txt), kter\u00fd lze otev\u0159\u00edt v libovoln\u00e9m editoru a kter\u00fd je dlouhodob\u011b udr\u017eiteln\u00fd i bez speci\u00e1ln\u00edho softwaru.<\/p>\n\n\n\n

\n
Zjistit v\u00edce…<\/a><\/div>\n\n\n\n
Gener\u00e1tor README<\/a><\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/main>\n<\/div><\/main>\n\n\n\n
\n

Pro\u010d to m\u00e1 smysl<\/strong><\/mark><\/h2>\n\n\n\n
\n
\n
\n
\n

1) Usnad\u0148uje opakovatelnost a \u0161et\u0159\u00ed \u010das (i v\u00e1m samotn\u00fdm)<\/h2>\n\n\n\n

Bez README mus\u00ed u\u017eivatel\u00e9 dohled\u00e1vat v\u00fdznam zkratek, n\u00e1zv\u016f soubor\u016f, k\u00f3d\u016f, jednotek nebo parametr\u016f anal\u00fdzy v \u010dl\u00e1nc\u00edch \u010di pozn\u00e1mk\u00e1ch. To m\u016f\u017ee trvat hodiny a\u017e dny. N\u011bkdy m\u016f\u017ee b\u00fdt samotn\u00fd dataset \u00fapln\u011b nepou\u017eiteln\u00fd.<\/p>\n\n\n\n

README zachyt\u00ed \u201etich\u00e9 znalosti\u201c (nastaven\u00ed p\u0159\u00edstroje, kroky zpracov\u00e1n\u00ed, QC, v\u00fdznam sloupc\u016f) pr\u016fb\u011b\u017en\u011b a zamez\u00ed tomu, \u017ee se kl\u00ed\u010dov\u00e9 detaily pro pochopen\u00ed dat i cel\u00e9ho v\u00fdzkumu „ztrat\u00ed v p\u0159ekladu“.<\/p>\n<\/div>\n<\/div>\n\n\n\n

\n
\n

2) Je to rychl\u00e1 cesta k FAIR dat\u016fm (a k lep\u0161\u00ed citovanosti)<\/h2>\n\n\n\n

FAIR principy (a od ledna 2027 tak\u00e9 Z\u00e1kon \u010d. 328\/2025 Sb.) zd\u016fraz\u0148uj\u00ed, \u017ee data maj\u00ed b\u00fdt dohledateln\u00e1, p\u0159\u00edstupn\u00e1, interoperabiln\u00ed a znovupou\u017eiteln\u00e1<\/strong>. Aby data byla skute\u010dn\u011b znovupou\u017eiteln\u00e1, je k tomu pot\u0159eba bohat\u00e1 dokumentace, licence a provenience.<\/p>\n\n\n\n

Dokumentace v podob\u011b README je k tomu ide\u00e1ln\u00ed, proto\u017ee dopl\u0148uje omezen\u00e1 repozit\u00e1\u0159ov\u00e1 metadata o praktick\u00e9 instrukce a nezbytn\u00e9 informace.<\/p>\n<\/div>\n<\/div>\n\n\n\n

\n
\n

3) Zvy\u0161uje \u0161anci na hladk\u00e9 ulo\u017een\u00ed dat do repozit\u00e1\u0159\u016f<\/h2>\n\n\n\n

\u0158ada repozit\u00e1\u0159\u016f i datov\u00fdch kur\u00e1tor\u016f o\u010dek\u00e1v\u00e1, \u017ee dataset bude m\u00edt popsan\u00fd obsah, strukturu soubor\u016f, prom\u011bnn\u00e9 a pravidla pou\u017eit\u00ed. README urychl\u00ed publikaci a sn\u00ed\u017e\u00ed po\u010det dotaz\u016f p\u0159i kur\u00e1torsk\u00e9 kontrole.<\/p>\n\n\n\n

Pro znovupou\u017eit\u00ed dat je kl\u00ed\u010dov\u00e9 uv\u00e9st nejen \u201ehotov\u00e9 tabulky\u201c, ale i informace o tom, jak vznikly. K tomu \u010dasto nesta\u010d\u00ed samotn\u00e1 publikace. Nato\u017e, aby data mohla b\u00fdt pou\u017eita i pro jin\u00fd \u00fa\u010del, ne\u017e je replikace publikovan\u00e9ho v\u00fdzkumu.<\/p>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n\n\n\n

\n

Kdy, kam, pro\u010d<\/strong><\/mark><\/h2>\n\n\n\n
\n
\n
\n

Kdy README vytv\u00e1\u0159et<\/h2>\n\n\n\n

Nejlep\u0161\u00ed praxe je p\u0159ipravit soubor README u\u017e na za\u010d\u00e1tku projektu\/v\u00fdzkumu a pr\u016fb\u011b\u017en\u011b ho aktualizovat. Pozd\u011bji se d\u016fle\u017eit\u00e9 detaily snadno zapomenou. A kdy\u017e u\u017e to nech\u00e1\u0161 nakonec, vytvo\u0159it bys ho m\u011bl nejpozd\u011bji p\u0159ed t\u00edm, ne\u017e bude\u0161 datasety zve\u0159ej\u0148ovat, nebo je vykazovat jako v\u00fdsledek typu T.<\/p>\n\n\n\n

README se typicky dopl\u0148uje p\u0159i ka\u017ed\u00e9 v\u00fdznamn\u00e9 zm\u011bn\u011b: nov\u00e9 verze soubor\u016f, \u00faprava prom\u011bnn\u00fdch, zm\u011bna pipeline, dopln\u011bn\u00ed QC, nebo publikace nov\u00e9 verze datasetu.<\/p>\n<\/div>\n<\/div>\n\n\n\n

\n
\n

Kam README ukl\u00e1dat<\/h2>\n\n\n\n

README m\u00e1 b\u00fdt ulo\u017een p\u0159\u00edmo spolu s daty, aby se „neztratil“. Soubor README by m\u011bl b\u00fdt jeden z prvn\u00edch, kter\u00fd u\u017eivatel u datasetu uvid\u00ed. Nejjednodu\u0161\u0161\u00ed je ulo\u017eit ho p\u0159\u00edmo do ko\u0159enov\u00e9ho adres\u00e1\u0159e datasetu\/projektu (root folder). Pokud m\u00e1\u0161 v\u00edce soubor\u016f README (nap\u0159. pro logick\u00e9 ucelen\u00e9 skupiny soubor\u016f), ulo\u017e ka\u017ed\u00fd README do dan\u00e9ho adres\u00e1\u0159e.<\/p>\n\n\n\n

Obecn\u011b se doporu\u010duje nazvat README prost\u011b README.md (Markdown) nebo README.txt (prost\u00fd text). Doporu\u010dil bych se p\u00e1r sekund zdr\u017eet a n\u00e1zev p\u0159eci jen tro\u0161ku vyladit. Co t\u0159eba: README_bc_[projectAcronym]_[DataSetName]_[yyyy]. Takov\u00fd n\u00e1zev pom\u016f\u017ee s identifikac\u00ed a p\u0159i\u0159azen\u00edm ke konr\u00e9tn\u00edmu datasetu. Prost\u011b i tento soubor se m\u016f\u017ee zatoulat, jako ka\u017ed\u00fd jin\u00fd.<\/p>\n<\/div>\n<\/div>\n\n\n\n

\n
\n

Pro\u010d README nesta\u010d\u00ed nahradit metadaty v repozit\u00e1\u0159i<\/h2>\n\n\n\n

Repozit\u00e1\u0159ov\u00e1 metadata jsou skv\u011bl\u00e1 pro indexov\u00e1n\u00ed a vyhled\u00e1v\u00e1n\u00ed dat. Je to podobn\u00e9, jako bibliografick\u00fd z\u00e1znam u knihy. Ale README slou\u017e\u00ed \u00fapln\u011b k n\u011b\u010demu jin\u00e9mu. D\u00edky n\u011bmu jsou data op\u011btovn\u00e9 pou\u017eiteln\u00e1 a tzv. interoperabiln\u00ed. Kdy\u017e n\u011bkdo dohled\u00e1 data d\u00edky metadat\u016fm a st\u00e1hne si je, aby s nimi mohl d\u00e1l pracovat, README jde s nimi a po\u0159\u00e1d vysv\u011btluje kontext a pou\u017eit\u00ed.<\/p>\n\n\n\n

Proto je kl\u00ed\u010dov\u00e9 m\u00edt oboj\u00ed: d\u016fsledn\u011b vypln\u011bn\u00e1 metadata v repozit\u00e1\u0159i a sou\u010dasn\u011b p\u0159ilo\u017een\u00fd README, kter\u00e9 detailn\u011b pop\u00ed\u0161e strukturu soubor\u016f, prom\u011bnn\u00e9, k\u00f3dy, zpracov\u00e1n\u00ed, QC atd.<\/p>\n<\/div>\n<\/div>\n<\/div>\n<\/main>\n\n\n\n

<\/div><\/span>
\n
\n
\n
\n
\n

Co by m\u011bl soubor README obsahovat (doporu\u010den\u00e9 minimum)<\/strong><\/a><\/h2>\n\n\n\n

1. Kdo \/ kontakt:<\/strong> auto\u0159i, instituce, e-mail pro dotazy.<\/p>\n\n\n\n

2. Co to je:<\/strong> kr\u00e1tk\u00fd popis datasetu a \u00fa\u010delu.<\/p>\n\n\n\n

3. Struktura soubor\u016f:<\/strong> seznam soubor\u016f a co je v ka\u017ed\u00e9m z nich, vztahy mezi soubory.<\/p>\n\n\n\n

4. Metody:<\/strong> jak byla data sb\u00edr\u00e1na\/generov\u00e1na a jak byla zpracov\u00e1na z raw do processed (v\u010detn\u011b n\u00e1stroj\u016f a verz\u00ed).<\/p>\n\n\n\n

5. Popis prom\u011bnn\u00fdch:<\/strong> n\u00e1zvy sloupc\u016f, definice, jednotky, k\u00f3dy pro chyb\u011bj\u00edc\u00ed hodnoty, zkratky.<\/p>\n\n\n\n

6. QC a outliery:<\/strong> jak prob\u011bhla kontrola kvality a jak bylo nalo\u017eeno s podez\u0159el\u00fdmi hodnotami.<\/p>\n\n\n\n

7. Licence a citace:<\/strong> jak data pou\u017e\u00edt a jak je citovat.<\/p>\n\n\n\n

<\/a><\/p>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div><\/div>\n\n\n\n

\n

Gener\u00e1tor README pro biologick\u00e1 data<\/h2>\n\n\n\n
\n
\n
\n
\n
\n
1. Jde o funk\u010dn\u00ed, ale p\u0159esto st\u00e1le testovac\u00ed beta verzi.<\/a><\/a><\/summary>\n

Omluv proto, pros\u00edm, drobn\u00e9 nedostatky. Budu r\u00e1d, za p\u0159ipom\u00ednky, abych gener\u00e1tor vyladil. Tak mi je, pros\u00edm, po\u0161li na e-mail: frantisek.vorel@bc.cas.cz<\/span><\/a> \ud83d\ude42<\/p>\n<\/details>\n\n\n\n

2. Vyber typ README podle typu datasetu<\/summary>\n

Nyn\u00ed jich je naprogramov\u00e1no 9. Pokud m\u00e1\u0161 z\u00e1jem o dal\u0161\u00ed, napi\u0161 mi do e-mailu, o jak\u00fd, a ide\u00e1ln\u011b p\u0159idej i\u00a0pole, kter\u00e1 by v nov\u00e9m README nem\u011bla chyb\u011bt. Bohu\u017eel neum\u00edm z\u00e1zraky na po\u010dk\u00e1n\u00ed, p\u00e1r dn\u00ed to potrv\u00e1.<\/p>\n\n\n\n

\u0160ablony m\u016f\u017ee\u0161 pou\u017e\u00edt i pro jin\u00e9 typy dataset\u016f. I tak dost urychl\u00ed a zjednodu\u0161\u00ed pr\u00e1ci.<\/p>\n\n\n\n

1. Vyber ten, kter\u00fd nejv\u00edc odpov\u00edd\u00e1, a vypl\u0148 ho.
2. Vygeneruj hotov\u00fd README.md a st\u00e1hni ho.
3. Dej mu trochu smyslupln\u00fd n\u00e1zev (nap\u0159. bc_README_projectAcronym_Dataset_v10.md).
4. Otev\u0159i v pozn\u00e1mkov\u00e9m bloku.
5. Co nesed\u00ed Tv\u00e9mu c\u00edli, sma\u017e, p\u0159epi\u0161, dopl\u0148.
6. Ulo\u017e.<\/p>\n<\/details>\n\n\n\n

3. P\u0159idej spoluautory<\/summary>\n

M\u016f\u017ee\u0161 vyplnit pouze PI. Zrovna tak m\u016f\u017ee\u0161 vyplnit v\u0161echny spoluautory v\u00fdzkumn\u00fdch dat, ke kter\u00fdm se konkr\u00e9tn\u00ed README file v\u00e1\u017ee. Je to dokonce \u017e\u00e1douc\u00ed. Proto sta\u010d\u00ed kliknout na „Add co-author“.<\/p>\n<\/details>\n\n\n\n

4. Zad\u00e1n\u00ed licence<\/a><\/a><\/summary>\n

Zadej licenci, kter\u00e1 ur\u010d\u00ed, jak\u00fdm zp\u016fsobem m\u016f\u017eou s datasetem nakl\u00e1dat ostatn\u00ed. Nejb\u011b\u017en\u011bj\u0161\u00ed je CC-BY. To umo\u017en\u00ed ostatn\u00edm v\u011bdc\u016fm vyu\u017e\u00edvat v pln\u00e9 \u0161\u00ed\u0159i, ale v\u017edy T\u011b budou muset alespo\u0148 citavat jako autora.<\/p>\n\n\n\n

Pokud se k dat\u016fm v\u00e1\u017eou n\u011bjak\u00e9 restrikce nebo \u010dasov\u00e9 embargo, kdy je nelze voln\u011b pou\u017e\u00edt, pole „Access restrictions \/ ethical restrictions \/ embargo“ je spr\u00e1vn\u00e9 m\u00edsto, kde toto popsat.<\/p>\n<\/details>\n\n\n\n

5. Outliery: pravidla + zach\u00e1zen\u00ed
<\/a><\/a><\/summary>\n

U n\u011bkter\u00fdch typ\u016f dataset\u016f je mo\u017enost vyplnit Outliery.<\/p>\n\n\n\n

Ty mohou b\u00fdt chyba m\u011b\u0159en\u00ed (pipetace, bublina, saturace, \u0161patn\u00e1 jamka, drift p\u0159\u00edstroje) nebo skute\u010dn\u00fd biologick\u00fd jev. Bez popisu pravidla to nikdo nepozn\u00e1.<\/p>\n\n\n\n

Transparentn\u00ed popis outlier\u016f a QC je sou\u010d\u00e1st\u00ed dobr\u00e9 dokumentace dat (v\u010detn\u011b definic k\u00f3d\u016f\/flag\u016f pro n\u00edzkou kvalitu a outliery).<\/p>\n\n\n\n

Doporu\u010den\u00fd obsah toho pole<\/strong><\/p>\n\n\n\n

1.\u00darove\u0148: technick\u00e9 repliky \/ biologick\u00e9 repliky \/ cel\u00e9 s\u00e9rie \/ cel\u00fd soubor.<\/p>\n\n\n\n

2. Detekce: nap\u0159. \u201eIQR > 1.5\u00d7\u201c, \u201e>3\u00d7MAD\u201c, \u201ez-score > 3\u201c, \u201eflag p\u0159\u00edstroje\u201c, \u201emimo rozsah kalibra\u010dn\u00ed k\u0159ivky\u201c<\/p>\n\n\n\n

3. Zach\u00e1zen\u00ed: odstran\u00edm \/ ozna\u010d\u00edm \/ nastav\u00edm NA \/ opakuji m\u011b\u0159en\u00ed<\/p>\n\n\n\n

4. Evidence: nap\u0159. sloupec qc_flag<\/code>, outlier_reason<\/code>, log v changelog<\/code>, ponech\u00e1n\u00ed raw dat beze zm\u011bny<\/p>\n\n\n\n

P\u0159.<\/p>\n\n\n\n

Outlier detection rule:<\/em> \u201eWithin technical replicas, we mark an outlier if it differs from the median of technical replicas by >3\u00d7MAD.\u201d<\/p>\n\n\n\n

Outlier handling:<\/em> \u201eI discard the outlier well and calculate the aggregation (median) from the others. If <2 technical replicates remain, I set the value to NA and repeat the measurement.“<\/p>\n<\/details>\n<\/div>\n\n\n\n

\n
6. Data-specific information<\/a><\/summary>\n

Data-specific information je \u010d\u00e1st README souboru, kam se zapisuj\u00ed, jak n\u00e1zev napov\u00edd\u00e1, hodn\u011b specifick\u00e9 informace. Nav\u00edc tato \u010d\u00e1st nemus\u00ed b\u00fdt v README ani jednou, nebo se m\u016f\u017ee opakovat mnohokr\u00e1t (ke ka\u017ed\u00e9mu souboru, tabulce, datasetu atd.). Z\u00e1le\u017e\u00ed na okolnostech a obsahu datasetu. A poka\u017ed\u00e9 se obsah t\u00e9to \u010d\u00e1sti m\u016f\u017ee li\u0161it. A na to u\u017e moje schopnost k\u00f3dov\u00e1n\u00ed holt nesta\u010d\u00ed.<\/p>\n\n\n\n

Proto je gener\u00e1tor nastaven tak, \u017ee v p\u0159\u00edpad\u011b pot\u0159eby vyplnit tuto \u010d\u00e1st, sta\u010d\u00ed kliknout na „Add Data-specific information“. M\u016f\u017ee\u0161 to opakovat tolikr\u00e1t, kolikr\u00e1t jen pot\u0159ebuje\u0161.<\/p>\n\n\n\n

Pokud bude pro Tebe tato \u010d\u00e1st nepodstatn\u00e1, ned\u011blej nic.<\/p>\n\n\n\n

A co do t\u00e9to \u010d\u00e1sti pat\u0159\u00ed?<\/p>\n\n\n\n

1. Seznam prom\u011bnn\u00fdch, v\u010detn\u011b cel\u00fdch n\u00e1zv\u016f a definic (uve\u010f zkratky) z\u00e1hlav\u00ed sloupc\u016f pro tabulkov\u00e1 data.
2. M\u011brn\u00e9 jednotky.
3. Definice k\u00f3d\u016f nebo symbol\u016f pou\u017eit\u00fdch k z\u00e1znamu chyb\u011bj\u00edc\u00edch dat.
4. Quality Control flags
5. Pozn\u00e1mky<\/p>\n<\/details>\n\n\n\n

7. Co nepot\u0159ebuje\u0161, nevypl\u0148uj<\/a><\/summary>\n

\u017d\u00e1dn\u00e9 z pol\u00ed nen\u00ed nastaveno defaultn\u011b jako povinn\u00e9. I tak by m\u011blo b\u00fdt vypln\u011bno co nejv\u00edc pol\u00ed. Pokud v\u0161ak je n\u011bco skute\u010dn\u011b irelevantn\u00ed, nech to pr\u00e1zdn\u00e9. Pokud se popisek prop\u00ed\u0161e do fin\u00e1ln\u00edho souboru, po otev\u0159en\u00ed ho b\u011bhem 5 sekund sma\u017ee\u0161.<\/p>\n<\/details>\n\n\n\n

8. Vygeneruj – prohl\u00e9dni – st\u00e1hni<\/a><\/summary>\n

Po vypln\u011bn\u00ed relevantn\u00edch pol\u00ed klikni ta tla\u010d\u00edtko Generate README<\/strong>. Zobraz\u00ed se n\u00e1hled cel\u00e9ho souboru. Pokud jsi s obsahem spokojen\u00fd, m\u016f\u017ee\u0161 soubor st\u00e1hnout kliknut\u00edm na tla\u010d\u00edtko Download README.md<\/strong>. Nebo m\u016f\u017ee\u0161 upravit pole v gener\u00e1toru a vygenerovat soubor nov\u00fd. Nemus\u00ed\u0161 se b\u00e1t, vypln\u011bn\u00e1 pole tak nezmiz\u00ed, nebude\u0161 muset d\u011blat v\u0161e od za\u010d\u00e1tku.<\/p>\n<\/details>\n\n\n\n

9. Defaultn\u00ed \u0161ablona README ke sta\u017een\u00ed<\/a><\/summary>\n

Jestli nejsi na tyhle online hra\u010dky, m\u016f\u017ee\u0161 si st\u00e1hnout defaultn\u00ed \u0161ablonu zde<\/a><\/span>. Jde o \u010dist\u00fd text, otev\u0159e se v proh\u00ed\u017ee\u010di. Cel\u00fd text ozna\u010d, zkop\u00edruj a vlo\u017e do pozn\u00e1mkov\u00e9ho bloku. Trv\u00e1 to tro\u0161ku d\u00fdl, ne\u017e p\u0159es gener\u00e1tor, ale po\u0159\u00e1d lep\u0161\u00ed, ne\u017e p\u0159ipravovat README od nuly.<\/p>\n<\/details>\n\n\n\n

10. Gener\u00e1tor je pouze v angli\u010dtin\u011b<\/a><\/summary>\n

Sv\u011btov\u00fdm jazykem v\u011bdy je angli\u010dtina a to se t\u00fdk\u00e1 i dokumentace dat. Nem\u011blo by smysl vytv\u00e1\u0159et README v \u010de\u0161tin\u011b nebo v jin\u00fdch jazyc\u00edch.<\/p>\n<\/details>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n\n\n\n

\n