140. Jak przygotować książkę kodową gotową do SPSS, Jamovi, R i Statistica?

W poprzednich lekcjach omówiliśmy pojedyncze elementy przygotowania bazy: nazwy zmiennych, identyfikatory, etykiety wartości, kodowanie braków danych, jednostki miary i kontrolę zakresów. Książka kodowa (codebook) łączy te elementy w jeden spójny dokument. Jest opisem struktury zbioru danych, który pozwala innej osobie zrozumieć, co oznacza każda kolumna, jakie wartości są dopuszczalne i jak dana zmienna powinna być traktowana w analizie.

Dobrze przygotowana książka kodowa nie jest dodatkiem tworzonym po zakończeniu badania. Powinna powstawać równolegle z kwestionariuszem, formularzem obserwacji lub planem ekstrakcji danych. Dzięki temu ogranicza ryzyko niejednoznacznego kodowania, ułatwia import do SPSS, Jamovi, R i Statistica oraz zwiększa odtwarzalność analiz. Zasada ta jest zgodna z praktyką organizowania danych w prostokątnej tabeli, w której wiersze oznaczają przypadki, kolumny zmienne, a osobny słownik opisuje ich znaczenie i kody (Broman i Woo, 2018).

Czym jest książka kodowa (codebook)?

Codebook, nazywany także słownikiem danych lub księgą kodów, to dokument opisujący każdą zmienną znajdującą się w zbiorze danych. W najprostszej postaci może być arkuszem kalkulacyjnym. Każdy wiersz arkusza odpowiada jednej zmiennej, a kolumny zawierają jej właściwości.

Książka kodowa powinna odpowiadać co najmniej na następujące pytania:

• Jak nazywa się zmienna w pliku danych?
• Co dokładnie mierzy lub opisuje?
• Jakiego jest typu: liczbowa, tekstowa, data, logiczna?
• Jaki ma poziom pomiaru: nominalny, porządkowy, przedziałowy lub ilorazowy?
• Jakie wartości są dopuszczalne?
• Co oznacza każdy kod kategorii?
• Jak zakodowano brak odpowiedzi, nieznajomość odpowiedzi lub nieadekwatność pytania?
• W jakiej jednostce zapisano wynik?
• Czy zmienna jest surowa, przekształcona czy obliczona?
• Czy należy ją uwzględnić w analizie, czy pełni wyłącznie funkcję techniczną?

W SPSS część tych informacji można zapisać bezpośrednio w widoku zmiennych: nazwa, typ, etykieta, etykiety wartości, kody braków danych i poziom pomiaru są właściwościami zmiennej przechowywanymi w pliku danych (IBM, 2025). W Jamovi podobną funkcję pełnią typ danych, typ pomiaru, etykieta zmiennej, poziomy kategorii i definicje braków danych (jamovi, 2026). W R i Statistica książka kodowa jest szczególnie ważna, ponieważ sam plik CSV często nie przechowuje pełnej informacji o etykietach i poziomach pomiaru.

Minimalna struktura książki kodowej

Najbardziej użyteczną książkę kodową można zbudować jako tabelę. Zalecany zestaw kolumn przedstawiono poniżej.

Pole	Znaczenie	Przykład
variable_name	Techniczna nazwa zmiennej	age_years
label	Pełny opis zmiennej	Wiek uczestnika w latach
source	Źródło informacji	Kwestionariusz, pytanie 3
data_type	Typ zapisanych danych	integer, decimal, character
measurement_level	Poziom pomiaru	continuous, ordinal, nominal
unit	Jednostka	lata, kg/m2, punkty
valid_values	Zakres lub lista wartości poprawnych	18–99
value_labels	Opis kodów kategorii	0 = nie, 1 = tak
missing_codes	Kody oznaczające brak danych	99 = nie wiem, 98 = odmowa
role	Rola w analizie	predyktor, wynik, identyfikator
derivation	Sposób utworzenia	średnia z pozycji BDI_01–BDI_21
notes	Dodatkowe reguły	Nie dotyczy osób bez diagnozy

Nie każda zmienna musi mieć wszystkie pola wypełnione w identyczny sposób. Dla zmiennej tekstowej pole „value_labels” może nie mieć zastosowania, natomiast dla zmiennej kategorialnej będzie kluczowe. Najważniejsza jest konsekwencja i jednoznaczność.

Nazwy zmiennych: krótkie technicznie, pełne opisowo

Nazwa zmiennej powinna być krótka, stabilna i możliwa do użycia w każdym z planowanych programów. Najbezpieczniej stosować litery alfabetu łacińskiego, cyfry i znak podkreślenia. Należy unikać spacji, polskich znaków, ukośników, nawiasów i znaków interpunkcyjnych. Przykładowe nazwy to sex, age_years, sbp_mmHg, pain_pre oraz pain_post.

Nazwa techniczna nie powinna zastępować pełnego opisu. qol_total jest użyteczne w składni programu, ale dopiero etykieta „Łączny wynik jakości życia w skali WHOQOL-BREF” informuje, co rzeczywiście oznacza zmienna. Warto także ustalić regułę nazewnictwa przed rozpoczęciem wprowadzania danych. Na przykład wszystkie pomiary przed interwencją mogą kończyć się na _pre, a po interwencji na _post.

Jeżeli badanie jest wieloośrodkowe lub wieloetapowe, nazwa może zawierać identyfikator czasu albo ośrodka, na przykład weight_t0, weight_t1 lub site_id. Nie należy jednak kodować w nazwie zbyt wielu informacji. Szczegóły powinny trafić do etykiety i notatek w książce kodowej.

Typ danych a poziom pomiaru

Typ danych mówi, jak wartość jest zapisana, natomiast poziom pomiaru mówi, jak należy ją interpretować. Te pojęcia nie są synonimami.

• Typ liczbowy całkowity obejmuje na przykład liczbę hospitalizacji, liczbę dzieci lub kod kategorii.
• Typ liczbowy dziesiętny obejmuje na przykład ciśnienie tętnicze, masę ciała lub wynik BMI.
• Typ tekstowy może przechowywać nazwę ośrodka, komentarz albo kod alfanumeryczny.
• Typ daty i czasu powinien mieć ustalony format, np. 2026-09-11 dla daty ISO.

Poziom pomiaru może być nominalny, porządkowy, przedziałowy lub ilorazowy. W praktyce programów statystycznych często spotyka się uproszczony podział na zmienne nominalne, porządkowe i ciągłe. Nie należy jednak przypisywać poziomu wyłącznie na podstawie tego, że kody są liczbami. Kod 1 = kobieta i 2 = mężczyzna jest liczbowy technicznie, ale nominalny statystycznie. Średnia z takich kodów nie ma sensownej interpretacji.

W Jamovi należy osobno określić typ danych oraz typ pomiaru. Program rozróżnia między innymi dane typu integer, decimal i text oraz pomiar nominalny, porządkowy i ciągły (jamovi, 2026). W SPSS analogiczna decyzja jest zapisywana w atrybucie „Measure”. W R informacja o poziomie pomiaru często wynika z klasy obiektu, na przykład factor, ordered lub numeric, ale nie jest automatycznie równoważna z oceną metodologiczną badacza.

Kody wartości i etykiety

Kod jest wartością zapisaną w bazie, a etykieta wartości jest jej opisem. Przykład:

Kod	Etykieta
0	Nie
1	Tak

W przypadku zmiennej nominalnej kolejność kodów nie ma znaczenia merytorycznego. Można użyć 0/1, 1/2 albo innych kodów, o ile zasada jest opisana i stosowana konsekwentnie. Dla zmiennej porządkowej kodowanie powinno odzwierciedlać naturalny porządek, na przykład:

Kod	Etykieta
1	Brak trudności
2	Trudność łagodna
3	Trudność umiarkowana
4	Trudność znaczna

Warto odróżniać etykietę zmiennej od etykiety wartości. „Palenie tytoniu” jest etykietą zmiennej, natomiast „0 = nie” i „1 = tak” są etykietami wartości. Pomieszanie tych dwóch poziomów utrudnia interpretację wyników i import metadanych.

Braki danych w książce kodowej

Brak danych nie jest jedną kategorią. W zależności od procedury może oznaczać: brak odpowiedzi, odmowę odpowiedzi, „nie wiem”, pytanie nieadekwatne albo błąd pomiaru. Jeżeli wszystkie te sytuacje otrzymają jeden kod, tracimy informację o przyczynie braku.

Przykładowy schemat może wyglądać następująco:

• 97 = nie dotyczy,
• 98 = odmowa odpowiedzi,
• 99 = nie wiem,
• pusta komórka = brak wpisu w formularzu.

W analizie kody specjalne muszą zostać rozpoznane jako braki danych. W przeciwnym razie wartość 99 może zostać potraktowana jako rzeczywisty wynik wieku, liczby punktów lub ciśnienia. Jamovi wymaga jawnego wskazania, że określona wartość, na przykład 9999, jest brakiem; bez tej definicji program traktuje ją jak zwykłą obserwację (jamovi, 2026). W SPSS kody można zdefiniować jako user-missing values.

W codebooku trzeba również zapisać, czy kod braku jest obecny w danych surowych, czy został już zamieniony na systemowy brak danych. To ważne dla odtwarzalności. Standardy raportowania APA zalecają także podawanie liczby lub odsetka braków oraz sposobu postępowania z nimi (Appelbaum i in., 2018).

Książka kodowa a cztery programy do analiz danych

SPSS

W SPSS podstawowym miejscem odwzorowania książki kodowej jest Variable View. Należy uzupełnić nazwę, typ, etykietę zmiennej, etykiety wartości, kody braków danych i poziom pomiaru. Warto zapisać także plik składni, ponieważ składnia dokumentuje sposób utworzenia etykiet, rekodowania i zmiennych pochodnych.

Jamovi

W Jamovi trzeba zweryfikować Data type i Measure type dla każdej zmiennej. Dla kategorii należy dodać etykiety poziomów i ustawić ich kolejność, szczególnie w zmiennych porządkowych. Braki specjalne trzeba zdefiniować w edytorze zmiennej, ponieważ sam zapis liczbowy nie informuje programu, że dana wartość jest brakiem.

R

W R warto przechowywać dane surowe w pliku tekstowym oraz tworzyć skrypt importu i kontroli jakości. Przykładowo:

dat <- read.csv("badanie.csv", na.strings = c("", "97", "98", "99"))
dat$smoking <- factor(dat$smoking,
                       levels = c(0, 1),
                       labels = c("Nie", "Tak"))

Codebook powinien wyjaśniać, dlaczego wartości 97–99 zostały potraktowane jako braki i dlaczego zmienna smoking została zamieniona na czynnik. Sam skrypt nie zastępuje dokumentacji merytorycznej.

Statistica

W Statistica należy sprawdzić typ zmiennej, definicje braków, etykiety kategorii i sposób interpretacji zmiennej w analizie. Przy eksporcie do CSV warto pamiętać, że część metadanych może nie przejść razem z danymi. Dlatego niezależna książka kodowa powinna być przechowywana obok pliku surowego i pliku analitycznego.

Przykład praktyczny: badanie pacjentów po zabiegu

Załóżmy, że zespół pielęgniarski bada natężenie bólu u pacjentów przed podaniem leku i 60 minut po jego podaniu. Fragment codebooka może wyglądać tak:

Nazwa	Opis	Typ	Poziom	Kody lub zakres
id	Identyfikator uczestnika	integer	nominal	1001–1999
age_years	Wiek w ukończonych latach	integer	ilorazowy	18–99; 99 nie stosować jako brak
pain_pre	Ból przed podaniem leku, skala 0–10	integer	porządkowy	0–10; 98 odmowa
pain_post	Ból 60 minut po podaniu leku	integer	porządkowy	0–10; 97 nie dotyczy
drug_dose_mg	Dawka leku	decimal	ilorazowy	0–1000 mg
pain_change	Zmiana wyniku bólu	decimal	ilorazowy	pain_pre - pain_post

Dla zmiennej pain_change dodatnia wartość oznacza zmniejszenie bólu, zero brak zmiany, a wartość ujemna zwiększenie bólu. Tę regułę trzeba zapisać w książce kodowej, ponieważ sama nazwa może być niewystarczająca. Wzór ma postać:

Δpain = pain_pre − pain_post

• Δpain oznacza zmianę natężenia bólu;
• pain_pre oznacza wynik przed podaniem leku;
• pain_post oznacza wynik 60 minut po podaniu leku.

Jeżeli pacjent miał wynik 8 przed interwencją i 5 po interwencji, Δpain = 3. Nie wolno jednak na tej podstawie automatycznie stwierdzić, że lek spowodował poprawę, jeżeli badanie nie obejmowało odpowiedniej grupy porównawczej lub randomizacji. Książka kodowa opisuje operacjonalizację zmiennej, ale nie rozstrzyga o przyczynowości.

Drugi przykład: kwestionariusz psychologiczny

W badaniu studentów można zastosować 10-itemową skalę stresu, gdzie każda pozycja ma odpowiedzi od 1 do 5. Książka kodowa powinna zawierać osobny wiersz dla każdej pozycji, informację o kierunku punktacji i regułę tworzenia wyniku ogólnego.

Zmienna	Opis	Kody	Uwagi
stress_01	Czuję się przeciążony obowiązkami	1–5	Wyższy kod = większy stres
stress_02	Mam poczucie kontroli nad sytuacją	1–5	Pozycja odwrócona
stress_02_r	Odwrócony wynik pozycji 2	1–5	6 - stress_02
stress_total	Suma lub średnia pozycji po rekodowaniu	10–50 lub 1–5	Dokładna reguła musi być zapisana

Jeśli odwracana jest skala od 1 do 5, wzór ma postać xr = 6 − x, gdzie x jest pierwotną odpowiedzią, a xr wynikiem po odwróceniu. Dla odpowiedzi 1 wynik po rekodowaniu wynosi 5, dla 2 wynosi 4, a dla 5 wynosi 1. Codebook powinien wskazywać, czy wynik ogólny jest sumą, średnią czy inną kompozycją pozycji. Nie należy nazywać zmiennej „wynikiem stresu”, jeśli nie opisano sposobu jej wyliczenia.

Kontrola jakości codebooka

Przed rozpoczęciem analizy wykonaj kontrolę w czterech etapach.

1. Kontrola kompletności: każda kolumna danych ma odpowiadający jej wiersz w codebooku.
2. Kontrola zgodności: nazwy w codebooku są identyczne z nazwami w pliku, łącznie z wielkością liter, jeśli program ją rozróżnia.
3. Kontrola zakresów: wartości obserwowane mieszczą się w zakresie dopuszczalnym, a kody specjalne są opisane.
4. Kontrola logiczna: reguły przejścia są spójne, na przykład osoba oznaczona jako „nie ma diagnozy” nie powinna mieć wypełnionych pytań dotyczących leczenia tej diagnozy.

Pomocne jest wygenerowanie tabel częstości dla zmiennych kategorialnych oraz minimum, maksimum i liczby braków dla zmiennych liczbowych. W R można automatyzować takie kontrole skryptem, w SPSS składnią, a w Jamovi funkcjami opisowymi i filtrami. Ważne jest, aby kontrola była powtarzalna, a nie wykonywana wyłącznie ręcznie.

Najczęstsze błędy

• Tworzenie książki kodowej dopiero po analizie. Wtedy część decyzji kodujących może być już nie do odtworzenia.
• Używanie samych skrótów. Nazwa q5 nie informuje, czego dotyczy pytanie.
• Brak informacji o jednostce. Wartość 120 może oznaczać mmHg, minuty, kilogramy albo punkty.
• Traktowanie kodów kategorii jak pomiaru ilościowego. Kod 1, 2, 3 nie zawsze oznacza skalę, na której sensowne jest liczenie średniej.
• Umieszczanie braków danych w zwykłym zakresie. Wiek równy 99 może być prawidłowy w jednej bazie, a oznaczać brak danych w innej.
• Brak rozróżnienia danych surowych i pochodnych. Zmienna obliczona powinna mieć podaną formułę i źródłowe zmienne.
• Wprowadzanie opisów kategorii bez kodów. Program musi wiedzieć, czy „tak” odpowiada 1, 0, czy wartości tekstowej.
• Zapisywanie kilku informacji w jednej komórce. Na przykład „nadciśnienie; cukrzyca” powinno zostać rozbite na osobne zmienne binarne albo ustrukturyzowane kategorie.
• Brak wersjonowania. Zmiana kodowania powinna mieć datę, numer wersji i krótki opis.

Praktyczny przewodnik tworzenia książki kodowej

1. Spisz wszystkie konstrukty i zmienne wynikające z celu badania.
2. Przypisz każdej zmiennej stabilną nazwę techniczną.
3. Dodaj pełną etykietę, źródło i jednostkę.
4. Określ typ danych oraz poziom pomiaru.
5. Zdefiniuj dopuszczalne wartości i etykiety kategorii.
6. Opisz wszystkie kody braków danych.
7. Oddziel zmienne surowe, przekształcone i obliczone.
8. Przetestuj import do docelowego programu.
9. Wygeneruj raport kontroli jakości.
10. Zapisz wersję książki kodowej razem z plikiem danych i skryptem analitycznym.

W ramach szkolenia na statystyk.edu.pl książkę kodową warto traktować jako centralny dokument łączący operacjonalizację zmiennych, organizację bazy i plan analizy. Dzięki temu kolejne osoby nie muszą odgadywać znaczenia kolumn ani rekonstruować decyzji badacza z przypadkowych notatek.

Co warto zapamiętać?

• Książka kodowa jest formalnym opisem struktury i znaczenia zbioru danych.
• Każda zmienna powinna mieć nazwę techniczną, pełną etykietę, typ danych, poziom pomiaru i reguły kodowania.
• Kod liczbowy nie zmienia automatycznie zmiennej kategorialnej w ilościową.
• Braki danych muszą być opisane i prawidłowo zdefiniowane w programie analitycznym.
• Zmienne pochodne wymagają zapisania wzoru oraz zmiennych źródłowych.
• SPSS, Jamovi, R i Statistica różnią się sposobem przechowywania metadanych, dlatego niezależna książka kodowa pozostaje potrzebny.
• Dobra książka kodowa zwiększa przejrzystość, kontrolę jakości i odtwarzalność analiz.

Najprostszy test jakości brzmi: czy osoba, która nie uczestniczyła w zbieraniu danych, potrafi na podstawie kodów poprawnie zaimportować plik, rozpoznać kody braków, odtworzyć zmienne pochodne i przygotować podstawową analizę? Jeśli odpowiedź brzmi „tak”, książka kodów spełnia swoją podstawową funkcję metodologiczną.

Źródła i dalsza lektura

1. Broman, K. W., & Woo, K. H. (2018). Data Organization in Spreadsheets. The American Statistician, 72(1), 2–10. DOI: 10.1080/00031305.2017.1375989.
2. Appelbaum, M., Cooper, H., Kline, R. B., Mayo-Wilson, E., Nezu, A. M., & Rao, S. M. (2018). Journal article reporting standards for quantitative research in psychology: The APA Publications and Communications Board task force report. American Psychologist, 73(1), 3–25. DOI: 10.1037/amp0000191.
3. IBM (2025). Variable View. IBM Documentation: IBM SPSS Statistics. IBM. Źródło.
4. jamovi project (2026). Data Variables. jamovi Documentation. jamovi project. Źródło.
5. American Psychological Association (2024). APA Style Journal Article Reporting Standards. APA Style. American Psychological Association. Źródło.
6. R Core Team (2026). R Data Import/Export: Reading Data from Text Files. R Documentation. R Foundation for Statistical Computing. Źródło.

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