Яку структуру папок рекомендується використовувати? Як повʼязати файли між собою за допомогою метаданих?
-----------------------------------------
Цілі хорошої організації
- Легко знайти потрібний файл (людям) і обробити його (машинам).
- Забезпечити відтворюваність: зрозуміло, яка версія, звідки дані, чим оброблені.
- Зменшити ризик плутанини у великих наборах (сотні/тисячі файлів).
Рекомендована структура папок (шаблон)
Код: Виділити все
dataset-root/
├─ data/
│ ├─ raw/ # сирі/первинні дані (недоторкані)
│ ├─ interim/ # проміжні результати (чистка/нормалізація)
│ └─ processed/ # кінцеві таблиці/масиви для аналізу/публікації
├─ code/ # скрипти, ноутбуки, конвеєри
├─ docs/ # звіти, методики, протоколи, постери/фігури
├─ metadata/
│ ├─ README.md # огляд набору (що всередині, як читати)
│ ├─ CHANGELOG.md # журнал змін (версії vX.Y)
│ ├─ data_dictionary.csv # опис змінних (назва, одиниці, словники)
│ ├─ file_manifest.csv # реєстр файлів (шлях, роль, опис, checksum)
│ └─ relationships.csv # посилання "який файл походить від якого"
└─ LICENSE.txt # ліцензія на дані (і, за потреби, CITATION.cff)
-----------------------------------------Тримайте глибину вкладеності ≤ 3 рівні. Для дуже великих проєктів додавайте рівень site/instrument, але не робіть “катакомби”.
Іменування файлів: правила й приклади
Правила
- Без пробілів і діакритики: ,
Код: Виділити все
lowercaseабоКод: Виділити все
snake_case.Код: Виділити все
kebab-case - ISO-дати: або мітка часу
Код: Виділити все
YYYY-MM-DD.Код: Виділити все
YYYY-MM-DDThhmmssZ - Послідовність елементів: проєкт_об’єкт/сайт_типданих_дата_версія_додатково.ext
- Падінг чисел: (камери, сесії, партії).
Код: Виділити все
001, 002, ... - Уникайте неоднозначних скорочень; для одиниць виміру використовуйте SI.
Код: Виділити все
projx_siteA_sensors_2025-08-15_v1.0.csv
projx_images_cam01_2025-08-15T101530Z.jpg
projx_model_outputs_2025-08-15_v1.2.parquet
projx_protocol_sample-prep_v1.1.pdf
projx_code_cleaning_v0.3.py
-----------------------------------------Для геоданих зберігайте узгоджене ім’я бази:.Код: Виділити все
map_tiles_v1.0.{shp,shx,dbf,prj}
file_manifest.csv (реєстр файлів)
Заведіть машинозчитуваний маніфест у metadata/file_manifest.csv, щоб пошук та перевірка цілісності були простими.
Код: Виділити все
file_path,role,description,derived_from,checksum_sha256,license
data/raw/siteA_2025-08-15.csv,raw,"Сирі сенсори, 1 Гц",,e3b0c442...,CC-BY-4.0
data/interim/siteA_2025-08-15_clean.csv,interim,"Фільтр Калмана","data/raw/siteA_2025-08-15.csv",a7f5f354...,CC-BY-4.0
data/processed/siteA_daily_2025-08-15.parquet,processed,"Добові агрегати",
"data/interim/siteA_2025-08-15_clean.csv",9c56cc51...,CC-BY-4.0
docs/methods_qc_v1.0.pdf,documentation,"Методика QC",,5d41402a...,CC-BY-4.0
code/etl_clean_v0.3.py,code,"Скрипт очистки",,098f6bcd...,MIT
Код: Виділити все
sha256sum */* > SHA256SUMS.txt-----------------------------------------
data_dictionary.csv (опис змінних)
Код: Виділити все
variable,label,description,unit,allowed_values,example,notes
timestamp,Час,"UTC ISO-8601","",,2025-08-15T10:15:30Z,""
temp,Температура,"Після калібрування",C,,"22.4","Датчик SHT31"
rh,Відносна вологість,,0..100,,"45.2","%"
soil_moisture,Вологість ґрунту,g/g,0..1,,"0.31","Метод TDR"
Як повʼязати файли між собою за допомогою метаданих
1) На рівні репозиторію (DataverseUA/Dataverse)
- Додайте зрозумілі описи файлів і теги файлів (Data / Code / Documentation / Supplementary).
- Скористайтесь полем directoryLabel при завантаженні — відтворює структуру папок.
- У цитаційному блоці метаданих вкажіть пов’язані матеріали: RelatedDatasets, RelatedMaterial, посилання на публікації.
- Для табличних файлів корисно вказати UNF (Dataverse) і опис змінних з data_dictionary.csv.
- Підтримуйте relationships.csv: стовпчик містить список джерел (файли/DOI).
Код: Виділити все
derived_from - У README.md додайте “Граф походження” словами: що є сирим, що проміжним, що підсумковим.
- У CHANGELOG.md фіксуйте, коли і чим згенеровані підсумкові файли.
- https://frictionlessdata.io/ — datapackage.json з описом ресурсів і схем.
- https://www.researchobject.org/ro-crate/ — RO-Crate (JSON-LD) для повного графа об’єкта дослідження.
- DataCite RelatedIdentifier — вкажіть, що файл/набір IsDerivedFrom інший DOI.
Практичні поради
- Не змішуйте різні версії даних у одній публікованій версії набору. Нова публікація → нова версія (vX.Y).
- Великі файли розбивайте на частини з чіткими іменами: + запис у маніфесті.
Код: Виділити все
dataset_part01of12.parquet - Уникайте закритих форматів, якщо є відкриті аналоги (CSV/Parquet/NetCDF/HDF5). Завжди UTF-8.
- Кожний скрипт у code/ має посилатися на конкретні файли/версії (і бажано на DOI набору).
- Додавайте прев’ю/візуалізації у docs/ — це допомагає рецензентам та колегам швидко зорієнтуватися.
Швидкий чек-лист перед публікацією
Код: Виділити все
[ ] README.md описує структуру та кроки використання
[ ] CHANGELOG.md пояснює відмінності версій (vX.Y)
[ ] file_manifest.csv і SHA256SUMS.txt узгоджені з фактичним вмістом
[ ] data_dictionary.csv покриває всі змінні в processed/ файлах
[ ] relationships.csv містить походження (derived_from) для оброблених даних
[ ] Ліцензія та спосіб цитування (CITATION або інструкція з цитування)
Запитання до спільноти
- Які шаблони структури/іменування працюють у ваших дисциплінах?
- Чи використовуєте RO-Crate або Frictionless Data? Поділіться прикладами.
- Які інструменти (скрипти) ви застосовуєте для автоматичного маніфесту та checksum?