Comment puis-je m'assurer que les résultats de mes simulations et ceux de mon article sont toujours synchronisés?

Dans l'un de mes articles, j'énumère des résultats numériques en plus de certains chiffres. Ce que j'aimerais faire, c'est m'assurer que les résultats numériques dans mon papier sont toujours en accord avec le code. À l’heure actuelle, je copie directement les résultats numériques de la sortie de ma simulation dans le document, ce qui est extrêmement simple et peu technique, mais source d’erreurs, car je pourrais mal copier les résultats ou oublier de synchroniser les résultats sur papier. sortie de code.

Existe-t-il un moyen efficace de synchroniser les résultats numériques cités dans mes documents avec les résultats générés par mon code? (Ici, je suppose que l’exécution du code est facile et pratique à faire chaque fois que je souhaite mettre à jour mon document.) Ces résultats numériques ne se prêtent pas nécessairement à la forme tabulaire. Parfois, j'ai des tableaux dans les manuscrits, mais plus généralement, j'ai des paramètres de simulation listés sous forme de nombres dans les équations . Un exemple serait quelque chose comme:

où je voudrais remplacer les éléments de la condition initiale par les paramètres que j’utilise dans une simulation qui intègre numériquement un système d’équations différentielles ordinaires. L'utilisation d'une table pour des données uniques, comme dans cet exemple, semble excessive et demande plus d'encre que nécessaire.$\mathbf{y}^{*}$

Je suppose que les figures sont un cas plus simple: chaque fois que le document est "construit" (à partir du source LaTeX, Markdown, RST, etc.), démarrez le processus de construction en exécutant le code. Toutefois, si les gens avaient de meilleures suggestions pour que les chiffres générés par mes simulations soient synchronisés avec mon document, j'aimerais les entendre.

Comme certains commentaires ont suggéré, cette approche a été développée longtemps dans la communauté R en mettant à profit Sweaveet , plus récemment, knitr. Évidemment, cette approche a le désavantage d’être spécifique à une langue pour le moment, mais elle a l’avantage d’être utilisée régulièrement dans les travaux universitaires.

Utilisation de Sweave dans de vraies publications

• Le Journal of Biostatistics encourage ces soumissions et place une lettre "R" sur les articles scientifiques dans lesquels l'éditeur de reproductibilité a pu exécuter le code et les données et obtenir ces résultats.
• Essentiellement, toutes les publications du R-Journal sont construites sur Sweave.

Bien entendu, plus couramment, les utilisateurs de Sweave / knitr ne soumettent que le résultat final à la plupart des revues, avec la certitude personnelle que les méthodes reproduisent les résultats. De même, sweave est souvent utilisé pour créer des diapositives pour des entretiens professionnels, etc.

Caractéristiques utiles

Pour être utile dans la pratique, un tel système devrait avoir certaines caractéristiques. Avec une masse critique d'utilisateurs, beaucoup d'entre eux sont bien développés en knitr. Quelques faits saillants:

• Caching L'écriture dans un format tel que markdown ou latex à compiler pour afficher le résultat rend cela impossible, y compris le code, lorsque les résultats ne peuvent pas être mis en cache. Une mise en cache intelligente knitrfacilite grandement le débogage de code intensif par rapport au travail en mode pur R, car il n’est pas nécessaire de réexécuter des fragments avec succès.

• Basculer l'affichage du code. Dans une publication formelle, il est possible que le code sous-jacent ne soit pas visible sur le résultat. En attendant, il est souvent utile de montrer le code (joliment formaté, mis en évidence par la syntaxe) qui produit les résultats dans le format de sortie lorsque vous voulez que le lecteur voie exactement ce que vous tapez.

• Communauté. L’avantage le plus important de cette approche par rapport à une solution maison est peut-être le nombre de personnes familiarisées avec le modèle et essayant de l’améliorer.

• Vous trouverez de nombreux exemples intéressants d’autres fonctionnalités sur les démos de la page Web de Knitr , notamment des outils de «publication allégée» ou de partage sur le Web. Bon nombre de ces fonctionnalités permettent de rendre cette approche plus compatible avec le flux de travail général, plutôt que de le faire uniquement lors de la rédaction du manuscrit.

Note de bas de page historique.

Bien que enraciné dans « programmation littéraire » de Knuth, comme son nom l' indique, l'accent est tout à fait différente, comme la programmation littéraire met l' accent sur la connexion du code logiciel et la documentation (dans la communauté R ce rôle est joué par Roxygen, qui trouve ses racines dans une autre branche de "l'arbre de programmation alphabète").

Aller plus loin

En principe, nous pourrions demander beaucoup plus à un document dynamique, tel que la capacité du lecteur à modifier les entrées et à visualiser les sorties sans avoir à éditer et recompiler le document entier, par exemple à l'aide d'une plate-forme interactive en ligne. XDynDocs peut être un pas dans cette direction.

Autres approches

• Peut-être envie de garder un œil sur dexy.it
• Dans une approche légèrement différente: un nombre croissant de publications économiques hébergent du code associé aux publications sur http://www.runmycode.org/ , qui réexécutera les analyses sur le cloud et autorisera des paramètres d’entrée ou des données d’entrée personnalisées.

Ce que vous demandez, c'est le grand défi Elsivier du "papier exécutable" . Bien que de nombreuses approches aient été essayées, aucune n’est aussi convaincante que les auteurs pourraient le suggérer. Voici quelques exemples de techniques utilisées.

Madagascar Project adopte votre approche, dans le script de création, exécutez les simulations qui produisent les figures et le papier simultanément.

IPython Notebook fournit un document que vous pouvez exécuter lorsque vous lisez et produisez des illustrations au contenu qui vous tient à cœur. (J'ai vu des plugins de mots, Mathematica et de nombreuses autres solutions utilisées de la même manière)

VisTrails utilise une approche d’architecture orientée service et fournit un gestionnaire de «prévoyance» ou de «flux de travail». En gros, vous enregistrez les points d'ancrage dans le code, puis vous concevez un flux de travail ou un test reproduisant votre travail. Il a été utilisé sur de nombreux types de codes, même les clusters HPC. Avec cette approche, vous aurez un moyen de rejouer les expériences.

Il existe de nombreuses solutions de ce type, mais ce sont trois solutions qui m'ont impressionné. C'est un problème difficile et je crois que nous ne sommes même pas près de nous attaquer. Nous ne pouvons même pas amener les gens à publier leur code avec leurs papiers, comment pouvons-nous nous attendre à ce qu'ils reproduisent les résultats = P

Je n'ai pas eu beaucoup de succès en utilisant les solutions des autres à ce problème. D'habitude, je veux juste quelque chose de simple qui fonctionne pour moi et qui fait le travail. À cette fin, j'essaie généralement d'écrire un script python chargé d'exécuter tous les résultats, d'analyser la sortie, ainsi que de construire les figures / tables.

J'écris mes codes pour générer des fichiers de données contenant les résultats dans un format texte. Vous pouvez éviter de réexécuter ces résultats dans votre script en vérifiant d’abord l’existence du fichier de sortie (en python avec os.path.isfile () par exemple). Si vous souhaitez réexécuter vos résultats, supprimez simplement les fichiers de données. Si les fichiers de données existent, je lance un analyseur syntaxique de ces fichiers. Pour cela, le module python pour les expressions régulières est très utile (re).

Ensuite, à partir de la sortie analysée, je crée les figures ou les tableaux. Pour les tables en latex, vous pouvez écrire le code pour générer la table dans un fichier séparé (j'utilise une extension .tbl), puis l'inclure dans votre fichier latex. La clé pour moi est d'utiliser 1 script python. Si j'en ai plusieurs, je me demande plus tard lequel est ce et ce qu'ils font. Si cette description est trop vague, je peux vous envoyer quelques exemples.

Le plus important, à mon avis, est de vous assurer que vous pouvez trouver un moyen de générer à nouveau tous vos résultats en un mois ou une année (par exemple, lorsque les arbitres vous demandent d’ajouter ou de modifier quelque chose). Pour cela, je propose un fichier texte contenant des instructions très détaillées sur la manière de reproduire tous les résultats. Il est préférable de les tester en les faisant essayer à quelqu'un d'autre (comme un co-auteur). Je vous recommande de fournir également ces instructions (et tout votre code) aux arbitres et aux lecteurs.

Voici un exemple (préparé par mon co-auteur, Aron Ahmadia).

L' orgmode d'Emacs associé à Babel y parvient. Babel peut exécuter des fragments de code à partir de divers langages de programmation et de script. Il peut par exemple ouvrir le fichier contenant les données de simulation et le placer dans une table en orgmode, qui peut être exportée vers LaTeX (et de nombreux autres formats). Il faut un certain temps pour s'habituer à toutes les combinaisons de touches dans orgmode, mais une fois que tout est en cours d'exécution, tout est automatique.

Si exécuter tout votre code est bon marché, vous pouvez faire quelque chose de low-tech tel que:

Vous pouvez créer un modèle pour vos documents avec des chaînes formatées afin qu'elles ressemblent à ceci

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

Avoir des scripts python qui ressemblent à ceci

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

Et puis faire quelque chose comme ça

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

Vous pouvez ensuite envelopper cela dans un Makefile.

Si vous utilisez LaTeX, une solution relativement peu technologique consiste à faire cracher votre fichier par un code (ou à utiliser un script pour filtrer la sortie de votre code) contenant tout un tas de lignes comme celle-ci:

\newcommand{\myresults1}{<value>}

Vous pouvez ensuite utiliser la \inputcommande pour ajouter ce fichier dans votre document et utiliser les commandes définies pour placer les valeurs.

Je travaille pour Elsevier. Mon entreprise a commencé à utiliser le framework Collage (développé en réponse au défi Executable Paper Grand Challenge) dans les revues afin de permettre aux auteurs de publier des morceaux de code exécutable avec leur article. Cette fonctionnalité permet aux lecteurs de reproduire plus facilement les résultats rapportés dans l'article et de réutiliser le matériel publié pour leurs propres recherches. Collage prend en charge une grande variété de logiciels propriétaires et à code source ouvert; Vous trouverez plus d'informations dans la vidéo d'information ici et sur le site Web Collage Authoring Environment .