Biologické Centrum AV ČR, v.v.i.
Generátor souboru README
README je stručný, ale zásadní „průvodce datasetem“. Popisuje, co data obsahují, jak vznikla, jak jsou soubory uspořádané, jaké jsou proměnné/jednotky a jak data správně interpretovat. Jeho účelem je, aby bylo snadné dataset pochopit a znovu použít kolegy v týmu, externími partnery a vědeckou komunitou bez sáhodlouhého vysvětlování. Koneckonců se to může hodit i Tobě, kdyby ses k datasetu vrátil za několik let.
README je obvykle textový soubor (README.md nebo README.txt), který lze otevřít v libovolném editoru a který je dlouhodobě udržitelný i bez speciálního softwaru.
Proč to má smysl
1) Usnadňuje opakovatelnost a šetří čas (i vám samotným)
Bez README musí uživatelé dohledávat význam zkratek, názvů souborů, kódů, jednotek nebo parametrů analýzy v článcích či poznámkách. To může trvat hodiny až dny. Někdy může být samotný dataset úplně nepoužitelný.
README zachytí „tiché znalosti“ (nastavení přístroje, kroky zpracování, QC, význam sloupců) průběžně a zamezí tomu, že se klíčové detaily pro pochopení dat i celého výzkumu „ztratí v překladu“.
2) Je to rychlá cesta k FAIR datům (a k lepší citovanosti)
FAIR principy (a od ledna 2027 také Zákon č. 328/2025 Sb.) zdůrazňují, že data mají být dohledatelná, přístupná, interoperabilní a znovupoužitelná. Aby data byla skutečně znovupoužitelná, je k tomu potřeba bohatá dokumentace, licence a provenience.
Dokumentace v podobě README je k tomu ideální, protože doplňuje omezená repozitářová metadata o praktické instrukce a nezbytné informace.
3) Zvyšuje šanci na hladké uložení dat do repozitářů
Řada repozitářů i datových kurátorů očekává, že dataset bude mít popsaný obsah, strukturu souborů, proměnné a pravidla použití. README urychlí publikaci a sníží počet dotazů při kurátorské kontrole.
Pro znovupoužití dat je klíčové uvést nejen „hotové tabulky“, ale i informace o tom, jak vznikly. K tomu často nestačí samotná publikace. Natož, aby data mohla být použita i pro jiný účel, než je replikace publikovaného výzkumu.
Kdy, kam, proč
Kdy README vytvářet
Nejlepší praxe je připravit soubor README už na začátku projektu/výzkumu a průběžně ho aktualizovat. Později se důležité detaily snadno zapomenou. A když už to necháš nakonec, vytvořit bys ho měl nejpozději před tím, než budeš datasety zveřejňovat, nebo je vykazovat jako výsledek typu T.
README se typicky doplňuje při každé významné změně: nové verze souborů, úprava proměnných, změna pipeline, doplnění QC, nebo publikace nové verze datasetu.
Kam README ukládat
README má být uložen přímo spolu s daty, aby se „neztratil“. Soubor README by měl být jeden z prvních, který uživatel u datasetu uvidí. Nejjednodušší je uložit ho přímo do kořenového adresáře datasetu/projektu (root folder). Pokud máš více souborů README (např. pro logické ucelené skupiny souborů), ulož každý README do daného adresáře.
Obecně se doporučuje nazvat README prostě README.md (Markdown) nebo README.txt (prostý text). Doporučil bych se pár sekund zdržet a název přeci jen trošku vyladit. Co třeba: README_bc_[projectAcronym]_[DataSetName]_[yyyy]. Takový název pomůže s identifikací a přiřazením ke konrétnímu datasetu. Prostě i tento soubor se může zatoulat, jako každý jiný.
Proč README nestačí nahradit metadaty v repozitáři
Repozitářová metadata jsou skvělá pro indexování a vyhledávání dat. Je to podobné, jako bibliografický záznam u knihy. Ale README slouží úplně k něčemu jinému. Díky němu jsou data opětovné použitelná a tzv. interoperabilní. Když někdo dohledá data díky metadatům a stáhne si je, aby s nimi mohl dál pracovat, README jde s nimi a pořád vysvětluje kontext a použití.
Proto je klíčové mít obojí: důsledně vyplněná metadata v repozitáři a současně přiložený README, které detailně popíše strukturu souborů, proměnné, kódy, zpracování, QC atd.
Co by měl soubor README obsahovat (doporučené minimum)
1. Kdo / kontakt: autoři, instituce, e-mail pro dotazy.
2. Co to je: krátký popis datasetu a účelu.
3. Struktura souborů: seznam souborů a co je v každém z nich, vztahy mezi soubory.
4. Metody: jak byla data sbírána/generována a jak byla zpracována z raw do processed (včetně nástrojů a verzí).
5. Popis proměnných: názvy sloupců, definice, jednotky, kódy pro chybějící hodnoty, zkratky.
6. QC a outliery: jak proběhla kontrola kvality a jak bylo naloženo s podezřelými hodnotami.
7. Licence a citace: jak data použít a jak je citovat.
Generátor README pro biologická data
1. Jde o funkční, ale přesto stále testovací beta verzi.
Omluv proto, prosím, drobné nedostatky. Budu rád, za připomínky, abych generátor vyladil. 🙂
2. Vyber typ README podle typu datasetu
Nyní jsou 4:
Ekologie / Biodiversita
Omics
Bioimaging
Laboratorní experiment
Pokud máš zájem o další, napiš mi do e-mailu, o jaký, a ideálně přidej i pole, která by v novém README neměla chybět. Bohužel neumím zázraky na počkání, pár dní to potrvá.
Šablony můžeš použít i pro jiné typy datasetů. I tak dost urychlí a zjednoduší práci.
1. Vyber ten, který nejvíc odpovídá, a vyplň ho.
2. Vygeneruj hotový README.md a stáhni ho.
3. Dej mu trochu smysluplný název (např. bc_README_projectAcronym_Dataset_v10.md).
4. Otevři v poznámkovém bloku.
5. Co nesedí Tvému cíli, smaž, přepiš, doplň.
6. Ulož.
3. Přidej spoluautory
Můžeš vyplnit pouze PI. Zrovna tak můžeš vyplnit všechny spoluautory výzkumných dat, ke kterým se konkrétní README file váže. Je to dokonce žádoucí. Proto stačí kliknout na „Add co-author“.
4. Zadání licence
Zadej licenci, která určí, jakým způsobem můžou s datasetem nakládat ostatní. Nejběžnější je CC-BY. To umožní ostatním vědcům využívat v plné šíři, ale vždy Tě budou muset alespoň citavat jako autora.
Pokud se k datům vážou nějaké restrikce nebo časové embargo, kdy je nelze volně použít, pole „Access restrictions / ethical restrictions / embargo“ je správné místo, kde toto popsat.
5. Outliery: pravidla + zacházení
U některých typů datasetů je možnost vyplnit Outliery.
Ty mohou být chyba měření (pipetace, bublina, saturace, špatná jamka, drift přístroje) nebo skutečný biologický jev. Bez popisu pravidla to nikdo nepozná.
Transparentní popis outlierů a QC je součástí dobré dokumentace dat (včetně definic kódů/flagů pro nízkou kvalitu a outliery).
Doporučený obsah toho pole
1.Úroveň: technické repliky / biologické repliky / celé série / celý soubor.
2. Detekce: např. „IQR > 1.5ד, „>3×MAD“, „z-score > 3“, „flag přístroje“, „mimo rozsah kalibrační křivky“
3. Zacházení: odstraním / označím / nastavím NA / opakuji měření
4. Evidence: např. sloupec qc_flag, outlier_reason, log v changelog, ponechání raw dat beze změny
Př.
Outlier detection rule: „Within technical replicas, we mark an outlier if it differs from the median of technical replicas by >3×MAD.”
Outlier handling: „I 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.“
6. Data-specific information
Data-specific information je část README souboru, kam se zapisují, jak název napovídá, hodně specifické informace. Navíc tato část nemusí být v README ani jednou, nebo se může opakovat mnohokrát (ke každému souboru, tabulce, datasetu atd.). Záleží na okolnostech a obsahu datasetu. A pokaždé se obsah této části může lišit. A na to už moje schopnost kódování holt nestačí.
Proto je generátor nastaven tak, že v případě potřeby vyplnit tuto část, stačí kliknout na „Add Data-specific information“. Můžeš to opakovat tolikrát, kolikrát jen potřebuješ.
Pokud bude pro Tebe tato část nepodstatná, nedělej nic.
A co do této části patří?
1. Seznam proměnných, včetně celých názvů a definic (uveď zkratky) záhlaví sloupců pro tabulková data.
2. Měrné jednotky.
3. Definice kódů nebo symbolů použitých k záznamu chybějících dat.
4. Quality Control flags
5. Poznámky
7. Co nepotřebuješ, nevyplňuj
Žádné z polí není nastaveno defaultně jako povinné. I tak by mělo být vyplněno co nejvíc polí. Pokud však je něco skutečně irelevantní, nech to prázdné. Pokud se popisek propíše do finálního souboru, po otevření ho během 5 sekund smažeš.
8. Vygeneruj – prohlédni – stáhni
Po vyplnění relevantních polí klikni ta tlačítko Generate README. Zobrazí se náhled celého souboru. Pokud jsi s obsahem spokojený, můžeš soubor stáhnout kliknutím na tlačítko Download README.md. Nebo můžeš upravit pole v generátoru a vygenerovat soubor nový. Nemusíš se bát, vyplněná pole tak nezmizí, nebudeš muset dělat vše od začátku.
9. Defaultní šablona README ke stažení
Jestli nejsi na tyhle online hračky, můžeš si stáhnout defaultní šablonu zde. Jde o čistý text, otevře se v prohížeči. Celý text označ, zkopíruj a vlož do poznámkového bloku. Trvá to trošku dýl, než přes generátor, ale pořád lepší, než připravovat README od nuly.
README Generator for Biological Datasets
Select a dataset type → fill in the fields → generate a README (Markdown) → copy or download.
1) README metadata & general information
2) Methods — common core
3) Domain-specific information
5) Output (README.md)
Click “Generate README”…
README.md, open it in any plain-text editor or Markdown editor, revise the relevant sections, and save the file again.If you change the dataset structure, methods, files, or access conditions, update those sections at the same time. Always remember to update the README last updated date and the README version.