539. Archiwizacja składni, logów i plików wynikowych
W poprzednich lekcjach omówiono znaczenie skryptów, wersji oprogramowania oraz kontroli obliczeń. Kolejnym krokiem jest takie uporządkowanie materiałów, aby po kilku tygodniach lub miesiącach można było odpowiedzieć na trzy pytania: jak wykonano analizę, na jakich danych ją przeprowadzono i z którego przebiegu obliczeń pochodzi konkretny wynik? Temu służy archiwizacja składni, logów i plików wynikowych. Nie jest ona wyłącznie czynnością techniczną. Stanowi element rzetelności metodologicznej, kontroli jakości i odpowiedzialnego raportowania wyników.
1. Czym jest archiwizacja analizy statystycznej?
Archiwizacja analizy statystycznej to zaplanowane przechowywanie wszystkich informacji potrzebnych do zrozumienia, sprawdzenia i — w miarę możliwości — ponownego wykonania analizy. Obejmuje nie tylko końcową tabelę w artykule, lecz także materiały pośrednie: dane wejściowe, składnię, pliki dziennika, definicje zmiennych, decyzje analityczne oraz wersje wyników.
W praktyce archiwum analizy może zawierać:
- oryginalny, niezmieniony plik danych;
- plik danych po anonimizacji lub przygotowaniu do analizy;
- składnię programu, na przykład plik
.sps,.R,.dolub.omv; - log z wykonania poleceń i komunikatów programu;
- pliki wynikowe, takie jak raporty HTML, PDF, DOCX, TXT lub pliki projektu;
- opis zmiennych, kodów braków danych i zastosowanych rekodowań;
- notatnik decyzji analitycznych;
- informację o wersji programu, pakietów i systemu operacyjnego;
- sumy kontrolne lub identyfikatory wersji plików, jeśli projekt tego wymaga.
Ważne jest rozróżnienie między archiwizacją a zwykłym wykonaniem kopii zapasowej. Kopia zapasowa chroni przede wszystkim przed utratą pliku. Archiwizacja naukowa ma dodatkowy cel: zachować kontekst, kolejność działań i uzasadnienie decyzji. Sam plik z tabelą „wyniki końcowe.xlsx” nie pozwala ustalić, z jakich danych i za pomocą jakich procedur tabela powstała.
2. Trzy podstawowe elementy dokumentacji
2.1. Składnia, czyli zapis poleceń
Składnia to zapis poleceń, funkcji, ustawień i procedur użytych do przygotowania danych oraz wykonania analizy. W programach opartych na kodzie jest to zwykle plik tekstowy. W programach z interfejsem graficznym składnia może być generowana automatycznie, wpisywana ręcznie albo zastępowana przez plik projektu zawierający ustawienia analizy.
Dobra składnia powinna być:
- czytelna dla innej osoby;
- podzielona na logiczne etapy;
- opatrzona komentarzami wyjaśniającymi cel operacji;
- pozbawiona niepotrzebnych, przypadkowych poleceń;
- powiązana z konkretną wersją danych i programem.
Przykładowy podział składni może wyglądać następująco:
- import danych;
- kontrola typów zmiennych i zakresów wartości;
- rekodowanie oraz tworzenie wskaźników;
- opis braków danych;
- analizy opisowe;
- analiza główna;
- analizy dodatkowe i wrażliwości;
- eksport tabel oraz wykresów.
Taki układ odpowiada idei przepływu analitycznego: od danych surowych, przez przygotowanie, do wyniku końcowego. Sandve i współpracownicy (2013) podkreślają, że dla każdego wyniku powinno być możliwe prześledzenie drogi prowadzącej od danych wejściowych przez kolejne operacje do końcowej prezentacji.
2.2. Log, czyli zapis wykonania analizy
Log jest dziennikiem wykonania programu. Może zawierać uruchomione polecenia, ostrzeżenia, błędy, komunikaty o liczbie obserwacji oraz rezultaty procedur. W zależności od programu log może być osobnym plikiem tekstowym, częścią raportu albo elementem projektu.
Składnia mówi, co zaplanowano lub uruchomiono, natomiast log pokazuje, co wydarzyło się podczas wykonania. To rozróżnienie ma znaczenie. Polecenie może być prawidłowe, lecz program może zwrócić ostrzeżenie o nieistniejącej zmiennej, usunięciu obserwacji albo problemie z konwergencją modelu.
Log powinien być zachowywany szczególnie wtedy, gdy:
- analiza obejmuje wiele etapów;
- stosowane są modele wymagające iteracyjnych obliczeń;
- program może automatycznie wykluczać obserwacje;
- wykorzystywane są zewnętrzne pakiety lub makra;
- analiza ma zostać poddana audytowi, recenzji albo kontroli zespołowej.
Nie należy traktować logu jako dokumentu, który można bezrefleksyjnie dołączyć do publikacji. Może zawierać ścieżki dostępu, identyfikatory, fragmenty danych lub komunikaty techniczne. Przed udostępnieniem trzeba sprawdzić, czy nie ujawnia informacji poufnych.
2.3. Pliki wynikowe
Pliki wynikowe to wszystkie produkty analizy: tabele, wykresy, raporty, zestawienia diagnostyczne, macierze korelacji, wyniki modeli oraz pliki eksportowane z programu. Warto rozróżniać pliki robocze od plików przeznaczonych do publikacji.
Przykładowe nazwy:
01_opis_proby_v01.html— pierwsza wersja wyników opisowych;02_model_logistyczny_v03.html— trzecia wersja modelu;tabela_2_wyniki_final_do_manuskryptu.docx— tabela przygotowana do tekstu;wykres_3_analiza_wrazliwosci_2026-11-10.pdf— wykres z datą wykonania.
Określenie „final” powinno być stosowane ostrożnie. W praktyce często powstają pliki final2, final_poprawiony i final_ostateczny, co zwiększa ryzyko pomyłki. Lepszym rozwiązaniem jest numer wersji, data albo system kontroli wersji. Stoudt, Vásquez i Martinez (2021) zwracają uwagę, że dokumentacja powinna obejmować także racjonalne uzasadnienie decyzji analitycznych, a nie tylko same pliki wykonywalne.
3. Proponowana struktura folderu projektu
Prosty projekt badawczy można uporządkować w następujący sposób:
projekt_badanie_2026/
├── README.txt
├── dane_raw/
├── dane_analiza/
├── skladnia/
├── logi/
├── wyniki_robocze/
├── wyniki_publikacja/
├── dokumentacja/
└── archiwum/
Folder dane_raw powinien zawierać dane pierwotne w stanie niezmienionym, o ile jest to prawnie i etycznie dopuszczalne. W dane_analiza umieszcza się dane po anonimizacji i przygotowaniu. Folder skladnia przechowuje pliki z poleceniami, a logi — dzienniki wykonania. W wyniki_robocze można zachować produkty pośrednie, natomiast wyniki_publikacja powinien zawierać tylko pliki wykorzystane w raporcie lub manuskrypcie.
Plik README powinien krótko opisywać:
- cel projektu;
- osobę odpowiedzialną za analizę;
- datę ostatniej aktualizacji;
- wersję programu;
- kolejność uruchamiania skryptów;
- znaczenie najważniejszych folderów;
- ograniczenia w dostępie do danych.
W dużych projektach korzystne może być użycie systemu kontroli wersji, na przykład Git. Nie zastępuje on kopii zapasowej ani zarządzania danymi wrażliwymi, ale pozwala śledzić zmiany w składni i odtworzyć wcześniejszą wersję pliku.
4. Archiwizacja a poufność danych
W badaniach medycznych, pielęgniarskich i psychologicznych archiwizacja musi uwzględniać ochronę danych osobowych. Nie wolno przechowywać w publicznym repozytorium bezpośrednich identyfikatorów pacjentów, numerów dokumentacji, dokładnych dat zdarzeń lub kombinacji zmiennych umożliwiających identyfikację osoby.
Należy oddzielić:
- identyfikatory bezpośrednie, takie jak imię, nazwisko lub numer PESEL;
- identyfikatory pośrednie, na przykład mała miejscowość, rzadkie rozpoznanie i dokładny wiek;
- materiał analityczny, który może być zanonimizowany lub spseudonimizowany.
Archiwizacja nie oznacza automatycznie publicznego udostępniania wszystkich danych. Można udostępnić składnię, opis zmiennych i przykładowy, sztucznie wygenerowany zbiór danych, a dostęp do danych rzeczywistych ograniczyć zgodnie z zgodą komisji bioetycznej, regulaminem instytucji i obowiązującymi przepisami.
5. Przykład 1: badanie pacjentów po interwencji pielęgniarskiej
Załóżmy, że zespół ocenia zmianę nasilenia bólu u 86 pacjentów przed i po interwencji edukacyjnej. Wyniki są zapisywane w skali od 0 do 10. Analiza obejmuje opis rozkładu, porównanie pomiarów zależnych oraz przedział ufności dla średniej różnicy.
W archiwum powinny znaleźć się:
- plik z danymi surowymi, przechowywany w bezpiecznym miejscu;
- anonimowy plik analityczny z identyfikatorem badania zamiast danych osobowych;
- składnia definiująca, że różnica jest obliczana jako
ból_po - ból_przed; - log pokazujący liczbę kompletnych par obserwacji;
- wynik testu, oszacowanie wielkości różnicy i 95% przedział ufności;
- notatka wyjaśniająca, dlaczego osoby bez obu pomiarów nie zostały uwzględnione w analizie par;
- wersja tabeli wykorzystana w raporcie.
Jeśli w raporcie znajdzie się informacja, że średni ból zmniejszył się o 1,4 punktu, osoba kontrolująca analizę powinna móc sprawdzić, czy wynik dotyczy wszystkich 86 osób, czy tylko osób z kompletnymi pomiarami. Log oraz składnia pozwalają odtworzyć tę informację. Sama tabela w dokumencie nie daje takiej pewności.
6. Przykład 2: modelowanie ryzyka ponownego przyjęcia do szpitala
W drugim projekcie analizuje się, czy wiek, liczba chorób współistniejących i długość hospitalizacji wiążą się z ponownym przyjęciem pacjenta w ciągu 30 dni. Zmienną zależną jest wynik binarny: 0 — brak ponownego przyjęcia, 1 — ponowne przyjęcie.
W tym przypadku szczególnie ważne jest zachowanie:
- definicji punktu końcowego;
- reguł kodowania wartości brakujących;
- listy obserwacji wyłączonych z modelu;
- kolejności wprowadzania zmiennych;
- informacji o problemach z konwergencją;
- wersji pakietów użytych do estymacji modelu;
- pełnego wyniku modelu, a nie tylko tabeli z ilorazami szans.
Przydatne jest zapisanie wzoru modelu w dokumentacji:
logit(pi) = β0 + β1X1i + β2X2i + β3X3i
gdzie pi oznacza prawdopodobieństwo ponownego przyjęcia dla osoby i, logit(pi) jest logitem tego prawdopodobieństwa, β0 to wyraz wolny, β1, β2 i β3 są współczynnikami modelu, a X1i, X2i i X3i oznaczają wartości predyktorów dla osoby i.
Archiwum powinno umożliwiać ustalenie, czy na przykład „wiek” był analizowany w latach jako zmienna ciągła, czy podzielony na kategorie. Taka informacja wpływa na interpretację współczynnika i nie może być pozostawiona wyłącznie domysłom czytelnika.
7. Przykład praktyczny: minimalny protokół archiwizacji
Przed zamknięciem analizy zespół może zastosować następującą procedurę:
- Skopiować dane surowe do bezpiecznego archiwum, bez ich nadpisywania.
- Zapisać wersję danych przeznaczoną do analizy oraz opis wszystkich przekształceń.
- Uruchomić składnię od początku na zapisanej wersji danych.
- Sprawdzić log pod kątem błędów, ostrzeżeń i liczebności.
- Porównać kluczowe wyniki z tabelami w manuskrypcie.
- Usunąć z plików przeznaczonych do udostępnienia informacje identyfikujące.
- Zapisać datę wykonania, wersję programu i osobę odpowiedzialną.
- Utworzyć nieedytowalny pakiet archiwalny, na przykład w formacie ZIP, oraz zachować jego kopię w innym miejscu.
Dobrym testem jest przekazanie kopii projektu drugiej osobie z zespołu. Jeżeli nie potrafi ona ustalić, jak powstał główny wynik, dokumentacja jest niewystarczająca. Mang, Prokosch i Kapsner (2023) wskazują, że reprodukowalność wymaga spójnego przejścia od analizy danych do przygotowania wyników i manuskryptu, a nie tylko zachowania pojedynczego skryptu.
8. Najczęstsze błędy
- Nadpisywanie plików. Zastąpienie wcześniejszej wersji danych lub składni uniemożliwia ustalenie, kiedy powstała zmiana.
- Zapisywanie wyłącznie końcowej tabeli. Tabela nie pokazuje reguł selekcji, braków danych ani diagnostyki modelu.
- Brak logu. Bez logu można nie zauważyć ostrzeżeń, automatycznych wykluczeń lub nieudanych procedur.
- Niejasne nazwy plików. Nazwy typu
analiza_nowa2_final.xlsxsą mniej użyteczne niż nazwa zawierająca etap, wersję i datę. - Ręczne poprawianie wyników. Przepisywanie liczb z programu do arkusza zwiększa ryzyko błędów i zrywa ślad audytowy.
- Brak opisu decyzji analitycznych. Sama składnia może nie wyjaśniać, dlaczego wybrano określony model lub sposób kodowania.
- Przechowywanie danych wrażliwych razem z wynikami. Pliki wynikowe, logi i zrzuty ekranu mogą zawierać informacje umożliwiające identyfikację.
- Brak kontroli zgodności. Wyniki w manuskrypcie mogą pochodzić z innej wersji analizy niż wyniki zapisane w archiwum.
- Brak informacji o środowisku. Ta sama składnia może dawać odmienne rezultaty po zmianie wersji pakietu lub programu.
9. Jak archiwizacja wspiera raportowanie naukowe?
Standardy APA JARS zalecają przedstawianie informacji umożliwiających ocenę metod, danych, wykluczeń i analiz. Archiwum nie jest tożsame z artykułem, ale ułatwia przygotowanie kompletnego raportu. Dzięki niemu można dokładnie opisać liczebność analizowanej próby, zastosowane procedury, wartości brakujące, analizy dodatkowe oraz ewentualne odstępstwa od planu.
Wytyczne dotyczące raportowania, takie jak JARS, STROBE czy CONSORT, nie nakazują identycznego systemu folderów. Ich wspólny cel jest jednak podobny: zwiększenie przejrzystości i możliwości oceny procesu badawczego. Warto więc już na etapie analizy prowadzonej w ramach publicznego szkolenia na statystyka.edu.pl przyjąć zasadę, że każdy ważny wynik powinien mieć swój ślad w składni, logu albo dokumentacji decyzji.
Archiwizacja zwiększa także odporność projektu na rotację członków zespołu. Jeżeli analizę prowadziła jedna osoba, uporządkowane materiały pozwalają innej osobie przejąć projekt bez odtwarzania całej historii z pamięci i przypadkowych plików.
Co warto zapamiętać?
- Archiwizacja analizy statystycznej obejmuje dane, składnię, logi, wyniki i dokumentację decyzji.
- Składnia pokazuje procedurę, a log pokazuje przebieg jej wykonania.
- Plik wynikowy bez informacji o danych wejściowych i sposobie analizy ma ograniczoną wartość kontrolną.
- Wersjonowanie plików jest bezpieczniejsze niż nadpisywanie poprzednich wersji.
- W badaniach medycznych i społecznych trzeba oddzielać reprodukowalność od nieuprawnionego udostępniania danych wrażliwych.
- Każdy główny wynik powinien być możliwy do prześledzenia od danych wejściowych do tabeli lub wykresu.
- Archiwum powinno pozwalać innej osobie zrozumieć analizę bez konieczności odtwarzania jej z pamięci autora.
Źródła i dalsza lektura
- Sandve, G. K., Nekrutenko, A., Taylor, J., & Hovig, E. (2013). Ten Simple Rules for Reproducible Computational Research. PLoS Computational Biology, 9(10), e1003285. DOI: 10.1371/journal.pcbi.1003285.
- Stoudt, S., Vásquez, V. N., & Martinez, C. (2021). Principles for Data Analysis Workflows. PLoS Computational Biology, 17(3), e1008770. DOI: 10.1371/journal.pcbi.1008770.
- Mang, J. M., Prokosch, H.-U., & Kapsner, L. A. (2023). Reproducibility in 2023 – An End-to-End Template for Analysis and Manuscript Writing. Studies in Health Technology and Informatics, 302, 58–62. DOI: 10.3233/SHTI230064.
- Kim, Y.-M., Poline, J.-B., & Dumas, G. (2018). Experimenting with Reproducibility: A Case Study of Robustness in Bioinformatics. GigaScience, 7(7), giy077. DOI: 10.1093/gigascience/giy077.
- American Psychological Association (2024). APA Style Journal Article Reporting Standards (JARS). APA Style. American Psychological Association. Źródło.
Więcej kolejnych lekcji publicznego szkolenia znajdziesz na statystyk.edu.pl.
Jeżeli potrzebujesz indywidualnego wsparcia w doborze metod, przygotowaniu bazy lub opracowaniu wyników badań, sprawdź analiza statystyczna.