¿Cómo me aseguro de que los resultados de mis simulaciones y los resultados de mi trabajo estén siempre sincronizados?

34

En uno de mis documentos, enumero algunos resultados numéricos además de algunas cifras. Lo que me gustaría hacer es asegurarme de que los resultados numéricos en mi trabajo siempre estén de acuerdo con el código. En este momento, solo copie directamente los resultados numéricos de mi salida de simulación en el papel, que es extremadamente simple y de baja tecnología, pero propenso a errores, porque podría copiar mal los resultados u olvidar sincronizar los resultados del papel con el salida de código

¿Hay una buena manera de mantener sincronizados los resultados numéricos que cito en mis documentos con los resultados generados por mi código? (Aquí, supongo que ejecutar el código es fácil y práctico cuando quiero actualizar mi trabajo). Estos resultados numéricos no necesariamente se prestan en forma tabular. A veces, tengo tablas en manuscritos, pero más comúnmente, tengo parámetros de simulación listados como números en ecuaciones . Un ejemplo sería algo como:

y=(y1,...,ynorte)

donde me gustaría reemplazar los elementos de la condición inicial con los parámetros reales que uso en una simulación que integra numéricamente un sistema de ecuaciones diferenciales ordinarias. Usar una tabla para datos únicos como este ejemplo parece excesivo y más tinta de la necesaria.y

Supongo que las cifras son un caso más fácil: cada vez que el documento se "construye" (desde la fuente LaTeX, Markdown, RST, etc.), inicie el proceso de compilación ejecutando el código. Sin embargo, si las personas tienen mejores sugerencias para mantener sincronizadas las cifras generadas por mis simulaciones con mi trabajo, me encantaría escucharlas.

Geoff Oxberry
fuente

Respuestas:

14

Como han sugerido algunos comentarios, este enfoque ha sido desarrollado en la comunidad R construyendo sobre Sweavey más recientemente, knitr. Obviamente, este enfoque tiene la desventaja de ser específico del idioma en este momento, pero la ventaja de que se usa regularmente en artículos académicos.

Uso de Sweave en publicaciones reales.

  • El Journal of Biostatistics alienta estas presentaciones, y coloca una letra "R" de kitemark en los documentos académicos en los que el editor de reproducción ha podido ejecutar el código y los datos y obtener estos resultados.
  • Esencialmente, todas las publicaciones en el R-Journal se basan en Sweave.

Por supuesto, más comúnmente los usuarios de Sweave / knitr envían solo el resultado final a la mayoría de las revistas, con la confianza personal de que los métodos realmente reproducen los resultados. Del mismo modo, sweave se usa a menudo para crear diapositivas para charlas profesionales, etc.

Características útiles

Para ser útil en la práctica, dicho sistema debe tener ciertas características. Con una masa crítica de usuarios, muchos de estos están bien desarrollados knitr. Algunos puntos destacados:

  • Almacenamiento en caché. Escribir en un formato como Markdown o Latex que debe compilarse para ver el resultado hace que esto incluya el código imposible cuando los resultados no se pueden almacenar en caché. El almacenamiento en caché inteligente knitrhace que la depuración de código intensivo sea mucho más fácil que trabajar en puro R, ya que no es necesario volver a ejecutar fragmentos exitosos.

  • Alternar visualización de código. En una publicación formal, uno puede no querer que ninguno de los códigos subyacentes sea visible en la salida. Mientras tanto, a menudo es valioso mostrar el código (bien formateado, resaltado por la sintaxis) que produce los resultados en el formato de salida cuando desea que el lector vea exactamente lo que está escribiendo.

  • Comunidad. Quizás la ventaja más convincente de este enfoque sobre una solución casera es la cantidad de personas familiarizadas con el modelo y que intentan mejorarlo.

  • Se pueden encontrar muchos ejemplos agradables de otras funciones en las demostraciones de la página web de knitr , incluidas las herramientas para "publicación ligera" o para compartir en la web. Muchas de estas características ayudan a hacer que este enfoque sea más compatible con el flujo de trabajo general, en lugar de hacer algo solo al escribir el manuscrito.

Nota al pie histórica.

Si bien está arraigado en la "programación alfabetizada" de Knuth, como su nombre lo indica, el énfasis es bastante diferente, ya que la programación alfabetizada se enfoca en conectar el código y la documentación del software (en la comunidad R ese papel es desempeñado Roxygen, lo que remonta sus raíces a una rama diferente de el "árbol de programación alfabetizado").

Ir más allá

En principio, podríamos pedir mucho más de un documento dinámico, como la capacidad del lector para cambiar las entradas y ver las salidas sin tener que editar y volver a compilar todo el documento, por ejemplo, utilizando una plataforma interactiva en línea. XDynDocs puede ser un paso en esta dirección.

Otros enfoques

  • Podría querer vigilar a dexy.it
  • En un enfoque ligeramente diferente: un número cada vez mayor de artículos de economía alojan código asociado con publicaciones en http://www.runmycode.org/ , que volverá a ejecutar los análisis en la nube y permitirá parámetros de entrada personalizados o datos de entrada personalizados.
cboettig
fuente
Carl, he estado siguiendo tu sitio web por un tiempo, y tu enfoque con knitr fue una de las inspiraciones para mi pregunta. También he estado siguiendo a Dexy por un tiempo porque Zed Shaw lo usa para construir la fuente de su libro How To Learn Python the Hard Way (ver el repositorio de git ). Lo que me gusta de Dexy en comparación con otros enfoques de programación alfabetizados es que el código y el texto están acoplados libremente, lo que permite el uso sensato de un depurador.
Geoff Oxberry
Geoff, genial, gracias por los comentarios! Anna Nelson también cree en el desacoplamiento. Los usuarios de R pueden lograr el desacoplamiento en knitr con la externalización de código o la nueva spin()función. Personalmente, creo que las quejas de Greg Wilson sobre la programación alfabetizada son bastante anticuadas. Tuve la misma experiencia terrible que describe con noweb, pero esa depuración complicada simplemente no existe en las herramientas modernas. Para CI alfabetizado use doxygen. Knitr es algo más fácil de depurar que R gracias al almacenamiento en caché y al manejo del entorno.
cboettig
20

Lo que está pidiendo es el gran desafío de Elsivier del "Documento ejecutable" . Si bien se han probado muchos enfoques, ninguno es tan convincente como los autores podrían sugerir. Aquí hay algunos ejemplos de técnicas utilizadas.

Madagascar Project adopta su enfoque, dentro del guión make se ejecutan las simulaciones que producen las figuras y el papel simultáneamente.

IPython Notebook proporciona un documento que se puede ejecutar a medida que lee y produce cifras para el contenido de su corazón. (He visto complementos de palabras, Mathematica y muchas otras soluciones utilizadas de la misma manera)

VisTrails utiliza un enfoque de arquitectura orientado a servicios y proporciona un administrador de "providencia" o "flujo de trabajo". Básicamente, registra ganchos para codificar y luego diseña un flujo de trabajo o experimento que reproduce su trabajo. Se ha utilizado en muchos tipos de códigos, incluso en clústeres de HPC. Con este enfoque, tendrá una manera de reproducir los experimentos.

Hay toneladas de este tipo de soluciones, pero esas son las tres que me impresionaron. Es un problema difícil y creo que realmente ni siquiera estamos cerca de abordarlo. Ni siquiera podemos lograr que las personas publiquen su código con sus documentos, ¿cómo podemos esperar que reproduzcan los resultados = P

aterrel
fuente
En una vena similar hay sweave , que no es algo que yo use pero es intrigante en concepto.
dmckee
El Proyecto Madagascar parecía que podría ser interesante cuando escuché una charla de uno de sus autores. Sin embargo, no he tratado de usarlo.
Ken
@dmckee: Conozco personas que han tenido buen éxito con sweave y knitr . Soy receloso de los enfoques de programación alfabetizados por las mismas razones que Greg Wilson da en Carpintería de software : el papel y el código están demasiado unidos, lo que dificulta ejecutar un depurador en el código (y podría obstaculizar la prueba el texto).
Geoff Oxberry
Utilizo Sweave para este propósito, funciona muy bien y es compatible con Lyx. Org-mode es aún mejor y es compatible con los idiomas más comunes.
David LeBauer
13

No he tenido mucho éxito al usar las soluciones de otras personas para este problema. Por lo general, solo quiero algo simple que funcione para mí y haga el trabajo. Con este fin, generalmente trato de escribir un script de Python que se encargue de ejecutar todos los resultados, analizar el resultado, así como construir las figuras / tablas.

Escribo mis códigos para generar archivos de datos que contienen los resultados en algún formato de texto. Puede evitar volver a ejecutar estos resultados en su script probando primero la existencia del archivo de salida (en python usando os.path.isfile (), por ejemplo). Si desea volver a ejecutar sus resultados, simplemente elimine los archivos de datos. Si existen los archivos de datos, entonces ejecuto un analizador de estos archivos. Para esto, el módulo python para expresiones regulares es muy útil (re).

Luego, a partir de la salida analizada, creo las figuras o tablas. Para las tablas en látex, puede escribir el código para generar la tabla en un archivo separado (uso una extensión .tbl) y luego incluir esto en su archivo de látex. La clave para mí es usar 1 script de Python. Si tengo muchos, luego me pregunto cuál es cuál y qué hacen. Si esta descripción es demasiado vaga, puedo enviarle algunos ejemplos.

Nathan Collier
fuente
1
Ya hago este tipo de cosas para las cifras. Sin embargo, en los documentos que estoy escribiendo, las tablas serían un formato poco natural para presentar los datos. Muchas veces, realmente solo quiero incluir la condición inicial de una EDO (entonces realmente, algo así como números 4-6, separados por comas), o una matriz completa de números como parte del lado derecho de una ecuación. Me gusta tu idea para las mesas. Para los casos que mencioné, siento que reformatearlos como tablas no sería natural, y me gustaría incluir los datos en un formato más natural.
Geoff Oxberry
Nathan, ¿te importaría publicar ejemplos? Uso el mismo enfoque, excepto que confirmo los archivos de texto en git, y uso git para administrar los resultados. Luego tengo scripts de Python para producir gráficos / tablas. Tengo un script por parcela o tabla.
Ondřej Čertík
También puede canalizar la salida de un script de shell directamente a latex usando el comando \input{|"path-to-script.py"}. Creo que es mejor poner todos los parámetros en un solo archivo de Python (o cualquier idioma que sea su favorito) y usar el parámetro de línea de comando para acceder a él \input{|"path-to-script.py param-name"}. En este caso, puede incluir el archivo param en otros scripts para ejecutar las simulaciones. Sin embargo, hace que la compilación sea más lenta y tiene algunos otros puntos negativos.
Helio el
7

Aún más importante, en mi opinión, es asegurarse de que pueda descubrir cómo volver a generar todos sus resultados desde cero en un mes o un año (por ejemplo, cuando los árbitros le piden que agregue o modifique algo). Para ese propósito, lo que hago es incluir un archivo de texto con instrucciones muy detalladas sobre cómo reproducir todos los resultados. Es mejor si los prueba haciendo que alguien más (como un coautor) los pruebe. Recomiendo que también proporcione estas instrucciones (y todo su código) a los árbitros y lectores.

Aquí hay un ejemplo (realmente preparado por mi coautor, Aron Ahmadia).

David Ketcheson
fuente
Lo he hecho antes (por mi propia cordura) y, afortunadamente, valió la pena cuando mi asesor me pidió que volviera a generar y volver a comprobar los resultados. Desde entonces, simplemente cambié el código fuente de un script que ejecuta todo en un apéndice de mis borradores para que esté allí, sé lo que hice y puedo hacer clic en un botón para obtener todos los números y cifras.
Geoff Oxberry
El script no hace ninguna instalación en este momento, porque es solo un script de MATLAB. En la documentación de la función, enumera las dependencias de los paquetes de terceros. Esos paquetes de terceros, a su vez, tienen una documentación clara sobre cómo instalarlos (y afortunadamente, también son compatibles, tienen excelentes desarrolladores y listas de correo activas).
Geoff Oxberry
6

El orgmode de Emacs en combinación con Babel logra eso. Babel puede ejecutar fragmentos de código de varios lenguajes de programación y scripts, por ejemplo, podría abrir el archivo que contiene los datos de simulación y ponerlo en una tabla en orgmode, que puede exportarse a LaTeX (y muchos otros formatos). Lleva bastante tiempo acostumbrarse a todos los combos de teclas en orgmode, pero una vez que se ejecuta, todo es automático.

Robert
fuente
Me gusta el modo org; Lo uso para contornos. No lo he usado con Babel. Tendré que probarlo.
Geoff Oxberry
Aquí hay una excelente descripción de enero de 2012 J. Stat. Software jstatsoft.org/v46/i03/paper
David LeBauer
Escribí un tutorial que muestra cómo convertir la plantilla LaTeX del European Physical Journal A (EPJ A) en un archivo de modo org.
Melioratus
4

Si ejecutar todo su código es barato, entonces podría hacer algo de baja tecnología como lo siguiente:

Puede modelar sus documentos con cadenas formateadas para que se vean así

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

Tener scripts de Python que se vean así

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

Y luego haz algo como esto

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

Entonces podría envolver esto en un Makefile.

MRocklin
fuente
Mi primer pensamiento cuando escribí esta pregunta fue una solución como la que usted propuso. Originalmente estaba pensando en algo de baja tecnología como usar un preprocesador macro, pero Python es probablemente un enfoque mejor (y ciertamente más legible), entonces un sistema de compilación puede manejar la regeneración incremental de resultados.
Geoff Oxberry
Realmente esta es solo una implementación muy básica de algo como las páginas del servidor Python. La idea del contenido generado automáticamente ha estado presente en la comunidad web por un tiempo. Sería bueno verlo migrar a la academia.
MRocklin
Convenido. Jinja2 podría usarse para hacer lo que has sugerido. De hecho, eso es lo que hace dexy , pero con un montón de filtros geniales que también manejan el resaltado de sintaxis y otras tareas diversas.
Geoff Oxberry
4

Si está utilizando LaTeX, una solución relativamente de baja tecnología es hacer que su código escupe un archivo (o usar un script para filtrar desde la salida de su código) que contiene un montón de líneas como esta:

\newcommand{\myresults1}{<value>}

Luego puede usar el \inputcomando para agregar ese archivo a su documento, y usar los comandos definidos para colocar los valores.

Aesin
fuente
2

Yo trabajo para Elsevier. Mi compañía ha comenzado a usar el marco Collage (desarrollado en respuesta al Gran desafío del papel ejecutable) en números de revistas para permitir a los autores publicar fragmentos de código ejecutable con su artículo. Esta característica facilita a los lectores reproducir los resultados informados en el artículo y reutilizar el material publicado para su propia investigación. Collage admite una amplia variedad de software de código abierto y propietario; Puede encontrar más información en el video informativo aquí y en el sitio web de Collage Authoring Environment .

Hylke Koers
fuente
El segundo enlace es a lo incorrecto.
David Ketcheson
@Hylke Koers: ¿Querías poner este enlace: collage.elsevier.com ?
Paul
@Paul: hice las ediciones; El segundo enlace original fue al Collage Google Group. Tal vez un mejor vínculo sería con el Collage, pero mi objetivo era tratar (principalmente) de preservar las buenas intenciones de la publicación mientras eliminaba las partes que lo hacían sonar promocional. Siéntase libre de editar la publicación como mejor le parezca.
Geoff Oxberry