Jak upewnić się, że wyniki moich symulacji i wyniki w mojej pracy są zawsze zsynchronizowane?

34

W jednym z moich artykułów wymieniam niektóre wyniki liczbowe oprócz niektórych liczb. Chciałbym się upewnić, że wyniki liczbowe w mojej pracy zawsze zgadzają się z kodem. W tej chwili po prostu kopiuję bezpośrednio wyniki liczbowe z wyników symulacji na papier, co jest niezwykle proste i mało zaawansowane technicznie, ale podatne na błędy, ponieważ mogłem źle skopiować wyniki lub zapomnieć o zsynchronizowaniu wyników papierowych z kod wyjściowy.

Czy istnieje dobry sposób na zsynchronizowanie wyników liczbowych, które cytuję w swoich artykułach, z wynikami wygenerowanymi przez mój kod? (Tutaj zakładam, że wykonanie kodu jest łatwe i praktyczne, gdy chcę zaktualizować swój artykuł). Te wyniki liczbowe niekoniecznie nadają się do postaci tabelarycznej. Czasami mam tabele w manuskryptach, ale częściej mam parametry symulacji wymienione jako liczby w równaniach . Przykładem może być coś takiego:

y=(y1,,yn)

gdzie chciałbym zastąpić elementy warunku początkowego rzeczywistymi parametrami, których używam w symulacji, która numerycznie integruje układ równań różniczkowych zwyczajnych. Używanie tabeli do jednorazowych danych, takich jak ten przykład, wydaje się przesadzeniem i większą ilością atramentu niż to konieczne.y

Zakładam, że liczby są łatwiejszym przypadkiem: ilekroć dokument jest „budowany” (ze źródła LaTeX, Markdown, RST itp.), Rozpocznij proces kompilacji, wykonując kod. Jeśli jednak ludzie mają lepsze sugestie dotyczące synchronizacji liczb generowanych przez moje symulacje z moją pracą, chciałbym je usłyszeć.

Geoff Oxberry
źródło

Odpowiedzi:

14

Ponieważ niektóre komentarze sugerują, takie podejście już dawno zostały opracowane w środowisku R opierając się na Sweavebardziej niedawna knitr. Oczywiście to podejście ma tę wadę, że jest specyficzne dla danego języka, ale ma tę zaletę, że jest regularnie stosowane w artykułach naukowych.

Wykorzystanie Sweave w prawdziwych publikacjach

  • Journal of Biostatystyki zachęca te oświadczenia i umieszcza nas Kitemark „R” na prace naukowe, w którym redaktor reproduciblity został w stanie uruchomić kod i dane i uzyskać te wyniki.
  • Zasadniczo wszystkie publikacje w R-Journal są oparte na Sweave.

Oczywiście częściej użytkownicy Sweave / knitr przesyłają ostateczne wyniki do większości czasopism z osobistą pewnością, że metody rzeczywiście odtwarzają wyniki. Podobnie sweter jest często używany do tworzenia slajdów do profesjonalnych rozmów itp.

Przydatne funkcje

Aby był przydatny w praktyce, taki system powinien mieć pewne cechy. Przy krytycznej masie użytkowników wielu z nich jest dobrze rozwiniętych knitr. Kilka najważniejszych:

  • Buforowanie Zapis w formacie takim jak markdown lub lateks, który musi zostać skompilowany, aby zobaczyć wynik, uniemożliwia włączenie kodu wraz z niemożnością buforowania wyników. Sprytne buforowanie w knitrrzeczywistości znacznie ułatwia debugowanie intensywnego kodu niż praca w trybie czystym R, ponieważ ponowne uruchomienie udanych porcji nie jest konieczne.

  • Przełącz wyświetlanie kodu. W oficjalnej publikacji nie można chcieć, aby kod wyjściowy był widoczny na wydruku. Tymczasem często warto pokazać (ładnie sformatowany, podświetlony składnią) kod, który generuje wyniki w formacie wyjściowym, gdy chcesz, aby czytnik dokładnie widział, co piszesz.

  • Społeczność. Być może najbardziej przekonującą zaletą tego podejścia w porównaniu z rozwiązaniem domowej roboty jest liczba osób zaznajomionych z modelem i próbujących go ulepszyć.

  • Wiele ciekawych przykładów innych funkcji można znaleźć na prezentacjach stron knitr , w tym narzędzia do „lekkiego publikowania” lub udostępniania w Internecie. Wiele z tych funkcji pomaga uczynić to podejście bardziej zgodnym z ogólnym obiegiem pracy, a nie zrobić coś tylko podczas pisania manuskryptu.

Przypis historyczny.

Choć zakorzenione jest w „programowaniu piśmiennym” Knutha, jak sama nazwa wskazuje, nacisk jest zupełnie inny, ponieważ programowanie literackie koncentruje się na połączeniu kodu oprogramowania i dokumentacji (w społeczności R rolę tę odgrywa Roxygen, która wywodzi się z innej gałęzi „literackie drzewo programowania”).

Wyjść poza

Zasadniczo możemy wymagać znacznie więcej od dynamicznego dokumentu, takiego jak zdolność czytelnika do zmiany danych wejściowych i przeglądania wyników bez konieczności edytowania i ponownej kompilacji całego dokumentu, na przykład za pomocą interaktywnej platformy online. XDynDocs może być krokiem w tym kierunku.

Inne podejścia

  • Może chcesz mieć oko na dexy.it
  • W nieco innym podejściu: rosnąca liczba hostów dokumentów ekonomicznych związanych z publikacjami na stronie http://www.runmycode.org/ , która ponownie uruchomi analizy w chmurze i pozwoli na niestandardowe parametry wejściowe lub niestandardowe dane wejściowe.
cboettig
źródło
Carl, obserwuję twoją stronę od jakiegoś czasu, a twoje podejście do knitra było jedną z inspiracji dla mojego pytania. Od dłuższego czasu śledzę dexy, ponieważ Zed Shaw używa go do zbudowania źródła dla swojej książki How To Learn Python the Hard Way (zobacz repozytorium git ). To, co lubię w dexy, w przeciwieństwie do innych umiejętności programowania, polega na tym, że kod i tekst są luźno powiązane, co umożliwia rozsądne korzystanie z debuggera.
Geoff Oxberry,
Geoff, super, dzięki za komentarze! Anna Nelson również wierzy w oddzielanie płatności od produkcji. Użytkownicy R mogą dokonać oddzielenia w knitr za pomocą eksternalizacji kodu lub nowej spin()funkcji. Osobiście uważam, że skargi Grega Wilsona na umiejętności pisania i czytania są dość przestarzałe. Miałem to samo straszne doświadczenie, które opisuje w przypadku nowegob, ale to skomplikowane debugowanie po prostu nie istnieje w nowoczesnych narzędziach. Dla piśmiennictwa CI użyj doxygen. Knitr jest łatwiejszy do debugowania niż R dzięki buforowaniu i obsłudze środowiska.
cboettig
20

To, o co prosisz, to wielkie wyzwanie Elsivier z „Executable Paper” . Chociaż wypróbowano wiele podejść, żadne nie jest tak przekonujące, jak sugerują autorzy. Oto kilka przykładów zastosowanych technik.

Projekt Madagaskar przyjmuje twoje podejście, w skrypcie make uruchomiono symulacje, w których jednocześnie powstają figury i papier.

IPython Notebook zapewnia dokument, który można wykonać, czytając i generując liczby zgodnie z własnym sercem. (Widziałem wtyczki słowne, Mathematica i wiele innych rozwiązań używanych w ten sam sposób)

VisTrails wykorzystuje podejście oparte na architekturze zorientowanej na usługi i zapewnia menedżera „opatrzności” lub „przepływu pracy”. Zasadniczo rejestrujesz haki do kodu, a następnie projektujesz przepływ pracy lub eksperyment, który odtwarza twoją pracę. Został on zastosowany w wielu typach kodów, nawet klastrach HPC. Dzięki takiemu podejściu będziesz mógł odtworzyć eksperymenty.

Istnieje mnóstwo tego typu rozwiązań, ale te trzy były pod wrażeniem. To trudny problem i uważam, że tak naprawdę nie jesteśmy nawet blisko rozwiązania tego problemu. Nie możemy nawet zmusić ludzi do wydania kodu wraz z dokumentami, jak możemy oczekiwać, że powiela wyniki = P

aterrel
źródło
W podobnym tonie jest sweter , którego nie używam, ale jest intrygujący w swojej koncepcji.
dmckee
Projekt Madagaskar wydawał się interesujący, gdy wysłuchałem przemówienia jednego z jego autorów. Jednak tak naprawdę nie próbowałem tego użyć.
Ken
@dmckee: Znam ludzi, którzy odnieśli sukces ze swave i knitr . Jestem ostrożny w zakresie umiejętności programowania z tych samych powodów, które Greg Wilson podaje w Software Carpentry : papier i kod są zbyt ściśle powiązane, co utrudnia uruchomienie debuggera na kodzie (i może przeszkodzić w sprawdzaniu poprawności tekst).
Geoff Oxberry
Używam Sweave do tego celu, działa bardzo ładnie i jest kompatybilny z Lyx. Tryb Org jest jeszcze lepszy i obsługuje większość popularnych języków.
David LeBauer
13

Nie odniosłem dużego sukcesu w stosowaniu rozwiązań tego problemu przez innych ludzi. Zwykle chcę po prostu czegoś prostego, co działa dla mnie i wykonuje pracę. W tym celu zazwyczaj próbuję napisać jeden skrypt w języku Python, który jest odpowiedzialny za uruchamianie wszystkich wyników, analizowanie danych wyjściowych, a także tworzenie rysunków / tabel.

Piszę moje kody, aby generować pliki danych, które zawierają wyniki w jakimś formacie tekstowym. Możesz uniknąć ponownego uruchamiania tych wyników w skrypcie, najpierw testując obecność pliku wyjściowego (na przykład w pythonie, używając os.path.isfile ()). Jeśli chcesz ponownie uruchomić wyniki, po prostu usuń pliki danych. Jeśli pliki danych istnieją, uruchamiam analizator składni tych plików. W tym celu bardzo przydatny (re) jest moduł pythonowy dla wyrażeń regularnych.

Następnie z przeanalizowanego wyjścia tworzę liczby lub tabele. W przypadku tabel w lateksie możesz napisać kod, aby wygenerować tabelę w osobnym pliku (używam rozszerzenia .tbl), a następnie dołączyć to do pliku lateksu. Kluczem jest dla mnie użycie 1 skryptu Python. Jeśli mam ich wiele, to zastanawiam się później, który z nich jest i co robią. Jeśli ten opis jest zbyt niejasny, mogę wysłać kilka przykładów.

Nathan Collier
źródło
1
Robię już coś takiego dla postaci. Jednak w artykułach, które piszę, tabele byłyby nienaturalnym formatem prezentacji danych. Często naprawdę chcę po prostu dołączyć warunek początkowy do ODE (tak naprawdę coś w rodzaju 4-6 liczb, oddzielonych przecinkami) lub całą macierz liczb jako część prawej strony równania. Podoba mi się twój pomysł na stoły. W przypadkach, o których wspomniałem, wydaje mi się, że ponowne sformatowanie ich jako tabel byłoby nienaturalne i chciałbym uwzględnić dane w bardziej naturalnym formacie.
Geoff Oxberry
Nathan, czy mógłbyś opublikować przykłady? Używam tego samego podejścia, z tym wyjątkiem, że zatwierdzam pliki tekstowe do git i używam git do zarządzania wynikami. Następnie mam skrypty Pythona do tworzenia wykresów / tabel. Mam jeden skrypt na fabułę lub tabelę.
Ondřej Čertík,
Możesz także przesłać dane wyjściowe skryptu powłoki bezpośrednio do lateksu za pomocą polecenia \input{|"path-to-script.py"}. Myślę, że lepiej umieścić wszystkie parametry w jednym pliku python (lub jakimkolwiek języku jest twoim ulubionym) i użyć parametru wiersza poleceń, aby uzyskać do niego dostęp \input{|"path-to-script.py param-name"}. W takim przypadku możesz dołączyć plik param do innych skryptów, aby uruchomić symulacje. Powoduje to jednak spowolnienie kompilacji i ma inne negatywne punkty.
Hel
7

Jeszcze ważniejsze, moim zdaniem, jest upewnienie się, że możesz dowiedzieć się, jak ponownie wygenerować wszystkie wyniki od zera w ciągu miesiąca lub roku (na przykład, gdy sędziowie proszą cię o dodanie lub modyfikację). W tym celu włączam plik tekstowy z bardzo szczegółowymi wskazówkami, jak odtworzyć wszystkie wyniki. Najlepiej, jeśli je przetestujesz, gdy ktoś inny (np. Współautor) je wypróbuje. Zalecam także przekazanie tych instrukcji (i całego kodu) recenzentom i czytelnikom.

Oto przykład (faktycznie przygotowany przez mojego współautora, Arona Ahmadię).

David Ketcheson
źródło
Zrobiłem to wcześniej (dla własnego zdrowia psychicznego) i na szczęście opłaciło się, gdy mój doradca poprosił mnie o ponowne wygenerowanie i ponowne sprawdzenie wyników. Od tego czasu przerzuciłem się na po prostu zrzut kodu źródłowego skryptu, który uruchamia wszystko w dodatku moich szkiców, więc jest tam, wiem, co zrobiłem i mogę kliknąć jeden przycisk, aby uzyskać wszystkie liczby i liczby.
Geoff Oxberry
Skrypt obecnie nie wykonuje żadnej instalacji, ponieważ jest to tylko skrypt MATLAB. W dokumentacji funkcji zawiera listę zależności od pakietów innych firm. Z kolei te pakiety innych firm mają przejrzystą dokumentację dotyczącą ich instalacji (i na szczęście są również aktywnie wspierane, mają świetnych programistów i aktywne listy mailingowe).
Geoff Oxberry
6

Udało się to osiągnąć dzięki trybowi Emacsa w połączeniu z Babel. Babel może wykonywać fragmenty kodu z różnych języków programowania i skryptów, np. Może otworzyć plik zawierający dane symulacji i umieścić go w tabeli w trybie orgmode, którą można wyeksportować do LaTeX (i wielu innych formatów). Przyzwyczajenie się do wszystkich kluczowych kombinacji w trybie orgm zajmuje trochę czasu, ale po uruchomieniu wszystko odbywa się automatycznie.

Robert
źródło
Lubię tryb org; Używam go do konturów. Nie użyłem tego z Babel. Będę musiał to wypróbować.
Geoff Oxberry
Oto doskonały przegląd z stycznia 2012 J. Stat. Oprogramowanie jstatsoft.org/v46/i03/paper
David LeBauer
Napisałem samouczek, który pokazuje, jak przekonwertować szablon LaTeX z European Physical Journal A (EPJ A) na plik w trybie org.
Melioratus
4

Jeśli uruchomienie całego kodu jest tanie, możesz zrobić coś mniej zaawansowanego technologicznie, jak na przykład:

Możesz utworzyć szablon dokumentów ze sformatowanymi ciągami, aby wyglądały tak

"we observed a %(fractional_improvement)s increase in ..."

Mają skrypty python, które wyglądają tak

results = {"alpha"                  : run_alpha_computation(...),
           "fractional_improvement" : run_fi_computation(...), 
           ...}

A potem zrób coś takiego

for fn in filenames:
    file = open(fn);      s = file.read();       file.close()
    file = open(fn, 'w'); file.write(s%results); file.close()

Następnie możesz zawinąć to w plik Makefile.

MRocklin
źródło
Moja pierwsza myśl, kiedy napisałem to pytanie, było rozwiązaniem podobnym do tego, które zaproponowałeś. Początkowo myślałem o czymś mniej zaawansowanym technologicznie, takim jak użycie preprocesora makr, ale Python jest prawdopodobnie lepszym (i na pewno bardziej czytelnym) podejściem, a następnie system kompilacji poradzi sobie z przyrostową regeneracją wyników.
Geoff Oxberry,
Naprawdę jest to tylko bardzo podstawowa implementacja czegoś takiego jak strony serwera Python. Idea treści generowanych automatycznie pojawia się w społeczności internetowej już od jakiegoś czasu. Byłoby miło, gdyby migrował do środowiska akademickiego.
MRocklin,
Zgoda. Jinja2 może służyć do robienia tego, co zasugerowałeś. W rzeczywistości to właśnie robi dexy , ale z kilkoma fajnymi filtrami, które również obsługują podświetlanie składni i inne różne zadania.
Geoff Oxberry,
4

Jeśli używasz LaTeX, stosunkowo mało zaawansowanym technologicznie rozwiązaniem jest wyplucie kodu z pliku (lub użycie skryptu do odfiltrowania danych wyjściowych kodu) zawierającego całą masę wierszy takich jak to:

\newcommand{\myresults1}{<value>}

Następnie możesz użyć \inputpolecenia, aby dodać ten plik do dokumentu i użyć zdefiniowanych poleceń, aby umieścić wartości.

Aesin
źródło
2

Pracuję dla Elseviera. Moja firma zaczęła używać frameworku Collage (opracowanego w odpowiedzi na Wielkie Wyzwanie Papieru Wykonawczego) w wydaniach czasopism, aby umożliwić autorom publikowanie fragmentów kodu wykonywalnego wraz z ich artykułem. Ta funkcja ułatwia czytelnikom odtwarzanie wyników zgłoszonych w artykule i ponowne wykorzystanie opublikowanych materiałów do własnych badań. Collage obsługuje szeroką gamę oprogramowania typu open source i zastrzeżonego; więcej informacji można znaleźć w wideo informacyjnym tutaj oraz na stronie internetowej środowiska tworzenia kolaży .

Hylke Koers
źródło
Drugi link to niewłaściwa rzecz.
David Ketcheson
@Hylke Koers: Czy chciałeś umieścić ten link: collage.elsevier.com ?
Paweł
@Paul: Wprowadziłem zmiany; oryginalny drugi link był do grupy dyskusyjnej Google. Być może lepszym linkiem byłby sam Kolaż, ale moim celem było (głównie) zachowanie dobrych intencji postu przy jednoczesnym usunięciu części, które sprawiły, że brzmiał on promocyjnie. Edytuj wpis, jeśli uważasz, że jest odpowiedni.
Geoff Oxberry