259. Wersjonowanie bazy i słownika danych

W poprzednich lekcjach omawialiśmy kontrolę duplikatów, wartości niemożliwych, reguł logicznych, braków danych oraz dokumentowanie czyszczenia. Kolejnym krokiem jest zapewnienie, aby było wiadomo nie tylko jakie dane znajdują się w bazie, lecz także kiedy, dlaczego i przez kogo zostały zmienione. Temu służy wersjonowanie bazy danych i słownika danych.

Wersjonowanie nie jest zwykłym zapisywaniem kolejnych plików pod nazwami „baza_finalna”, „baza_finalna2” i „baza_ostateczna”. Jest uporządkowanym sposobem rejestrowania kolejnych stanów danych, definicji zmiennych, reguł kontroli jakości oraz decyzji zespołu badawczego. Dobrze zaprojektowany system pozwala odtworzyć zbiór użyty w analizie, wykazać zakres wprowadzonych zmian i ograniczyć ryzyko, że dwie osoby będą analizowały pozornie tę samą bazę, która w rzeczywistości różni się zawartością.

Czym jest wersjonowanie bazy danych?

Wersjonowanie bazy danych oznacza nadawanie kolejnym, formalnie zdefiniowanym stanom bazy unikatowych oznaczeń oraz dokumentowanie zmian pomiędzy tymi stanami. Wersją może być zarówno kopia całego zbioru danych, jak i identyfikowalny stan bazy przechowywany w systemie, który rejestruje historię modyfikacji.

W badaniach naukowych warto rozróżnić co najmniej trzy obiekty:

• dane surowe – dane otrzymane bezpośrednio ze źródła, na przykład z formularza elektronicznego, aparatu diagnostycznego lub pliku przekazanego przez instytucję;
• baza robocza – dane poddawane kontroli, korektom, rekodowaniu i tworzeniu zmiennych pochodnych;
• zbiór analityczny – wersja przygotowana do konkretnej analizy, często zawierająca wybrane obserwacje, określone kodowanie i jasno opisane reguły postępowania z brakami danych.

Nie należy nadpisywać danych surowych danymi po czyszczeniu. Jeżeli wartość została skorygowana, w dokumentacji powinno być możliwe ustalenie wartości pierwotnej, wartości po korekcie, przyczyny zmiany i osoby, która ją zatwierdziła. Taka zasada jest zgodna z ogólną ideą śladu audytowego, istotną zwłaszcza w badaniach klinicznych i projektach, w których dane mogą być poddawane kontroli zewnętrznej (Krishnankutty et al., 2012).

Czym jest słownik danych?

Słownik danych jest uporządkowanym opisem zmiennych, ich znaczenia, sposobu pomiaru, kodowania i dopuszczalnych wartości. Nie jest jedynie listą nazw kolumn. Powinien umożliwiać osobie spoza zespołu zrozumienie, co reprezentuje każda zmienna i jak należy jej używać w analizie.

Minimalny słownik danych powinien zawierać:

Element	Przykład
Nazwa zmiennej	sbp_baseline
Etykieta opisowa	Skurczowe ciśnienie tętnicze w punkcie wyjściowym
Definicja operacyjna	Pierwszy prawidłowo wykonany pomiar przed rozpoczęciem interwencji
Typ danych	Liczbowa, całkowita
Jednostka	mmHg
Zakres dopuszczalny	70–260
Kody specjalne	99 = brak informacji, tylko jeśli tak ustalono w planie kodowania
Źródło	Formularz wizyty początkowej
Wersja definicji	1.2

Słownik powinien opisywać również zmienne kategoryczne. Dla zmiennej smoking_status trzeba podać, czy kod 0 oznacza „nigdy nie palił”, 1 „były palacz”, a 2 „aktualny palacz”. Nie wystarczy sama informacja, że zmienna jest nominalna. Trzeba także określić, czy pytanie dotyczy całego życia, ostatnich 30 dni czy chwili badania.

Współczesne podejście do metadanych podkreśla, że opis danych powinien wspierać ich odnajdywanie, interpretację, interoperacyjność i ponowne wykorzystanie. Są to cele zgodne z zasadami FAIR, choć ich spełnienie wymaga czegoś więcej niż dołączenia prostego arkusza z nazwami kolumn (Wilkinson et al., 2016). W badaniach klinicznych znaczenie mają także metadane dotyczące pochodzenia danych, identyfikatorów badania, dostępu i odpowiedzialności za poszczególne obiekty danych (Canham i Ohmann, 2016).

Dlaczego baza i słownik muszą być wersjonowane razem?

Zmiana definicji zmiennej może zmienić interpretację wyników nawet wtedy, gdy wartości w komórkach pozostają bez zmian. Załóżmy, że w pierwszej wersji słownika zmienna depression oznacza rozpoznanie depresji odnotowane w dokumentacji medycznej. W drugiej wersji zespół opisuje ją jako wynik powyżej ustalonego punktu odcięcia w kwestionariuszu PHQ-9. Obie zmienne mają tę samą nazwę, ale mierzą różne konstrukty. Połączenie nowego słownika ze starą bazą prowadziłoby do błędnej interpretacji.

Analogicznie, zmiana kodowania może zmienić wyniki analiz. Jeśli w wersji 1 kod 1 oznacza „kobieta”, a w wersji 2 kod 1 oznacza „mężczyzna”, nie można po prostu podmienić słownika bez informacji o zakresie obowiązywania zmiany. Dlatego wersja bazy i wersja słownika powinny być ze sobą powiązane, na przykład:

• DB_2026-04-15_v1.0 – pierwsza zamknięta wersja bazy;
• DD_2026-04-15_v1.0 – słownik opisujący tę wersję;
• DB_2026-05-03_v1.1 – baza po korekcie błędów kodowania;
• DD_2026-05-03_v1.1 – słownik z poprawionymi kodami i historią zmian.

Jak zaprojektować numerowanie wersji?

Numerowanie wersji powinno być proste i konsekwentne. Jednym z praktycznych schematów jest zapis:

Wersja = MAJOR.MINOR.PATCH

• MAJOR – duża zmiana wpływająca na znaczenie zmiennych, strukturę bazy lub porównywalność z wcześniejszymi wersjami;
• MINOR – rozszerzenie bazy albo słownika bez zmiany znaczenia istniejących zmiennych;
• PATCH – korekta błędu technicznego lub dokumentacyjnego, która nie zmienia zaplanowanej interpretacji danych.

Przykład: wersja 2.1.3 może oznaczać drugą główną strukturę bazy, pierwsze rozszerzenie w jej obrębie oraz trzecią korektę techniczną. W projekcie trwającym kilka miesięcy można dodatkowo stosować datę, na przykład DB_2.1.3_2026-09-29. Data nie zastępuje numeru wersji, lecz ułatwia wyszukiwanie plików i porządkowanie archiwum.

Duża zmiana powinna zwiększać numer główny, gdy na przykład:

• zmienia się jednostka pomiaru;
• zmienna zostaje zastąpiona inną definicją operacyjną;
• zmienia się jednostka analizy, na przykład z pacjenta na wizytę;
• zmienia się sposób kodowania braków danych w sposób wpływający na analizę;
• zmieniona zostaje populacja objęta bazą.

Numer wersji nie ma znaczenia sam w sobie. Najważniejsze jest, aby zespół ustalił reguły przed rozpoczęciem pracy i stosował je do końca badania.

Rejestr zmian, czyli changelog

Każda wersja powinna mieć rejestr zmian. W najprostszej postaci jest to tabela zawierająca:

Data	Wersja	Obiekt	Opis zmiany	Powód	Osoba zatwierdzająca
2026-09-01	1.0.0	Baza i słownik	Utworzenie struktury badania	Rozpoczęcie rekrutacji	Kierownik projektu
2026-09-12	1.1.0	Słownik	Dodano jednostkę pomiaru dla masy ciała	Ujednolicenie formularzy	Koordynator danych
2026-09-18	1.1.1	Baza	Poprawiono literówkę w etykiecie	Korekta dokumentacyjna	Koordynator danych

Opis zmiany powinien być konkretny. Zdanie „poprawiono dane” nie pozwala odtworzyć decyzji. Lepszy zapis brzmi: „W 14 rekordach zamieniono kod 3 na kod 2, ponieważ formularz źródłowy zawierał kategorię »położna«, a słownik dopuszczał wyłącznie kod 2 dla tej kategorii; korektę potwierdzono z dokumentacją źródłową”.

Warto rozdzielić zmiany techniczne od merytorycznych. Zmiana kolejności kolumn może być techniczna. Zmiana definicji „aktywności fizycznej” jest merytoryczna i wymaga oceny, czy wcześniej wykonane analizy nadal są aktualne.

Wersjonowanie a ślad pochodzenia danych

Ślad pochodzenia, czyli data provenance, odpowiada na pytanie: skąd pochodzi dana wartość i jakie operacje wykonano przed jej uzyskaniem? W praktyce dokumentuje się co najmniej:

1. źródło danych;
2. datę importu;
3. wersję formularza lub systemu;
4. zastosowane reguły walidacji;
5. wykonane rekodowania;
6. utworzone zmienne pochodne;
7. wersję programu lub skryptu analitycznego;
8. osobę odpowiedzialną za zatwierdzenie.

W projektach klinicznych i wieloośrodkowych pomocne mogą być standardy wymiany metadanych. CDISC Operational Data Model obejmuje dane kliniczne wraz z metadanymi, informacjami administracyjnymi, danymi referencyjnymi i informacjami audytowymi (CDISC, 2023). Nie oznacza to, że każdy projekt akademicki musi wdrażać pełny standard CDISC. Warto jednak przyjąć jego podstawową ideę: dane powinny być przechowywane razem z opisem, kontekstem i informacją o historii zmian.

Przykład 1: badanie pacjentów z nadciśnieniem

Zespół prowadzi obserwacyjne badanie pacjentów podstawowej opieki zdrowotnej. W pierwszej wersji bazy zmienna bp_sys oznacza pojedynczy pomiar skurczowego ciśnienia tętniczego wykonany podczas wizyty. Po dwóch miesiącach badacze ustalają, że zgodnie z protokołem analizie powinien podlegać średni wynik z dwóch pomiarów.

Nie wystarczy zmienić opisu w słowniku. Trzeba:

• utworzyć nowe zmienne, na przykład bp_sys_1 i bp_sys_2;
• zdefiniować regułę obliczania średniej;
• ustalić, co zrobić, gdy brakuje jednego z pomiarów;
• zachować wcześniejszą wersję bazy;
• zaktualizować słownik i rejestr zmian;
• odnotować, czy wcześniejsze analizy opierały się na pojedynczym pomiarze.

Jeżeli średnia jest obliczana tylko wtedy, gdy dostępne są oba pomiary, można zapisać regułę:

bp_sys_mean = (bp_sys_1 + bp_sys_2) / 2

Symbol bp_sys_1 oznacza pierwszy pomiar, bp_sys_2 drugi pomiar, a bp_sys_mean średnią arytmetyczną. Jeżeli zespół dopuszcza obliczenie średniej przy jednym dostępnym pomiarze, musi to wyraźnie opisać, ponieważ zmienia to zarówno definicję zmiennej, jak i sposób postępowania z brakami danych.

Przykład 2: badanie dobrostanu psychicznego studentów

W badaniu ankietowym wykorzystano skalę dobrostanu z 10 pozycjami. W wersji 1 słownika zaznaczono, że wynik całkowity jest sumą odpowiedzi, przy czym brak jednej odpowiedzi zastępuje się średnią z pozostałych pozycji. Po konsultacji z metodologiem zespół decyduje, że zgodnie z instrukcją narzędzia wynik będzie liczony wyłącznie wtedy, gdy student udzielił odpowiedzi na co najmniej 8 z 10 pozycji.

Jest to zmiana merytoryczna. Wymaga utworzenia nowej wersji słownika, opisania progu 8 odpowiedzi, wskazania algorytmu uzupełniania brakującej pozycji i sprawdzenia, czy wyniki publikowane wcześniej nie wykorzystywały innej reguły. W przeciwnym razie dwie osoby mogą używać nazwy wellbeing_total dla wyników obliczonych według różnych zasad.

Warto przechowywać zarówno zmienne składowe, jak i zmienną wynikową. Pozwala to skontrolować, czy wynik został obliczony prawidłowo, oraz w razie potrzeby odtworzyć go według innej, uzasadnionej reguły.

Jak organizować pliki i uprawnienia?

Wersjonowanie wymaga także organizacji przechowywania. Przykładowa struktura katalogów może wyglądać następująco:

projekt_badanie/
├── 01_dane_surowe/
├── 02_bazy_wersjonowane/
├── 03_slowniki_danych/
├── 04_skrypty/
├── 05_rejestr_zmian/
├── 06_zbiory_analityczne/
└── 07_archiwum/

Dane surowe powinny być chronione przed przypadkową edycją. Dostęp do nich powinny mieć tylko osoby, które rzeczywiście go potrzebują. Z kolei baza robocza powinna być przechowywana w systemie umożliwiającym kontrolę dostępu, tworzenie kopii zapasowych i rejestrowanie modyfikacji. W przypadku danych medycznych wersjonowanie nie może naruszać zasad poufności, minimalizacji danych ani ustaleń zawartych w zgodzie uczestnika i planie zarządzania danymi.

W planach zarządzania danymi należy opisać między innymi standardy, narzędzia, sposób zachowania danych, dostęp i odpowiedzialność za nadzór. Takie elementy są obecnie wyraźnie akcentowane w polityce NIH dotyczącej zarządzania i udostępniania danych (NIH, 2021; NIH, 2026). W praktyce akademickiej podobny opis zwiększa przejrzystość projektu, nawet gdy grantodawca nie wymaga formalnego planu.

Najczęstsze błędy

• Nadpisywanie poprzedniej bazy. Uniemożliwia odtworzenie stanu danych z dnia wykonania wcześniejszej analizy.
• Używanie nazw „finalna” i „ostateczna”. Takie nazwy nie informują, czym różnią się pliki ani który z nich został wykorzystany w publikacji.
• Brak historii zmian w słowniku. Sam aktualny opis nie pokazuje, jakie definicje obowiązywały wcześniej.
• Zmiana kodów bez zmiany nazwy wersji. Może doprowadzić do błędnego połączenia danych i metadanych.
• Usuwanie wartości pierwotnych. Korekta powinna być możliwa do prześledzenia, a nie tylko widoczna jako nowy stan.
• Brak właściciela decyzji. W rejestrze powinno być wiadomo, kto zatwierdził zmianę i na jakiej podstawie.
• Wersjonowanie bazy bez wersjonowania skryptu. Ten sam skrypt może dać różne wyniki na różnych wersjach danych.
• Niejasne kody braków danych. Kod 99 może oznaczać „nie wiem”, „nie dotyczy” albo „odmowa odpowiedzi”; nie są to równoważne sytuacje.
• Traktowanie słownika jako dokumentu jednorazowego. Słownik powinien rozwijać się wraz z badaniem i odzwierciedlać aktualny stan projektu.

Przykład praktyczny: procedura zamknięcia wersji bazy

Przed przekazaniem zbioru do analizy zespół może zastosować następującą procedurę:

1. zablokować wprowadzanie nowych danych na czas kontroli;
2. wykonać kopię bazy i nadać jej unikatowy identyfikator;
3. uruchomić ustalone kontrole zakresów, braków, duplikatów i spójności;
4. przejrzeć wszystkie otwarte zapytania do ośrodków lub osób wprowadzających dane;
5. zaktualizować słownik danych;
6. wygenerować raport różnic względem poprzedniej wersji;
7. zatwierdzić bazę przez określone osoby;
8. zapisać wersję używaną w analizie wraz ze skryptem i opisem środowiska;
9. umieścić informację o wersji w raporcie analitycznym lub publikacji.

W raporcie można napisać na przykład: „Analizy wykonano na zamkniętej wersji bazy 2.1.0, utworzonej 29 września 2026 r.; definicje zmiennych i kody przedstawiono w słowniku danych w wersji 2.1.0”. Taki zapis jest znacznie bardziej użyteczny niż ogólne stwierdzenie, że „dane zostały oczyszczone”.

Jeżeli chcesz przećwiczyć opis zmian, reguły kontroli i przygotowanie zbioru analitycznego, możesz wykorzystać tę lekcję jako uzupełnienie publicznego szkolenia metodologiczno-statystycznego na statystyk.edu.pl.

Co warto zapamiętać?

• Wersjonowanie oznacza kontrolowane rejestrowanie kolejnych stanów bazy, a nie tworzenie przypadkowych kopii plików.
• Słownik danych opisuje znaczenie, kodowanie, jednostki, źródło i reguły interpretacji zmiennych.
• Baza i słownik powinny być wersjonowane razem, ponieważ zmiana definicji może zmienić znaczenie wyników.
• Dane surowe należy zachować i chronić przed nadpisaniem.
• Każda istotna zmiana powinna mieć datę, opis, uzasadnienie i osobę zatwierdzającą.
• Numer wersji powinien być powiązany także z wersją skryptu i zbiorem analitycznym.
• Ślad audytowy zwiększa odtwarzalność, przejrzystość i możliwość kontroli jakości.
• Dobrze prowadzony słownik ułatwia współpracę, analizę wtórną i odpowiedzialne udostępnianie danych.

Źródła i dalsza lektura

1. Krishnankutty, B.; Bellary, S.; Kumar, N. B. R.; Moodahadu, L. S. (2012). Data management in clinical research: An overview. Indian Journal of Pharmacology, 44(2), 168–172. DOI: 10.4103/0253-7613.93842.
2. Canham, S.; Ohmann, C. (2016). A metadata schema for data objects in clinical research. Trials, 17(1), 557. DOI: 10.1186/s13063-016-1686-5.
3. Rashid, S. M.; McCusker, J. P.; Pinheiro, P.; Bax, M. P.; Santos, H.; Stingone, J. A.; Das, A. K.; McGuinness, D. L. (2020). The Semantic Data Dictionary—An Approach for Describing and Annotating Data. Data Intelligence, 2(4), 531–546. DOI: 10.1162/dint_a_00058.
4. Wilkinson, M. D.; Dumontier, M.; Aalbersberg, I. J. J.; Appleton, G.; Axton, M.; Baak, A.; Blomberg, N.; Boiten, J.-W.; da Silva Santos, L. B.; Bourne, P. E.; et al. (2016). The FAIR Guiding Principles for scientific data management and stewardship. Scientific Data, 3, 160018. DOI: 10.1038/sdata.2016.18.
5. Smith, J. P.; Elliott, A. C.; Hynan, L. S.; Reisch, J. S.; Waddell, S. A. (2010). Creation and use of a database in clinical and translational research. Journal of Investigative Medicine, 58(3), 544–553. DOI: 10.231/JIM.0b013e3181c9f668.
6. National Institutes of Health (2021). Final NIH Policy for Data Management and Sharing. National Institutes of Health. Źródło.
7. National Institutes of Health (2026). Writing a Data Management and Sharing Plan. National Institutes of Health. Źródło.
8. Clinical Data Interchange Standards Consortium (2023). ODM v2.0. CDISC. Źródło.

Jeżeli potrzebujesz indywidualnego wsparcia w doborze metod, przygotowaniu bazy lub opracowaniu wyników badań, sprawdź analiza statystyczna.