Reprodukowalny pipeline neuroinformatyczny: zbuduj łańcuch dowodowy wyniku
Sposób wersjonowania wejść, konfiguracji, zależności, kontenerów, testów i manifestów tak, aby wynik dało się ponownie wygenerować.
Wykres w publikacji jest końcem długiego łańcucha: akwizycji, konwersji, kuracji, wykluczeń, transformacji, modelowania i renderowania. Reprodukowalność obliczeniowa wymaga, aby ten łańcuch można było wykonać ponownie z tym samym wejściem i warunkami. Największym problemem rzadko jest brak ostatniego skryptu; częściej brakuje konkretnej wersji danych, konfiguracji albo środowiska.
National Academies rozróżnia reprodukowalność obliczeniową od replikacji badania na nowych danych. Ponowne uzyskanie wyniku z tych samych wejść nie dowodzi, że wniosek jest prawdziwy lub uogólnia się na inną próbę. Ułatwia jednak wykrywanie błędów i niezależną ocenę analizy.
1. Nadaj wersję danym wejściowym
Manifest wejścia powinien zawierać identyfikator zbioru i wersji, listę plików, rozmiary, sumy kontrolne oraz informację o standardzie. Dla danych kontrolowanych zamiast publicznego adresu podaj trwały identyfikator, procedurę dostępu i wersję, której użyto. Lokalna ścieżka na komputerze autora nie jest identyfikatorem.
Oddziel dane źródłowe, surowe po kuracji i pochodne. Nie poprawiaj surowego pliku w miejscu. Korekta metadanych powinna tworzyć nową wersję z dziennikiem zmian. Dzięki temu można wyjaśnić, czy różnica wyniku pochodzi ze zmiany kodu czy wejścia.
2. Wersjonuj kod oraz konfigurację razem
Repozytorium kodu powinno zawierać małe, logiczne kroki i oznaczone wydania. Manifest zapisuje dokładny commit, nie tylko nazwę gałęzi. Konfigurację przechowuj w pliku czytelnym maszynowo: progi, ścieżki logiczne, wybór kanałów, filtry, przestrzenie, model, ziarna i parametry zasobów.
Nie ukrywaj ważnych decyzji w komórkach notatnika uruchomionych w przypadkowej kolejności. Notatnik może służyć do raportu lub eksploracji, ale właściwy pipeline powinien być możliwy do uruchomienia od początku w czystym środowisku. Usuń ręczne kroki albo opisz je jako jawne, wersjonowane adnotacje.
3. Zbuduj graf zależności
Każdy krok określa wejścia, wyjścia, parametry i warunek sukcesu. Menedżer workflow może uruchamiać tylko brakujące lub zmienione zadania, ale nawet prosty skrypt powinien sprawdzać zależności. Nie opieraj kolejności na dacie modyfikacji pliku, jeśli nie gwarantuje ona pochodzenia.
Graf ujawnia rozgałęzienia wariantów analizy i wspólne wejścia. Pozwala też odróżnić produkt tymczasowy od wyniku przeznaczonego do archiwizacji. Zachowaj log polecenia, kod zakończenia i czas wykonania każdego węzła.
4. Uchwyć środowisko obliczeniowe
Lista nazw bibliotek bez wersji jest niewystarczająca. Zapisz system operacyjny, język, wersje pakietów, zależności pośrednie i istotne biblioteki systemowe. Użyj pliku blokady lub innego mechanizmu odtwarzającego konkretne wersje. Jeżeli sprzęt, sterownik albo biblioteka numeryczna może zmieniać wynik, dodaj je do manifestu.
Kontener pomaga zapakować zależności i polecenie uruchomienia. Oznacz go nie tylko zmiennym tagiem, lecz także niezmiennym digestem. Kontener nie zawiera automatycznie danych, licencji, sterowników sprzętu ani zewnętrznych usług. Sprawdź, czy obraz można pobrać, zbudować z jawnego przepisu i uruchomić bez sekretów autora.
5. Traktuj losowość jawnie
Zapisz źródła losowości i ziarna dla bibliotek, które ich używają. W modelach z podziałem danych zachowaj same indeksy podziału, a nie tylko seed. Ziarno może nie wystarczyć, gdy algorytm równoległy, akcelerator lub wersja biblioteki wykonuje operacje w innej kolejności.
Zdefiniuj, czego oczekujesz: identycznych bajtów, zgodności wartości w tolerancji czy równoważnego wniosku statystycznego. Testy powinny odpowiadać temu poziomowi. Nie oznaczaj drobnej różnicy zmiennoprzecinkowej jako katastrofy, ale nie zwiększaj tolerancji bez uzasadnienia tylko po to, by test przeszedł.
6. Dodaj testy danych i kodu
Testy schematu sprawdzają wymagane pola, typy, jednostki i relacje. Testy danych wykrywają duplikaty, nieoczekiwane liczby kanałów, brakujące zdarzenia i wartości poza sensownym zakresem technicznym. Testy kodu obejmują małe funkcje, cały krótki przebieg i regresję kluczowych wyników.
Przygotuj mały, legalnie udostępnialny zbiór testowy albo syntetyczne dane o znanych właściwościach. Nie używaj niezanonimizowanej sesji uczestnika w publicznej automatyzacji. Test syntetyczny wykryje błędy implementacji, ale nie zastąpi kontroli na reprezentatywnych danych rzeczywistych w bezpiecznym środowisku.
7. Generuj manifest każdego wykonania
Manifest uruchomienia łączy wersję wejścia, commit kodu, konfigurację, środowisko, kontener, sprzęt, czas, użytkownika technicznego lub system, statusy kroków, ostrzeżenia i sumy wyjść. Powinien być zapisany automatycznie, zanim wynik zostanie uznany za gotowy.
Dołącz tabelę przepływu jednostek: ile uczestników, sesji, kanałów i prób weszło do każdego etapu, ile odpadło i dlaczego. Dzięki temu końcowa liczebność nie jest liczbą przepisaną ręcznie do tekstu, lecz wynikiem tego samego pipeline'u.
8. Raportuj jakość oraz pochodzenie
Raport musi pokazywać metryki wejścia i wyjścia, wizualizacje kontrolne, kryteria, wykluczenia, wersje oraz otwarte ostrzeżenia. Dla dużego zbioru stwórz widok zbiorczy i możliwość przejścia do pojedynczej jednostki. Nie ukrywaj brakujących raportów — brak pliku powinien zatrzymać odbiór.
Wynik publikacyjny generuj z tych samych tabel i pochodnych, które przeszły kontrolę. Ręczne kopiowanie liczb do arkusza tworzy boczny, nieudokumentowany pipeline. Jeżeli ręczna adnotacja jest konieczna, zapisz ją w ustrukturyzowanym pliku z autorem, datą i uzasadnieniem.
9. Przećwicz odtworzenie na czystym środowisku
Osoba, która nie tworzyła pipeline'u, powinna pobrać dozwolone wejście, zbudować środowisko i wygenerować określony wynik według instrukcji. Zapisz czas, wymagane zasoby, problemy i różnice. Test na komputerze autora nie wykrywa niejawnych plików, zmiennych i cache.
W automatyzacji uruchamiaj przynajmniej krótki przypadek przy zmianie kodu. Pełny kosztowny pipeline może działać okresowo lub przed wydaniem. Artefakty testu powinny mieć termin przechowywania i nie mogą ujawniać danych kontrolowanych w publicznych logach.
10. Udostępnij instrukcję i granice
README powinien wskazywać cel, wejścia, licencję, warunki dostępu, wymagania, polecenie uruchomienia, oczekiwane wyjścia, zasoby, czas, testy i sposób cytowania. Dodaj znane ograniczenia oraz różnicę między odtworzeniem obliczeń a oceną naukowego wniosku.
Jeżeli danych nie można otworzyć, udostępnij metadane i procedurę dostępu w zakresie dozwolonym przez zgodę i prawo. FAIR nie wymaga ujawnienia wrażliwych plików wszystkim. Wymaga natomiast, aby warunki były opisane, a uprawniony użytkownik wiedział, jak uzyskać właściwą wersję.
Kryterium gotowości
Pipeline jest gotowy do przekazania, gdy wejście ma trwałą wersję, wykonanie odbywa się jednym udokumentowanym procesem, parametry nie żyją tylko w pamięci, środowisko można zbudować, testy przechodzą, raport obejmuje wszystkie jednostki, a manifest prowadzi od wyniku do źródła. Otwarte ostrzeżenia mają właściciela i uzasadnienie.
To nadal nie gwarantuje poprawnego wniosku. Potrzebne są właściwy projekt, statystyka, przegląd dziedzinowy i uczciwa interpretacja niepewności. Reprodukowalność sprawia jednak, że te elementy można zobaczyć, sprawdzić i ulepszyć.
Źródła
Ujęcie reprodukowalności opisano za opracowaniem National Academies wymienionym w tekście. Materiał nie zastępuje wymagań konkretnego czasopisma, grantodawcy ani komisji etycznej.