Come posso assicurarmi che i risultati delle mie simulazioni e i risultati nel mio documento siano sempre sincronizzati?

In uno dei miei articoli, elencherò alcuni risultati numerici oltre ad alcune cifre. Quello che mi piacerebbe fare è assicurarmi che i risultati numerici nel mio documento siano sempre in accordo con il codice. In questo momento, copio direttamente i risultati numerici dal mio output di simulazione sul foglio, che è estremamente semplice e di bassa tecnologia, ma soggetto a errori, perché potrei copiare erroneamente i risultati o dimenticare di sincronizzare i risultati della carta con il uscita del codice.

C'è un buon modo per mantenere sincronizzati i risultati numerici che cito nei miei articoli con i risultati generati dal mio codice? (Qui, presumo che eseguire il codice sia facile e pratico da fare ogni volta che voglio aggiornare il mio documento.) Questi risultati numerici non si prestano necessariamente in forma tabellare. A volte, ho tabelle nei manoscritti, ma più comunemente ho parametri di simulazione elencati come numeri nelle equazioni . Un esempio potrebbe essere qualcosa del tipo:

dove mi piacerebbe sostituire gli elementi della condizione iniziale con i parametri reali che utilizzo in una simulazione che integra numericamente un sistema di equazioni differenziali ordinarie. L'uso di una tabella per dati una tantum come questo esempio sembra eccessivo e più inchiostro del necessario.$\mathbf{y}^{*}$

Presumo che le cifre siano un caso più semplice: ogni volta che il documento viene "costruito" (da sorgente LaTeX, Markdown, RST, ecc.), Avvia il processo di compilazione eseguendo il codice. Tuttavia, se le persone hanno suggerimenti migliori per mantenere sincronizzati i dati generati dalle mie simulazioni con il mio documento, mi piacerebbe ascoltarli.

Come alcuni commenti hanno suggerito, questo approccio è stato a lungo sviluppata nella comunità di R con la costruzione su Sweavee, più recentemente, knitr. Ovviamente questo approccio ha lo svantaggio di essere specifico per la lingua al momento, ma il vantaggio che viene regolarmente utilizzato nei documenti accademici.

Uso di Sweave in pubblicazioni reali

• Il Journal of Biostatistics incoraggia questi invii e inserisce una lettera kitemark "R" su documenti accademici in cui l'editor di riproducibilità è stato in grado di eseguire il codice e i dati e ottenere questi risultati.
• Fondamentalmente tutte le pubblicazioni nell'R-Journal sono basate su Sweave.

Naturalmente più comunemente gli utenti Sweave / knitr inviano solo l'output finale alla maggior parte delle riviste, con la sicurezza personale che i metodi riproducano effettivamente i risultati. Allo stesso modo sweave viene spesso utilizzato per creare diapositive per discorsi professionali, ecc.

Caratteristiche utili

Per essere utile nella pratica, tale sistema dovrebbe avere alcune caratteristiche. Con una massa critica di utenti, molti di questi sono ben sviluppati in knitr. Alcuni punti salienti:

• Caching. Scrivere in un formato come markdown o latex che deve essere compilato per vedere l'output rende questo incluso il codice impossibile quando i risultati non possono essere memorizzati nella cache. Il caching intelligente in knitrrealtà rende il debug del codice intensivo molto più semplice che lavorare in puro R, poiché non è necessario rieseguire blocchi di successo.

• Attiva / disattiva la visualizzazione del codice. In una pubblicazione formale non si può desiderare che nessuno dei codici sottostanti sia visibile sull'output. Nel frattempo è spesso utile mostrare il codice (ben formattato, evidenziato in sintassi) che produce i risultati nel formato di output quando si desidera che il lettore veda esattamente ciò che si sta digitando.

• Comunità. Forse il vantaggio più convincente di questo approccio rispetto a una soluzione homebrewed è il numero di persone che hanno familiarità con il modello e cercano di migliorarlo.

• Molti esempi interessanti di altre funzionalità sono disponibili nelle demo delle pagine Web di Knitr , inclusi gli strumenti per la "pubblicazione leggera" o la condivisione sul Web. Molte di queste funzioni aiutano a rendere questo approccio più compatibile con il proprio flusso di lavoro generale, piuttosto che qualcosa da fare solo quando si scrive il manoscritto.

Nota storica.

Sebbene radicato nella "programmazione letterata" di Knuth, come suggerisce il nome, l'enfasi è piuttosto diversa, poiché la programmazione letteraria si concentra sulla connessione di codice software e documentazione (nella comunità R quel ruolo è svolto Roxygen, che traccia le sue radici in un diverso ramo di "albero di programmazione alfabetico").

Andare oltre

In linea di principio potremmo chiedere molto di più da un documento dinamico, come la capacità del lettore di modificare gli input e vedere gli output senza dover modificare e ricompilare l'intero documento, ad esempio utilizzando una piattaforma online interattiva. XDynDocs potrebbe essere un passo in questa direzione.

Altri approcci

• Potrebbe voler tenere d'occhio dexy.it
• In un approccio leggermente diverso: un numero crescente di articoli di economia ospita il codice associato alle pubblicazioni su http://www.runmycode.org/ , che eseguirà nuovamente le analisi sul cloud e consentirà parametri di input personalizzati o dati di input personalizzati.

Quello che stai chiedendo è la grande sfida di Elsivier del "Documento eseguibile" . Mentre molti approcci sono stati provati, nessuno è convincente come gli autori potrebbero suggerire. Ecco alcuni esempi di tecniche utilizzate.

Il progetto Madagascar segue il tuo approccio, all'interno della sceneggiatura di make sono in esecuzione le simulazioni che producono figure e carta contemporaneamente.

IPython Notebook fornisce un documento che è possibile eseguire mentre si legge e si producono figure per il contenuto del proprio cuore. (Ho visto plugin di parole, Mathematica e numerose altre soluzioni usate allo stesso modo)

VisTrails utilizza un approccio di architettura orientato ai servizi e fornisce un gestore "provvidenza" o "flusso di lavoro". Fondamentalmente si registrano hook per codificare quindi progettare un flusso di lavoro o esperimento che riproduca il proprio lavoro. È stato utilizzato su molti tipi di codici, anche su cluster HPC. Con questo approccio avrai un modo per ripetere gli esperimenti.

Ci sono tonnellate di soluzioni di questo tipo là fuori, ma quelle sono tre di cui sono rimasto colpito. È un problema difficile e credo che in realtà non siamo nemmeno vicini. Non possiamo nemmeno convincere le persone a rilasciare il loro codice con i loro articoli, come possiamo aspettarci che riproducano i risultati = P

Non ho avuto molto successo nell'usare le soluzioni di altre persone a questo problema. Di solito voglio solo qualcosa di semplice che funzioni per me e svolga il lavoro. A tal fine, in genere cerco di scrivere uno script Python che si occupa di eseguire tutti i risultati, analizzare l'output e costruire figure / tabelle.

Scrivo i miei codici per generare file di dati che contengono i risultati in un formato di testo. Puoi evitare di rieseguire questi risultati nel tuo script testando prima l'esistenza del file di output (ad esempio in python usando os.path.isfile ()). Se si desidera rieseguire i risultati, è sufficiente rimuovere i file di dati. Se i file di dati esistono, eseguo un parser di questi file. Per questo, il modulo python per le espressioni regolari è molto utile (ri).

Quindi dall'output analizzato creo le figure o le tabelle. Per le tabelle in lattice è possibile scrivere il codice per generare la tabella in un file separato (utilizzo un'estensione .tbl) e quindi includerlo nel file in lattice. La chiave per me è usare 1 script Python. Se ne ho molti, in seguito mi chiedo quale sia quale e cosa facciano. Se questa descrizione è troppo vaga, posso inviarti alcuni esempi.

Ancora più importante, secondo me, è assicurarsi che tu possa capire come rigenerare da zero tutti i tuoi risultati in un mese o un anno (ad esempio, quando gli arbitri ti chiedono di aggiungere o modificare qualcosa). A tale scopo, ciò che faccio è includere un file di testo con indicazioni molto dettagliate su come riprodurre tutti i risultati. È meglio se li provi facendo provare a qualcun altro (come un coautore). Consiglio di fornire anche queste istruzioni (e tutto il codice) ad arbitri e lettori.

Ecco un esempio (in realtà preparato dal mio coautore, Aron Ahmadia).

La modalità org di Emacs in combinazione con Babel lo raggiunge. Babel può eseguire frammenti di codice da vari linguaggi di programmazione e di scripting, ad esempio, potrebbe aprire il file contenente i dati di simulazione e inserirlo in una tabella in modalità org, che può essere esportata in LaTeX (e in molti altri formati). Ci vuole un po 'di tempo per abituarsi a tutte le combinazioni di tasti in orgmode, ma una volta in esecuzione tutto è automatico.

Se l'esecuzione di tutto il tuo codice è economica, potresti fare qualcosa di a bassa tecnologia come il seguente:

Puoi modellare i tuoi documenti con stringhe formattate in modo che appaiano così

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

Avere script Python che assomigliano a questo

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

E poi fai qualcosa del genere

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

Potresti quindi concludere questo in un Makefile.

Se stai usando LaTeX, una soluzione relativamente a bassa tecnologia è fare in modo che il tuo codice sputi un file (oppure usa uno script per filtrare dall'output del tuo codice) contenente un sacco di righe come questa:

\newcommand{\myresults1}{<value>}

Quindi è possibile utilizzare il \inputcomando per aggiungere quel file nel documento e utilizzare i comandi definiti per posizionare i valori.

Lavoro per Elsevier. La mia azienda ha iniziato a utilizzare il framework Collage (sviluppato in risposta all'Executable Paper Grand Challenge) nelle edizioni del diario per consentire agli autori di pubblicare pezzi di codice eseguibile con il loro articolo. Questa funzione semplifica la riproduzione da parte dei lettori dei risultati riportati nell'articolo e il riutilizzo del materiale pubblicato per le proprie ricerche. Collage supporta un'ampia gamma di software open source e proprietari; ulteriori informazioni sono disponibili nel video informativo qui e nel sito Web Collage Authoring Environment .