136. Słownik kodów i etykiety wartości – jak je przygotować?

W poprzednich lekcjach omawialiśmy sposoby kodowania zmiennych, braków danych i kategorii odpowiedzi. Kolejnym krokiem jest udokumentowanie tego, co dokładnie oznacza każdy kod. Temu służy słownik kodów, często nazywany także z ang. codebookiem lub słownikiem danych. Bez takiej dokumentacji liczby zapisane w arkuszu mogą wyglądać poprawnie, ale po kilku tygodniach stają się niejednoznaczne nawet dla osoby, która je zakodowała. W tej lekcji pokazano, jak przygotować słownik kodów i etykiety wartości w sposób użyteczny dla badacza, analityka, członka zespołu oraz przyszłego użytkownika danych. Zasady te dobrze uzupełniają publiczne szkolenie metodologiczne dostępne na statystyk.edu.pl.

Czym jest słownik kodów?

Słownik kodów to uporządkowany dokument opisujący zmienne w zbiorze danych oraz sposób interpretowania ich wartości. Jego podstawowym zadaniem jest połączenie technicznej postaci danych z ich znaczeniem merytorycznym. W praktyce słownik może być arkuszem kalkulacyjnym, tabelą w dokumentacji projektu, plikiem tekstowym, dokumentem JSON/XML albo elementem systemu zarządzania danymi.

Dobry codebook powinien umożliwiać odpowiedź na pytania: jak nazywa się zmienna, co mierzy, w jakich jednostkach, jakie wartości może przyjmować, co oznacza każdy kod, które wartości są brakami danych oraz czy zmienna jest pierwotna, czy wyprowadzona. ICPSR wskazuje, że dokumentacja zmiennej powinna obejmować między innymi nazwę, etykietę, treść pytania, wartości kodów, etykiety wartości i – zależnie od potrzeb – statystyki opisowe (ICPSR, 2026).

Etykieta wartości to tekstowe objaśnienie przypisane do konkretnego kodu. Jeżeli w bazie zapisano 1, sama liczba nie mówi, czy oznacza „kobieta”, „tak”, „łagodny ból”, „oddział intensywnej terapii” czy „pierwszą kategorię odpowiedzi”. Dopiero etykieta, na przykład 1 = kobieta, nadaje kodowi znaczenie.

Słownik kodów a etykiety wartości

Te pojęcia są powiązane, ale nie są synonimami.

• Słownik kodów opisuje cały zbiór zmiennych i ich właściwości.
• Etykiety wartości opisują znaczenie poszczególnych kodów w obrębie jednej zmiennej.
• Etykieta zmiennej to krótki opis tego, co mierzy zmienna, na przykład „Samodzielnie oceniany poziom bólu w chwili przyjęcia”.
• Lista kodów określa dopuszczalne wartości, na przykład 0, 1, 2, 3.

W programach statystycznych etykiety wartości mogą być przechowywane razem z danymi. Nie należy jednak zakładać, że zapiszą się poprawnie po eksporcie do CSV, imporcie do innego programu albo po połączeniu kilku zbiorów. Z tego względu słownik powinien istnieć jako osobny, kontrolowany dokument.

Po co przygotowywać słownik kodów?

Jednoznaczność interpretacji

Najważniejszą funkcją słownika jest ograniczenie ryzyka błędnej interpretacji. Kod 2 może oznaczać „nie”, ale w innej zmiennej – „umiarkowane nasilenie objawów”. Znaczenie kodu zawsze zależy od konkretnej zmiennej, dlatego nie wolno tworzyć jednej uniwersalnej legendy dla całego badania, jeśli kody nie są rzeczywiście zharmonizowane.

Kontrola jakości danych

Słownik pozwala wykrywać wartości niedopuszczalne. Jeżeli zmienna „status palenia” ma kody od 0 do 2 oraz osobny kod braku danych, pojawienie się wartości 7 powinno uruchomić kontrolę. Dokumentacja staje się wówczas podstawą reguł walidacyjnych w formularzu, arkuszu lub skrypcie analitycznym.

Powtarzalność i przekazywanie danych

W badaniu zespołowym wiele osób może mieć kontakt z bazą: ankieterzy, pielęgniarki, koordynatorzy, statystyk i archiwista. Słownik ogranicza zależność od pamięci pojedynczego badacza. Jest również ważny przy analizie wtórnej i udostępnianiu danych, ponieważ metadane są formą komunikacji między twórcą danych a ich późniejszym użytkownikiem (ICPSR Metadata Documentation Portal, 2026).

Interoperacyjność

W badaniach klinicznych i zdrowotnych słowniki danych są częścią szerszego systemu metadanych. WHO stosuje ustrukturyzowane opisy danych, obejmujące między innymi nazwy, definicje i kody, aby ułatwić ich interpretację przez ludzi oraz systemy komputerowe (WHO, 2022). W badaniach regulowanych standard Define-XML opisuje między innymi zbiory, zmienne, kontrolowane terminy oraz metadane zależne od wartości (CDISC, 2019).

Minimalna struktura słownika kodów

Nie istnieje jeden obowiązkowy układ dla każdego projektu, ale praktyczny słownik powinien zawierać co najmniej następujące kolumny:

Element	Co opisuje?
Nazwa zmiennej	Techniczna nazwa kolumny, na przykład pain_adm.
Etykieta zmiennej	Krótki, zrozumiały opis treści zmiennej.
Definicja operacyjna	Sposób pomiaru, moment pomiaru i kryteria klasyfikacji.
Typ danych	Tekst, liczba całkowita, liczba rzeczywista, data, czas lub wartość logiczna.
Poziom pomiaru	Nominalny, porządkowy, przedziałowy lub ilorazowy, z uwzględnieniem charakteru konkretnego pomiaru.
Jednostka	Na przykład mmHg, kg, lata, punkty albo brak jednostki.
Kody i etykiety	Pełna lista dopuszczalnych wartości wraz z ich opisem.
Kody braków danych	Rozróżnienie między „nie wiem”, „odmowa odpowiedzi”, „nie dotyczy” i brakiem technicznym.
Źródło	Kwestionariusz, dokumentacja medyczna, pomiar aparatem lub zmienna wyprowadzona.
Reguła walidacji	Zakres, warunek logiczny lub zależność od innej zmiennej.

W większych projektach warto dodać wersję słownika, datę aktualizacji, osobę odpowiedzialną, status zatwierdzenia oraz informację o zmianach. Dla zmiennych pochodnych należy dopisać wzór lub algorytm obliczeń. WHO w przykładowych słownikach danych wskazuje również na potrzebę dokumentowania typów danych, kodów, opcji wejściowych i reguł obliczeń (WHO, 2023).

Jak projektować kody i etykiety wartości?

1. Zacznij od znaczenia, nie od numeru

Najpierw należy ustalić, jakie kategorie lub wartości rzeczywiście występują w pomiarze. Dopiero potem przypisuje się im kody. Na przykład dla statusu palenia można ustalić: „nigdy nie palił”, „były palacz”, „aktualny palacz”. Kody 0, 1 i 2 są wtórne wobec tej definicji.

2. Używaj kodów stabilnych i jednoznacznych

Warto zachować tę samą konwencję w całym projekcie. Jeżeli 1 oznacza „tak” w zmiennej dotyczącej zgody, podobne znaczenie może mieć w innych zmiennych binarnych, o ile nie prowadzi to do niejasności. Nie należy jednak poświęcać poprawności semantycznej na rzecz sztucznej jednolitości.

3. Nie koduj porządku tam, gdzie go nie ma

W zmiennej nominalnej kody są tylko identyfikatorami kategorii. Jeżeli regiony zakodowano jako 1 = północ, 2 = centrum, 3 = południe, nie oznacza to, że południe ma „więcej” cechy niż centrum. W analizie nie wolno automatycznie traktować takich kodów jako liczby o znaczeniu ilościowym.

4. Zachowaj pełne etykiety

Etykieta „1 = tak” jest użyteczna, ale w badaniu medycznym lepsza może być etykieta „1 = rozpoznanie potwierdzone w dokumentacji”. Etykieta powinna być krótka, lecz wystarczająco precyzyjna, aby nie wymagała domyślania się kontekstu.

5. Dokumentuj wersję narzędzia

Jeżeli zmienna pochodzi z kwestionariusza, zapisz nazwę instrumentu, wersję, język i sposób punktowania. Dotyczy to zwłaszcza skal psychologicznych i klinicznych, w których zmiana instrukcji, zakresu odpowiedzi lub kodowania braków może wpływać na wynik.

Przykład 1: ból przy przyjęciu do oddziału ratunkowego

Załóżmy, że pacjent ocenia ból w chwili przyjęcia w skali od 0 do 10, gdzie 0 oznacza brak bólu, a 10 ból najsilniejszy z możliwych. Zmienna może być opisana tak:

Nazwa	Etykieta	Kody	Typ i jednostka
pain_arrival	Natężenie bólu przy przyjęciu	0–10 = wynik oceny bólu; 99 = nie zmierzono	Liczbowa; punkty

W tym przypadku kod 99 nie jest wynikiem bólu. Jest kodem braku danych i powinien być oznaczony jako brak, a nie analizowany jako bardzo silny ból. Jeżeli narzędzie przewidywało odpowiedź „pacjent nieprzytomny”, nie należy ukrywać jej pod kodem 99 bez dokumentacji. Można rozważyć osobny kod, na przykład 98 = pacjent niezdolny do samooceny, pod warunkiem że zostanie on konsekwentnie zdefiniowany i wyłączony z analiz wymagających rzeczywistego wyniku skali.

Ważna jest też definicja momentu pomiaru. „Ból przy przyjęciu” nie powinien oznaczać raz pomiaru przed podaniem leku, a innym razem pomiaru po interwencji ratownika. Słownik powinien wskazywać moment oraz warunki pomiaru.

Przykład 2: status palenia w badaniu zdrowia publicznego

Można zaprojektować zmienną nominalną:

Kod	Etykieta wartości	Definicja
0	Nigdy nie palił	Osoba, która nie wypaliła w życiu co najmniej 100 papierosów i obecnie nie pali.
1	Były palacz	Osoba, która paliła w przeszłości, ale obecnie nie pali.
2	Aktualny palacz	Osoba paląca obecnie, zgodnie z definicją przyjętą w protokole.
7	Nie wiem	Respondent nie potrafił udzielić odpowiedzi.
8	Odmowa	Respondent odmówił odpowiedzi.

Kody 7 i 8 nie są kategoriami statusu palenia. Są informacją o jakości lub dostępności odpowiedzi. Ich rozdzielenie może mieć znaczenie, ponieważ odmowa może występować częściej w określonych grupach, a odpowiedź „nie wiem” może wskazywać na inny problem pomiarowy. Łączenie wszystkich tych sytuacji w jeden kod „brak” upraszcza bazę, ale usuwa informację.

Przykład praktyczny: projektowanie słownika dla badania pielęgniarek

Badanie dotyczy obciążenia pracą pielęgniarek na oddziale. Zespół zbiera liczbę pacjentów pod opieką, liczbę godzin dyżuru, ocenę zmęczenia i rodzaj zmiany. Zamiast tworzyć jedynie listę nazw kolumn, zespół powinien ustalić pełne definicje:

• patients_shift – liczba pacjentów przypisanych do pielęgniarki na początku zmiany; liczba całkowita; zakres 0–60;
• shift_hours – rzeczywisty czas trwania zmiany w godzinach, zapisany z dokładnością do 0,1 godziny;
• fatigue_end – samoocena zmęczenia po zakończeniu zmiany: 0 = brak zmęczenia, 1 = niewielkie, 2 = umiarkowane, 3 = duże, 4 = bardzo duże;
• shift_type – 1 = dzienna, 2 = nocna, 3 = inna, zgodnie z definicją protokołu.

Jeżeli liczba pacjentów jest rejestrowana na początku zmiany, nie wolno później opisywać jej jako „średnia liczba pacjentów podczas dyżuru”. Taka zmiana etykiety zmieniałaby znaczenie danych. Właśnie dlatego definicja operacyjna jest ważniejsza niż sama nazwa kolumny.

Dla zmiennej fatigue_end należy udokumentować kierunek skali: wyższy wynik oznacza większe zmęczenie. Ma to znaczenie przy interpretacji średnich, korelacji i modeli regresji. Warto też wskazać, czy skala jest pojedynczym pytaniem porządkowym, czy wynikiem sumowania wielu pozycji. Nie należy utożsamiać etykiety wartości z pełną dokumentacją narzędzia pomiarowego.

Jak kontrolować słownik przed rozpoczęciem analizy?

1. Sprawdź, czy każda kolumna w zbiorze ma odpowiadający wpis w słowniku.
2. Porównaj listę dopuszczalnych kodów z faktycznymi wartościami w danych.
3. Zweryfikuj, czy kody braków danych są wyraźnie odróżnione od prawidłowych odpowiedzi.
4. Sprawdź zgodność etykiet z kwestionariuszem i protokołem badania.
5. Upewnij się, że jednostki miary są zapisane przy każdej zmiennej ilościowej.
6. Przetestuj reguły logiczne, na przykład: jeśli pregnant = 0, zmienna dotycząca tygodnia ciąży powinna mieć wartość „nie dotyczy”.
7. Zapisz datę, autora i powód każdej zmiany w słowniku.

W projektach klinicznych warto dokumentować również pochodzenie wartości i przekształcenia, którym została poddana. Literatura dotycząca metadanych wartości podkreśla znaczenie informacji o źródle, definicji, zmianach, kontroli jakości i ścieżce przetwarzania danych (Canham i Ohmann, 2016; Rashid i in., 2020).

Najczęstsze błędy

• Brak słownika albo tworzenie go dopiero po analizie. Po czasie trudno odtworzyć pierwotne decyzje kodowania.
• Używanie nieopisanych kodów magicznych. Wartości 7, 8, 9 lub 99 nie powinny być wprowadzane bez wskazania, co oznaczają.
• Traktowanie kodów kategorii jako wyników ilościowych. Kod 3 nie musi oznaczać „więcej” niż kod 1.
• Łączenie różnych rodzajów braków danych. „Nie dotyczy”, „odmowa” i „nie zmierzono” mogą mieć różne znaczenie.
• Zbyt ogólne etykiety. Opis „wynik testu” nie mówi, jaki test wykonano, w jakiej jednostce i kiedy.
• Zmiana etykiety bez zmiany danych lub odwrotnie. Aktualizacja dokumentacji musi odpowiadać rzeczywistej zmianie w bazie.
• Brak informacji o wersji narzędzia. Dotyczy to zwłaszcza kwestionariuszy, skal i klasyfikacji medycznych.
• Wpisywanie całej metodologii do jednej komórki. Słownik powinien być zwięzły, ale szczegółowe reguły można powiązać z protokołem i instrukcją badania.
• Brak kontroli kodów po imporcie i eksporcie. Program może zmienić typ danych, usunąć zera wiodące albo potraktować kody jako tekst.

Co warto zapamiętać?

• Słownik kodów jest dokumentacją znaczenia danych, a nie tylko legendą do tabeli.
• Etykieta wartości wyjaśnia konkretny kod, natomiast etykieta zmiennej opisuje całą zmienną.
• Każda zmienna powinna mieć definicję, typ danych, jednostkę lub informację o jej braku, dopuszczalne wartości oraz sposób kodowania braków.
• Kody nominalne są identyfikatorami kategorii i nie powinny być automatycznie traktowane jako liczby.
• Warto rozdzielać różne przyczyny braku odpowiedzi, jeśli mogą mieć znaczenie dla jakości danych lub interpretacji wyników.
• Słownik trzeba tworzyć przed zbieraniem danych, aktualizować w toku projektu i wersjonować.
• Dobra dokumentacja zwiększa powtarzalność, ułatwia kontrolę jakości i pozwala innym badaczom prawidłowo wykorzystać zbiór.

Przygotowanie słownika kodów jest niewielkim zadaniem organizacyjnym, ale ma duże konsekwencje metodologiczne. Chroni przed pomyleniem kodu z pomiarem, kategorii z liczbą oraz braku danych z rzeczywistą obserwacją. W dobrze zaprojektowanym badaniu słownik powstaje razem z narzędziem pomiarowym i protokołem, a nie dopiero wtedy, gdy pojawia się problem podczas analizy.

Źródła i dalsza lektura

1. Inter-university Consortium for Political and Social Research (ICPSR) (2026). What is a codebook?. ICPSR. University of Michigan. Źródło.
2. Inter-university Consortium for Political and Social Research (ICPSR) (2026). ICPSR Metadata Documentation Portal. ICPSR Metadata Documentation Portal. Inter-university Consortium for Political and Social Research. Źródło.
3. World Health Organization (2022). Data Description Schema. WHO Data. World Health Organization. Źródło.
4. Clinical Data Interchange Standards Consortium (CDISC) (2019). Define-XML v2.1. CDISC Standards. Clinical Data Interchange Standards Consortium. Źródło.
5. Canham, Steve; Ohmann, Christian (2016). A metadata schema for data objects in clinical research. Trials, 17(1), 557. DOI: 10.1186/s13063-016-1686-5.
6. Rashid, Sabbir M.; McCusker, James P.; Pinheiro, Paulo; Bax, Marcello P.; Santos, Henrique; Stingone, Jeanette A.; Das, Amar K.; McGuinness, Deborah L. (2020). The Semantic Data Dictionary—An Approach for Describing and Annotating Data. Data Intelligence, 2(3), 416–427. DOI: 10.1162/dint_a_00058.
7. Buchanan, Erin M.; Crain, Sarah E.; Cunningham, Ari L.; Johnson, Hannah R.; Stash, Hannah; Papadatou-Pastou, Marietta; Isager, Peder M.; Carlsson, Rickard; Aczel, Balazs (2021). Getting Started Creating Data Dictionaries: How to Create a Shareable Data Set. Advances in Methods and Practices in Psychological Science, 4(1). DOI: 10.1177/2515245920928007.
8. World Health Organization (2023). SMART DAK SMBP: Data Dictionary. SMART Guidelines Digital Adaptation Kits. World Health Organization. Źródło.