537. Reprodukowalny skrypt analityczny – podstawowe zasady
W poprzednich lekcjach omawiano zalety podejścia skryptowego oraz sposoby kontroli poprawności obliczeń. Kolejnym krokiem jest połączenie tych umiejętności w spójny, reprodukowalny skrypt analityczny. Jego zadaniem nie jest wyłącznie wykonanie testu statystycznego. Dobry skrypt dokumentuje całą drogę od danych wejściowych, przez przygotowanie zbioru i obliczenia, aż do tabel, wykresów oraz wyników przedstawionych w raporcie. Dzięki temu analiza może zostać powtórzona przez autora, współpracownika, recenzenta albo inną osobę korzystającą z tych samych danych i informacji o środowisku obliczeniowym.
W kontekście podręcznika do szkolenia na statystyk.edu.pl warto przyjąć praktyczną zasadę: skrypt powinien być zrozumiały nie tylko dla komputera, lecz także dla człowieka, który za kilka miesięcy będzie chciał ustalić, dlaczego wykonano określone przekształcenie lub wybrano konkretny model.
Czym jest reprodukowalność analizy?
Reprodukowana analiza to taka analiza, w której można ponownie uzyskać te same lub odpowiednio zgodne wyniki, korzystając z określonego zbioru danych, kodu, parametrów oraz środowiska obliczeniowego. Nie oznacza to, że każdy przyszły wynik musi być identyczny co do ostatniego miejsca po przecinku. Różnice mogą wynikać na przykład z odmiennej implementacji algorytmu, zaokrągleń lub wersji bibliotek. Istotne jest natomiast, aby było wiadomo, jakie decyzje doprowadziły do rezultatu i aby można było je ponownie wykonać.
Trzeba odróżnić kilka pojęć:
- powtarzalność przez autora oznacza możliwość ponownego uruchomienia własnej analizy i uzyskania wyników;
- reprodukowanie obliczeń oznacza odtworzenie wyników na podstawie tego samego kodu, danych i środowiska;
- replikacja badania dotyczy ponownego przeprowadzenia badania, często na nowych osobach lub w innych warunkach;
- przejrzystość analizy oznacza możliwość prześledzenia, w jaki sposób dane zostały oczyszczone, przekształcone i przeanalizowane.
Skrypt nie naprawi błędnego projektu badania, nie zastąpi poprawnej operacjonalizacji zmiennych i nie zagwarantuje prawdziwości wniosków. Może jednak ograniczyć liczbę błędów technicznych, ułatwić audyt oraz ujawnić, czy opis w publikacji odpowiada rzeczywistym obliczeniom. W literaturze dotyczącej obliczeń naukowych podkreśla się znaczenie wersjonowania kodu, archiwizowania oprogramowania, dokumentowania danych i automatyzowania kroków analizy (Sandve et al., 2013; Wilson et al., 2017).
Minimalna struktura projektu analitycznego
Najbezpieczniej jest traktować analizę jako projekt, a nie jako pojedynczy plik zapisany na pulpicie. Przykładowa struktura może wyglądać następująco:
badanie_nadcisnienie/
├── data_raw/
├── data_processed/
├── scripts/
├── output_tables/
├── output_figures/
├── report/
├── README.md
└── renv.lock
Katalog data_raw zawiera dane surowe, których nie należy nadpisywać. W data_processed można zapisywać dane po kontrolowanym oczyszczeniu. Katalog scripts przechowuje skrypty, na przykład osobne pliki do importu danych, kontroli jakości, analizy opisowej i modelowania. Tabele i wykresy trafiają do katalogów wynikowych, natomiast raport zawiera dokument lub plik generowany na podstawie obliczeń.
Plik README.md powinien krótko wyjaśniać: cel projektu, źródło danych, znaczenie najważniejszych zmiennych, sposób uruchomienia skryptów, wymagane pakiety oraz ograniczenia analizy. Nie jest to formalność. Dla osoby, która otworzy projekt po roku, README może być ważniejsze niż pamięć autora.
Dlaczego nie należy nadpisywać danych surowych?
Załóżmy, że w kolumnie sex występują wartości „K”, „M”, „kobieta” i „mężczyzna”. Można utworzyć nową, uporządkowaną zmienną, ale nie powinno się usuwać pierwotnych wartości bez śladu. Dane surowe są punktem odniesienia. Jeżeli w wyniku błędnego rekodowania część osób otrzyma nieprawidłową kategorię, możliwość porównania z oryginalnym plikiem ułatwia wykrycie problemu.
Praktyczna reguła brzmi: surowe dane są tylko do odczytu, a każde przekształcenie powinno być zapisane w kodzie. Ręczna korekta arkusza może być czasem konieczna, ale powinna zostać opisana i, jeśli to możliwe, zastąpiona jawną instrukcją w skrypcie.
Elementy dobrego skryptu
1. Nagłówek i opis celu
Na początku pliku warto umieścić komentarz zawierający nazwę projektu, autora, datę utworzenia, cel skryptu oraz oczekiwane pliki wyjściowe. Data nie zastępuje systemu kontroli wersji, ale ułatwia orientację w projekcie.
# Projekt: kontrola ciśnienia tętniczego
# Cel: opis pacjentów i porównanie średniego SBP między grupami
# Dane wejściowe: data_raw/pacjenci.csv
# Wyniki: output_tables/tabela1.csv
2. Jawne ustawienie katalogu projektu
Skrypt nie powinien zależeć od tego, gdzie znajduje się komputer autora. W RStudio można korzystać z projektu RStudio i odwoływać się do plików względnie, na przykład data_raw/pacjenci.csv, zamiast wpisywać pełną ścieżkę typu C:/Users/Anna/Desktop/badanie/pacjenci.csv. Ścieżki bezwzględne często przestają działać po przeniesieniu projektu na inny komputer.
3. Kontrola pakietów i wersji
Sam zapis nazwy pakietu może nie wystarczyć, ponieważ pakiety zmieniają się w czasie. W R można wykorzystać narzędzie renv, które zapisuje informacje o zależnościach projektu w pliku blokady i ułatwia odtworzenie środowiska na innym komputerze. Funkcje renv::snapshot() i renv::restore() służą odpowiednio do zapisania oraz odtworzenia stanu pakietów. Narzędzie to nie rozwiązuje wszystkich problemów, ponieważ nie przechowuje automatycznie całej wersji systemu operacyjnego ani każdego elementu infrastruktury (renv documentation, 2026).
4. Kolejność kroków
Skrypt powinien być wykonywany od początku do końca bez ręcznego poprawiania obiektów w środowisku pracy. Sensowny układ obejmuje:
- załadowanie pakietów;
- import danych;
- kontrolę nazw, typów i braków danych;
- przygotowanie zmiennych;
- analizę opisową;
- analizę główną;
- diagnostykę i analizę wrażliwości, jeżeli jest potrzebna;
- zapis tabel, wykresów i komunikatów.
Jeżeli uruchomienie sekcji dotyczącej modelu wymaga wcześniejszego ręcznego kliknięcia w programie, analiza nie jest jeszcze w pełni reprodukowalna.
5. Kontrole jakości danych
Kontrola jakości powinna poprzedzać właściwe testy. Należy sprawdzić między innymi liczbę obserwacji, duplikaty identyfikatorów, zakresy wartości, typy zmiennych, nieoczekiwane kategorie oraz braki danych. W badaniu medycznym można sprawdzić, czy wiek mieści się w zaplanowanym zakresie, czy skurczowe ciśnienie tętnicze nie zostało zapisane jako ujemne oraz czy data pomiaru nie przypada po dacie wypisu.
Kontrola zakresu nie oznacza automatycznego usuwania obserwacji odstających. Wartość 250 mmHg może być błędem wpisu, ale może też oznaczać ciężki stan kliniczny. Skrypt powinien wykryć obserwację i oznaczyć ją do weryfikacji, a decyzję o wykluczeniu należy uzasadnić.
Przykład 1: badanie pacjentów z nadciśnieniem
Załóżmy, że zespół analizuje dane 240 pacjentów poradni. Zmiennymi są: id, age, sex, sbp oraz treatment_group. Celem jest opisanie średniego skurczowego ciśnienia tętniczego w dwóch grupach leczenia.
Najpierw skrypt powinien sprawdzić liczbę wierszy i unikalność identyfikatorów:
data <- read.csv("data_raw/pacjenci.csv")
stopifnot(nrow(data) == 240)
stopifnot(!anyDuplicated(data$id))
Instrukcja stopifnot() zatrzyma wykonywanie analizy, jeżeli warunek nie jest spełniony. To ważne zabezpieczenie: jeżeli plik zawiera 239 osób zamiast 240, skrypt nie powinien po cichu wygenerować tabeli, która będzie później traktowana jako poprawna.
Następnie można zdefiniować zmienną grupującą oraz sprawdzić jej kategorie:
data$treatment_group <- factor(data$treatment_group)
print(table(data$treatment_group, useNA = "ifany"))
summary(data$sbp)
Wynik należy interpretować razem z informacją o brakach danych. Jeżeli pomiar SBP jest niedostępny u części pacjentów, liczebność użyta w opisie może być mniejsza niż ogólna liczba osób w bazie. Tę różnicę trzeba później jasno pokazać w tabeli lub tekście.
Jeżeli porównywane są średnie, skrypt powinien zapisać nie tylko wartość p, lecz także różnicę średnich i przedział ufności. Ogólny zapis przedziału ufności dla różnicy średnich można przedstawić jako:
oszacowanie ± wartość krytyczna × błąd standardowy
gdzie oszacowanie jest obserwowaną różnicą średnich, wartość krytyczna zależy od przyjętego poziomu ufności i rozkładu statystyki, a błąd standardowy opisuje niepewność oszacowania. Przedział nie jest gwarancją, że prawdziwa różnica znajduje się w tym konkretnym przedziale. Jest procedurą, która przy wielokrotnym zastosowaniu ma określoną częstość pokrycia przy założeniach danego modelu.
W raporcie nie należy pisać: „p = 0,03 oznacza 97% prawdopodobieństwa, że hipoteza zerowa jest fałszywa”. Wartość p nie jest prawdopodobieństwem prawdziwości hipotezy zerowej. Informuje, jak zgodne z hipotezą zerową są dane lub wynik co najmniej tak odległy od niej, przy założeniu modelu i hipotezy zerowej. Zgodnie z dobrymi praktykami raportowania należy podać metodę, oszacowanie, miarę niepewności i – w razie potrzeby – wielkość efektu (Lang i Altman, 2015).
Przykład 2: skala lęku w badaniu psychologicznym
W drugim przykładzie badacz analizuje skalę lęku złożoną z dziesięciu pozycji ocenianych od 1 do 5. Część pozycji jest sformułowana odwrotnie. Reprodukowany skrypt powinien jasno pokazać, które pozycje są rekodowane i według jakiej reguły.
Dla skali od 1 do 5 pozycję odwrotną można przekształcić według wzoru:
xodwrócone = 6 − xoryginalne
Symbol xoryginalne oznacza pierwotną odpowiedź respondenta, a xodwrócone – wartość po rekodowaniu. Liczba 6 wynika z sumy minimalnej i maksymalnej wartości skali powiększonej o jeden: 1 + 5. Odpowiedź 1 staje się 5, odpowiedź 2 staje się 4, a odpowiedź 5 staje się 1.
data$item4_r <- 6 - data$item4
data$item7_r <- 6 - data$item7
items <- data[c("item1", "item2", "item3", "item4_r", "item5", "item6", "item7_r", "item8", "item9", "item10")]
data$anxiety_score <- rowMeans(items, na.rm = FALSE)
Ustawienie na.rm = FALSE powoduje, że wynik skali będzie brakujący, jeżeli respondent nie odpowiedział na co najmniej jedną pozycję. To tylko jedna z możliwych reguł. Można dopuścić brak jednej lub dwóch odpowiedzi i obliczać średnią z pozostałych pozycji, ale taka decyzja musi wynikać z planu badania, właściwości narzędzia lub uzasadnionej procedury, a nie z przypadkowego zachowania funkcji.
Skrypt powinien także zapisać definicję wyniku: czy jest to suma, średnia, wynik standaryzowany, czy wynik przeliczony według norm. Nie wystarczy nazwa score. Osoba analizująca dane powinna wiedzieć, co dokładnie oznacza każda jednostka wyniku i jaki jest jego zakres.
Dokumentowanie decyzji analitycznych
Nie wszystkie decyzje da się odczytać z samego kodu. W komentarzach lub pliku README warto wyjaśnić:
- dlaczego wybrano określony sposób kodowania braków danych;
- kiedy obserwację uznano za niespełniającą kryteriów włączenia;
- dlaczego zastosowano transformację zmiennej;
- czy analiza była zaplanowana przed obejrzeniem wyników;
- które wyniki są główne, a które eksploracyjne;
- jak potraktowano wielokrotne testowanie lub dane odstające.
Warto oddzielić kod od interpretacji. Skrypt może obliczyć różnicę między grupami, ale zdanie „interwencja poprawiła stan pacjentów” wymaga odpowiedniego schematu badania, kontroli czynników zakłócających i ostrożnego języka przyczynowego. W badaniu obserwacyjnym bez właściwej kontroli nie należy zamieniać związku statystycznego w twierdzenie o skutku leczenia.
Najczęstsze błędy
- Nadpisywanie pliku z danymi. Uniemożliwia ustalenie, które wartości były pierwotne, a które zostały zmienione.
- Ręczne wybieranie obserwacji. Filtrowanie w arkuszu bez zapisania reguły może prowadzić do niewidocznych różnic między kolejnymi wersjami analizy.
- Brak ustawienia ziarna losowania. Algorytmy wykorzystujące losowanie, na przykład bootstrap lub podział danych na próbę uczącą i testową, mogą dawać różne wyniki. Należy zapisać użyte ziarno, na przykład
set.seed(1234), oraz opisać jego zastosowanie. - Wybieranie wyników po fakcie. Uruchamianie wielu modeli i prezentowanie wyłącznie tego, który dał najmniejszą wartość p, zwiększa ryzyko optymistycznego obrazu wyników.
- Brak kontroli liczebności. Tabela może wyglądać poprawnie, mimo że przez braki danych poszczególne analizy opierają się na różnych grupach osób.
- Niejasne nazwy obiektów. Nazwy
a,test2ifinal_finalutrudniają audyt. Lepsze są nazwydata_analysis,table_baselinelubmodel_logistic_primary. - Zapisywanie tylko końcowego pliku. Sam wykres lub tabela nie pozwala sprawdzić, z jakich danych i poleceń powstały.
- Założenie, że skrypt zawsze jest bezbłędny. Reprodukowanie tego samego błędu nie czyni wyniku poprawnym. Kod musi być sprawdzany logicznie i merytorycznie.
Przykład praktyczny: od danych do raportu
Wyobraźmy sobie badanie pielęgniarek dotyczące zmęczenia zawodowego. Zespół ma dane ankietowe, zmienną dotyczącą liczby godzin pracy oraz oddział, na którym pracuje respondent. Analiza może zostać podzielona na cztery skrypty:
01_import_check.R– import, kontrola typów, zakresów i braków;02_prepare_variables.R– rekodowanie pozycji i obliczenie skali;03_descriptive_analysis.R– charakterystyka próby i wykresy;04_primary_model.R– model zaplanowany w protokole badania.
Każdy skrypt może zapisywać wynik pośredni, ale powinien działać w przewidywalnej kolejności. Po zmianie reguły obliczania skali uruchamia się całość od początku, a nie tylko ostatnią sekcję. Taki workflow umożliwia sprawdzenie, czy zmiana wpłynęła na wszystkie tabele i wykresy.
Raport generowany z kodu może zawierać opis liczebności, średnią i odchylenie standardowe, medianę i kwartyle, a także oszacowania modelu z przedziałami ufności. W tekście należy podać dokładnie, jakie dane wykorzystano, jak zdefiniowano wynik oraz które obserwacje weszły do modelu. Wytyczne SAMPL są pomocnym punktem odniesienia dla raportowania podstawowych analiz statystycznych, ale nie zastępują wytycznych właściwych dla projektu badania, takich jak STROBE dla badań obserwacyjnych czy CONSORT dla badań randomizowanych (Lang i Altman, 2015).
Jak zwiększać reprodukowalność krok po kroku?
Nie trzeba od razu budować skomplikowanego systemu z kontenerami, automatycznym serwerem i zaawansowanym testowaniem. Rozsądny plan minimalny obejmuje:
- utworzenie jednego katalogu projektu;
- zachowanie danych surowych bez nadpisywania;
- zapisanie każdego przekształcenia w skrypcie;
- stosowanie opisowych nazw plików i obiektów;
- dodanie README z instrukcją uruchomienia;
- używanie systemu kontroli wersji, na przykład Git;
- zapisanie wersji głównego programu i pakietów;
- sprawdzenie, czy osoba niezależna może uruchomić projekt.
W praktyce reprodukowalność jest cechą całego workflow, a nie pojedynczej funkcji. Obejmuje dane, kod, dokumentację, środowisko, sposób zapisu wyników i decyzje interpretacyjne. Współczesne opracowania wskazują na znaczenie kilku filarów: literate programming, kontroli wersji, kontroli środowiska obliczeniowego, trwałego przechowywania danych oraz dokumentacji (Ziemann, Poulain i Bora, 2023). Notebooki obliczeniowe mogą łączyć tekst, kod i wyniki, ale także one wymagają uporządkowania, kontroli kolejności wykonywania komórek i archiwizacji (Figueiredo et al., 2022).
Co warto zapamiętać?
- Reprodukowany skrypt pozwala odtworzyć drogę od danych do wyników, a nie tylko ponownie wykonać pojedynczy test.
- Dane surowe należy chronić przed nadpisaniem, a każde przekształcenie zapisywać jawnie w kodzie.
- Projekt powinien mieć logiczną strukturę katalogów, plik README i jednoznaczne nazwy obiektów.
- Kontrola jakości danych musi poprzedzać analizę główną.
- Należy dokumentować decyzje dotyczące braków danych, rekodowania, obserwacji odstających i wyboru modelu.
- Wersjonowanie kodu oraz środowiska ogranicza ryzyko, że późniejsza aktualizacja zmieni wynik.
- Wartości p nie są prawdopodobieństwami prawdziwości hipotez; trzeba rozdzielać istotność statystyczną, wielkość efektu i znaczenie praktyczne.
- Reprodukowalność nie gwarantuje poprawności merytorycznej. Kod może wiernie odtwarzać niewłaściwą decyzję lub błąd.
Najlepszym testem jakości skryptu jest próba przekazania projektu innej osobie. Jeżeli potrafi ona zrozumieć dane, uruchomić analizę i odnaleźć źródło każdej tabeli bez dodatkowych ustnych wyjaśnień, projekt spełnia podstawowy standard reprodukowalności.
Źródła i dalsza lektura
- Sandve, Geir Kjetil; Nekrutenko, Anton; Taylor, James; Hovig, Eivind (2013). Ten Simple Rules for Reproducible Computational Research. PLoS Computational Biology, 9(10), e1003285. DOI: 10.1371/journal.pcbi.1003285.
- Wilson, Greg; Bryan, Jennifer; Cranston, Karen; Kitzes, Justin; Nederbragt, Lex; Teal, Tracy K. (2017). Good enough practices in scientific computing. PLoS Computational Biology, 13(6), e1005510. DOI: 10.1371/journal.pcbi.1005510.
- Ziemann, Mark; Poulain, Pierre; Bora, Anusuiya (2023). The five pillars of computational reproducibility: bioinformatics and beyond. Briefings in Bioinformatics, 24(6), bbad375. DOI: 10.1093/bib/bbad375.
- Figueiredo, Ludmilla; et al. (2022). A simple kit to use computational notebooks for more openness, reproducibility, and productivity in research. PLoS Computational Biology, 18(9), e1010356. DOI: 10.1371/journal.pcbi.1010356.
- Lang, Thomas A.; Altman, Douglas G. (2015). Basic statistical reporting for articles published in biomedical journals: the “Statistical Analyses and Methods in the Published Literature” or the SAMPL Guidelines. International Journal of Nursing Studies, 52(1), 5–9. DOI: 10.1016/j.ijnurstu.2014.09.006.
- Posit Software, PBC; Ushey, Kevin; Wickham, Hadley (2026). renv: Project Environments. R package version 1.3.1. Comprehensive R Archive Network. CRAN. Źródło.