-
Notifications
You must be signed in to change notification settings - Fork 11
/
Copy pathRepro_ms.Rmd
310 lines (131 loc) · 40.3 KB
/
Repro_ms.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
---
title: "| Ciencia reproducible: qué, por qué, cómo \n| Reproducible science: what, why, how\n"
author: Francisco Rodríguez-Sánchez^1^, Antonio Jesús Pérez-Luque^2\*^, Ignasi Bartomeus^1\*^, Sara Varela^3\*^
output:
word_document:
fig_caption: yes
fig_height: 6
fig_width: 7.5
highlight: null
reference_docx: Ecosistemas_template.docx
bibliography: references.bib
csl: ecosistemas.csl
---
> (1) Departamento de Ecología Integrativa, Estación Biológica de Doñana (EBD-CSIC), Consejo Superior de Investigaciones Científicas, Avda. Américo Vespucio s/n, E-41092 Sevilla, España.
> (2) Laboratorio de Ecología (iEcolab), Instituto Interuniversitario Sistema Tierra (CEAMA), Universidad de Granada, Avda. del Mediterráneo s/n, Granada 18006, España.
> (3) Departamento de Ciencias de la Vida, Facultad de Biología, Ciencias Ambientales y Química, Universidad de Alcalá, Campus Universitario. Ctra. Madrid-Barcelona, Km. 33,600, 28805 Alcalá de Henares, Madrid, España.
> (*) Estos autores contribuyeron de manera equivalente y el orden se determinó ejecutando en R: `sample(c("AJPL", "IB", "SV"))`.
> Autor para correspondencia: F. Rodríguez-Sánchez [frodriguez.work@gmail.com]
# Resumen
> **Ciencia reproducible: qué, por qué, cómo**. La inmensa mayoría de los estudios científicos no son reproducibles: resulta muy difícil, si no imposible, trazar todo el proceso de análisis y obtención de resultados a partir de un conjunto de datos - incluso tratándose de los mismos investigadores. La trazabilidad y reproducibilidad de los resultados son sin embargo condiciones inherentes a la ciencia de calidad, y un requisito cada vez más frecuente por parte de revistas y organismos financiadores de la investigación. Los estudios científicos reproducibles incluyen código informático capaz de recrear todos los resultados a partir de los datos originales. De esta manera el proceso de análisis queda perfectamente registrado, se reduce drásticamente el riesgo de errores, y se facilita la reutilización de código para otros análisis. Pero la ciencia reproducible no sólo acelera el progreso científico sino que también reporta múltiples beneficios para el investigador incluyendo ahorro de tiempo y esfuerzo, incremento de la calidad e impacto de las publicaciones. En este artículo explicamos en qué consiste la reproducibilidad, por qué es necesaria en ciencia, y cómo podemos hacer ciencia reproducible. Presentamos una serie de recomendaciones y herramientas para el manejo y análisis de datos, control de versiones de archivos, organización de ficheros y manejo de programas informáticos que nos permiten desarrollar flujos de trabajo reproducibles en el contexto actual de la ecología.
# Abstract
> **Reproducible science: what, why, how**. Most scientific papers are not reproducible: it is really hard, if not impossible, to understand how results are derived from data, and being able to regenerate them in the future (even by the same researchers). However, traceability and reproducibility of results are indispensable elements of high-quality science, and an increasing requirement of many journals and funding sources. Reproducible studies include code able to regenerate results from the original data. This practice not only provides a perfect record of the whole analysis but also reduces the probability of errors and facilitates code reuse, thus accelerating scientific progress. But doing reproducible science also brings many benefits to the individual researcher, including saving time and effort, improved collaborations, and higher quality and impact of final publications. In this article we introduce reproducible science, why it is important, and how we can improve the reproducibility of our work. We introduce principles and tools for data management, analysis, version control, and software management that help us achieve reproducible workflows in the context of ecology.
# Palabras clave
> análisis de datos; ciencia abierta; ecoinformática; ecología; programación; R; reproducibilidad
# Keywords
> data analysis; ecoinformatics; ecology; open science; programming; R; reproducibility
# Introducción
¿Cuántas veces hemos querido revisitar un análisis estadístico meses o años después y no hemos sido capaces, bien porque no recordamos cómo hacerlo o los datos no están fácilmente disponibles? ¿Cuánto tiempo perdemos en rehacer análisis estadísticos, figuras o tablas tras corregir un error en los datos, o siguiendo las recomendaciones de un revisor? ¿Cuánto tiempo invertimos intentando implementar un nuevo método de análisis a partir de la escueta descripción proporcionada en un artículo? ¿Cuántas veces hemos intentado recabar datos infructuosamente porque los autores han perdido los datos, su formato es ilegible hoy en día, o simplemente se niegan a compartirlos?
Todas estas escenas son desgraciadamente frecuentes en el día a día de los científicos, y evidencian un grave problema de reproducibilidad en ciencia [@Peng2011]. La inmensa mayoría de los artículos científicos no son reproducibles, esto es, resulta muy difícil o incluso imposible trazar claramente el proceso de obtención de los resultados y volver a obtenerlos (reproducirlos) ¡incluso tratándose del mismo equipo de autores! En este artículo discutimos por qué los resultados científicos deben ser reproducibles, presentamos las ventajas de adoptar un flujo de trabajo reproducible, e introducimos las principales herramientas para ello.
# ¿Qué es la ciencia reproducible?
| *"A scientific article is advertising, not scholarship.*
| *The actual scholarship is the full software environment, code and data,*
| *that produced the result."*
| @Claerbout1992
La ciencia se caracteriza por seguir unas pautas metodológicas que garantizan su validez epistemológica [@Pigliucci2013g]. La confrontación rigurosa de hipótesis con evidencias empíricas (observacionales o experimentales) y el escrutinio público de los resultados contribuyen a garantizar que las conclusiones sean ciertas. Es por ello que los artículos científicos tienen una sección de métodos explicando los pasos seguidos en la recolección y análisis de datos. Esta información resulta crucial para examinar la veracidad y robustez de las conclusiones del artículo, así como para permitir futuras repeticiones del estudio por otros autores. Sin embargo, en la mayoría de ocasiones la escueta descripción verbal que aparece en la sección de métodos resulta insuficiente para conocer todos los detalles del análisis [@Ince2012, **Fig. 1**]. Este problema resulta cada vez más acuciante con el aumento de la complejidad de los análisis estadísticos [@Michener2012].
Un estudio científico es reproducible si el texto del artículo viene acompañado de código (texto interpretable por un ordenador) que permite recrear exactamente a partir de los datos originales todos los resultados y figuras incluidos en el artículo [@Peng2011; @Marwick2016]. El concepto es por tanto diferente al de repetibilidad, que se refiere a la posibilidad de replicar el mismo estudio (con nuevos datos) a partir de la información proporcionada en el artículo. La reproducibilidad se relaciona principalmente con la transparencia, trazabilidad, y completitud del protocolo seguido para llegar a unos resultados concretos a partir de un conjunto de datos determinado. La reproducibilidad no es una cualidad binaria sino un gradiente que va desde trabajos totalmente irreproducibles (que sólo contienen el texto, tablas y figuras finales) a estudios perfectamente reproducibles donde la integración de texto, código y datos permite regenerar fácilmente el resultado final a partir de los datos originales [e.g. @Goring2013c; @FitzJohn2014, **Fig. 1**].
# ¿Por qué es necesaria la reproducibilidad en ciencia?
| *"Every analysis you do on a dataset will have to be redone*
| *10–15 times before publication. Plan accordingly."*
| [Trevor A. Branch](https://twitter.com/TrevorABranch/status/648987799648014336)
La reproducibilidad es un pilar fundamental del método científico: los resultados deben estar basados en datos y evidencias perfectamente contrastables. De hecho, ningún estudio científico puede garantizar que sus resultados sean correctos, pero sí reproducibles [@Peng2011]. La reproducibilidad es por tanto una garantía de transparencia y calidad: los artículos reproducibles están mejor blindados frente a errores, y cuando los contienen son detectados y corregidos más fácilmente [@Hayden2015]. Además, la reutilización de código pre-existente por parte de otros autores contribuye a acelerar el progreso científico. En los últimos años ha aumentado la presión por incrementar la reproducibilidad de los trabajos científicos, tras la creciente detección de errores graves en artículos que carecen de garantías de reproducibilidad [@Alberts2015b; @NatureEditorial2014a; @NatureEditorial2014b]. De hecho, el número de revistas y fuentes de financiación que requieren la publicación de datos y código no para de crecer [@Stodden2013].
Pero la reproducibilidad no debería ser vista como una obligación impuesta externamente, sino como una oportunidad de mejorar nuestra manera de hacer ciencia y la contribución de nuestros trabajos al avance científico general. Hacer ciencia reproducible trae consigo múltiples ventajas para el investigador (ver **Tabla 1**), a pesar del esfuerzo inicial que implica siempre aprender nuevas técnicas de trabajo.
Para empezar, tener flujos de trabajo reproducibles evita muchos de los problemas planteados al comienzo de este artículo. Por ejemplo, tras corregir un error en los datos o introducir nuevas observaciones podemos volver a generar - sin ningún esfuerzo extra - todas las tablas, figuras y resultados de un trabajo. Esto no sólo ahorra tiempo sino que disminuye drásticamente los errores en el manuscrito final. Igualmente, la existencia de un código que documenta fielmente el proceso de análisis facilita además tanto la escritura del manuscrito como su interpretación por coautores, revisores y los lectores finales [@Markowetz2015a]. Además, dicha transparencia le da un sello de calidad al trabajo y facilita su aceptación, incrementando su impacto posterior en términos de citas y reconocimiento [@Piwowar2007; @Vandewalle2012]. Por ejemplo, la revista *Molecular Ecology* menciona en sus [instrucciones a los autores](http://onlinelibrary.wiley.com/journal/10.1111/%28ISSN%291365-294X/homepage/ForAuthors.html) que "los artículos con archivado de datos y código son más valiosos para investigaciones futuras, por lo que, a igualdad de condiciones, se les dará mayor prioridad para su publicación". La existencia de un código ordenado y bien estructurado permitirá además su reutilización en proyectos posteriores, ahorrando tiempo y esfuerzos al equipo de investigación [@Garijo2013]. Además, compartir públicamente el código con el que generamos unos resultados puede ayudarnos a identificar errores (idealmente antes de su publicación) y abrir nuevas líneas de colaboración [@Hampton2015a].
# Cómo hacer ciencia reproducible
| *"You can't reproduce if you don't understand where a number came from.*
| *You can't reproduce what you don't remember. And trust me: you won't.*
| *You can't reproduce what you've lost.*
| *What if you need access to a file as it existed 1, 10, 100, or 1000 days ago?"*
| @Bond-Lamberty2014a
Adoptar un flujo de trabajo reproducible (**Fig. 2**) requiere un esfuerzo inicial importante. Es necesario familiarizarse con diversas herramientas (bases de datos, programación, sistemas de control de versiones) lo cual lleva su tiempo. Recibir una formación adecuada y temprana (idealmente previa a la realización del proyecto de máster o doctorado) facilita mucho las cosas. Dado que el interés por la ciencia reproducible es bastante reciente, en nuestro país la formación es aún escasa, aún más en el campo de la ecología. Pero existen cursos, libros y material de aprendizaje fácilmente disponibles (ver **Apéndice 1**).
La reproducibilidad no es una cualidad binaria sino un gradiente (**Fig. 1**) y conviene implementarla paso a paso en nuestra investigación para facilitar la transición. Un ejemplo extremo de irreproducibilidad sería aquel donde los datos son manipulados en una hoja de cálculo (e.g. Microsoft Excel, LibreOffice Calc), posteriormente analizados manualmente en programas estadísticos (como Statistica o SPSS), el manuscrito redactado en un procesador de texto (e.g. Microsoft Word, Google Docs), las figuras realizadas en un programa gráfico (e.g. SigmaPlot, Adobe Illustrator, Photoshop), y los valores de las tablas copiados a mano. Afortunadamente, cada vez es más frecuente que los análisis se hagan mediante código (mayoritariamente R o Python), lo cual representa un avance importante en cuanto a reproducibilidad. Sin embargo, dicho flujo de trabajo incluye todavía múltiples pasos manuales que rompen su dinamismo, no dejan registro de las operaciones realizadas, y abren la puerta a la introducción de errores (por ejemplo, al copiar manualmente múltiples valores a una tabla). En el otro extremo de este gradiente de reproducibilidad estarían los análisis puramente integrados donde el trabajo final puede ser reconstituido a partir de los datos originales con un solo comando o clic del ratón (**Fig. 1**).
A continuación presentamos los elementos más importantes de un flujo de trabajo reproducible (**Fig. 2**) e introducimos las principales herramientas disponibles para el manejo de datos, análisis de datos mediante código, control de versiones, la organización de los archivos, y el manejo de las dependencias de software externo. En el **Apéndice 1** hemos incluido un listado de recursos que profundizan más en cualquiera de estos aspectos.
## Recolección y manejo de datos
El proceso de recolección y manejo de datos resulta crucial, ya que cualquier error en esta primera etapa se propagará hasta los resultados finales. Por tanto es muy importante garantizar la calidad de este proceso, que podría dividirse en cinco etapas [@Michener2012]:
### Planificación
Una buena planificación es la mejor forma de asegurar la calidad de los datos, multiplicando su valor durante y después de finalizado el proyecto [@Ruegg2014]. Muchas instituciones (como la National Science Foundation de Estados Unidos) requieren la presentación de un 'data management plan' con cada proyecto (http://www.nsf.gov/bio/biodmp.jsp). Dicho plan debe incluir información detallada acerca de qué datos se van a obtener y cómo van a recogerse, almacenarse y compartirse [@Michener2012; @Michener2015] (por ejemplo véase https://www.dataone.org/sites/all/documents/DMP_Copepod_Formatted.pdf). Para ello, existen herramientas como DMPTool (https://dmptool.org/) muy útiles para elaborar esta planificación.
### Recolección
El proceso de obtención de datos ecológicos varía enormemente según el tipo de estudio, desde la captura de organismos en el campo hasta descarga de imágenes de satélite. A pesar de esta heterogeneidad, un principio común a seguir es intentar conservar los datos brutos en su estado original de la mejor manera posible (por ejemplo, insectos capturados en un museo o una colección, fichas de campo en un archivo seguro, imágenes o capas GIS en un repositorio), con un identificador único. Esto nos permite establecer claramente qué conjunto de datos se ha utilizado para un análisis, así como revisar/reutilizar estos datos en el futuro. Igualmente, la metodología de obtención de datos debe quedar perfectamente registrada.
### Descripción del conjunto de datos (metadatos)
Todo conjunto de datos debe ir acompañado de una descripción detallada de lo que representa cada variable, cómo y dónde se tomó, en qué unidades está medida, cuándo se tomaron los datos, quien los tomó, etc. Esta información, conocida como metadatos, resulta necesaria para una correcta interpretación de los datos [@Michener1997], y además multiplica su utilidad favoreciendo la reutilización [@Alonso2006; @Fegraus2005; @Ruegg2014].
Aunque los metadatos pueden alojarse en un simple fichero de texto, es muy conveniente utilizar un sistema estándar pues facilita la validación, integración y síntesis de los datos de manera automatizada [@Alonso2006]. Existen diferentes estándares de metadatos en función del propósito y la disciplina científica. En ecología existe el estándar llamado 'Ecological Metadata Language' (EML) (http://knb.ecoinformatics.org/software/eml/) que se utiliza por ejemplo en las redes de seguimiento ecológico a largo plazo (LTER, Long-Term Ecological Research; @Vanderbilt2015). Existen varias herramientas para crear o editar metadatos, como `Morpho` (http://knb.ecoinformatics.org/morphoportal.jsp), `DEIMS` (https://data.lter-europe.net/deims/, utilizado en la red LTER), o el paquete de R `eml` (https://github.com/ropensci/EML/).
### Control de calidad
El control de calidad de los datos es un paso imprescindible pero frecuentemente obviado. Siempre se introducen errores, ya sea en la toma de datos en el campo o al introducirlos en un ordenador, y es importante detectarlos y depurarlos. La utilización de plantillas que restrinjan el tipo de datos introducido (e.g. fecha en un formato determinado, valores numéricos dentro de un rango determinado, especie a elegir de un listado predefinido) evita la introducción de muchos errores desde el principio. En cualquier caso, es conveniente realizar un control de calidad final comprobando que todos los datos se ajustan a unos valores adecuados o razonables. Este control de calidad puede hacerse de manera reproducible e iterativa mediante funciones de importación de datos que incluyen tests para comprobar la validez de los datos (e.g. ver http://ropensci.org/blog/2015/06/03/baad). Además, es importante seguir algunas normas básicas de estructuración de la base de datos [@Wickham2014a] para facilitar su análisis posterior (e.g. ver http://kbroman.org/dataorg/ o http://www.datacarpentry.org/spreadsheet-ecology-lesson/).
### Preservación
Finalmente, debemos buscar la forma de asegurar que nuestros datos seguirán estando disponibles a largo plazo. Un estudio reciente [@Vines2014] estimó que la disponibilidad de los datos se reduce con el tiempo a una alarmante tasa anual del 17%. En muchos casos, la dificultad de acceso a los datos se debe a su almacenamiento en formatos propietarios o dispositivos digitales obsoletos; otras veces simplemente se extravían. Actualmente, la mejor manera de asegurar la persistencia de los datos a largo plazo [@White2013; @Hart2016] es alojarlos en formato abierto (e.g. txt o csv para datos tabulados, png para imágenes) en un repositorio oficial de los muchos que hay disponibles (ver http://www.re3data.org/). Muchos de estos repositorios están orientados a la difusión pública de los datos, pero otros permiten alojamiento privado (e.g. Figshare, KNB, Open Science Framework). Estos repositorios otorgan un identificador único y persistente (DOI, Digital Object Identifier) a los datos, facilitando su reutilización y citación. Existen múltiples programas que permiten subir, actualizar y descargar datos fácilmente desde estos repositorios (e.g. ver http://ropensci.org/packages/#data_publication). El alojamiento en la nube representa por tanto la mejor opción para la conservación de los datos [@Hart2016].
## Análisis de datos y documentos dinámicos
Para que un estudio sea reproducible, todo el análisis debe realizarse mediante 'scripts' de código, desde la manipulación de datos hasta la generación de tablas y figuras. Eso significa que debemos evitar hacer ningún cambio directamente sobre los datos originales (e.g. en una hoja de cálculo como Microsoft Excel): los datos originales son intocables, y cualquier modificación posterior debe realizarse mediante código de manera que quede un registro de todos los cambios realizados.
La utilización de código trae consigo una serie de ventajas frente al análisis manual mediante clics. En primer lugar, el análisis manual es totalmente irreproducible, a diferencia del código que es interpretable tanto para humanos como computadoras. El código contiene un registro perfecto de todos los pasos seguidos en el análisis, muy útil para compartir con colaboradores o reutilizar algún tiempo después (siempre que podamos reproducir el entorno de computación, véase sección de dependencias externas más abajo). Además, la utilización de código permite automatizar tareas, ahorrando tiempo al investigador.
En ecología y otras muchas disciplinas científicas el lenguaje de programación dominante desde hace años es R (www.r-project.org). R es un lenguaje gratuito, de código abierto, inicialmente dirigido al análisis de datos y la visualización, pero cuyos usos no paran de crecer gracias a una comunidad muy activa de usuarios-desarrolladores que contribuyen sus propios 'paquetes' con funciones (ver https://cran.r-project.org/web/packages/available_packages_by_name.html). Además de R, existen otros lenguajes de programación bastante extendidos como Python, C, C++, MATLAB, etc. [@Bass2008].
La aparición en el último lustro de herramientas para generar documentos dinámicos a partir de un conjunto de datos y código ([knitr](http://yihui.name/knitr/) y [rmarkdown](http://rmarkdown.rstudio.com) en R, [IPython](http://ipython.org/) para Python, [Jupyter](https://jupyter.org/) para múltiples lenguajes) ha supuesto una auténtica revolución en el campo de la ciencia reproducible. Estos programas integran texto y código de manera que es posible regenerar todas las tablas, figuras y resultados presentes en un artículo, libro o informe con un solo clic (**Fig. 3**). Ello nos libra por tanto de tener que volver a copiar manualmente todos los valores de una tabla o rehacer figuras con cada iteración del análisis. Por tanto, utilizar documentos dinámicos no sólo ahorra tiempo sino que también reduce la probabilidad de cometer errores: todos los resultados son perfectamente trazables a partir de los datos originales.
En el caso concreto de R, la integración de rmarkdown en Rstudio (www.rstudio.com) facilita la tarea de escribir artículos, tesis, páginas web e incluso presentaciones totalmente reproducibles (véase http://rmarkdown.rstudio.com). A modo de ejemplo, este artículo está escrito íntegramente en Rmarkdown (véase el código fuente aquí: https://github.com/ecoinfAEET/Reproducibilidad). Aquí (https://github.com/Pakillo/rmdTemplates) puede descargarse una plantilla para escribir artículos en Rmarkdown para la revista Ecosistemas [@RodriguezSanchez2016].
## Control de versiones
| *"Your closest collaborator is you 6 months ago,*
| *and you don't respond to emails."*
| P. Wilson
El control de versiones es otro de los nudos conflictivos a lo largo del desarrollo de un proyecto. El sistema más común -y problemático- de control de versiones consiste en guardar copias de los ficheros con distintos nombres (**Fig. 4**), en un intento de tener un archivo de todos los cambios aplicados al documento. Este sistema lleva a la acumulación desmesurada de archivos muy similares cuyas modificaciones no son fácilmente comparables, y dificulta reconstruir la historia del proyecto, volver atrás en caso de detectar errores, o colaborar con varios coautores haciendo modificaciones sobre el mismo documento. Herramientas como [Google Docs](http://docs.google.com), [Dropbox](http://dropbox.com), [Overleaf](http://overleaf.com) o [Authorea](http://authorea.com) representan un gran avance al respecto, pero están más enfocadas a la escritura colaborativa de manuscritos que a la integración dinámica de datos, texto, y código ejecutable como en los documentos de Rmarkdown o IPython.
Los sistemas de control de versiones se encargan de monitorizar automáticamente los cambios realizados en cualquier fichero, registrando *quién* hizo *qué* cambio, *cuándo* y *por qué* [@Blischak2016], de forma que es posible recuperar distintas versiones del fichero en todo momento. En el campo de la programación existen sistemas de control de versiones muy eficientes que recientemente se han incorporado como herramientas básicas de la ciencia reproducible [@Ram2013a]. `Git` (https://git-scm.com/) es el sistema más utilizado hoy día, en conjunción con plataformas de internet como `GitHub` (https://github.com), `BitBucket` (https://bitbucket.org/), o `GitLab` (https://gitlab.com/). `Git` facilita enormemente la tarea de archivar, reconstruir y navegar por la historia de un proyecto. La integración de git en plataformas como `GitHub` facilita además enormemente el desarrollo conjunto de análisis, código y texto entre todos los colaboradores de un proyecto. A modo de ejemplo, este artículo se escribió utilizando `git` para el control de versiones y `GitHub` para la colaboración y discusión entre los autores. El desarrollo completo del artículo (incluyendo quién hizo qué cambios, cuándo y por qué) está disponible públicamente en `GitHub`: https://github.com/ecoinfAEET/Reproducibilidad/commits/master.
## Organización de ficheros
Mantener un sistema consistente de organizar todos los archivos relacionados con un proyecto es otro punto importante para garantizar su reproducibilidad (y hacer la vida del investigador más fácil). Cuando no se tiene ningún criterio los archivos se acumulan desordenadamente y resulta muy difícil manejar los distintos componentes del proyecto (datos, código, figuras, texto...). Esto no sólo dificulta la comprensión y reutilización en el futuro, sino que también favorece la aparición de errores incontrolados.
Hay muchas maneras de organizar un proyecto, y cada investigador elige la más conveniente en su caso. Pero sí existen algunos principios básicos [@Noble2009, véase también enlaces en **Apéndice 1**]: (i) todos los ficheros relacionados con el proyecto deben estar dentro del mismo directorio (e.g. un proyecto de Rstudio); (ii) existen subdirectorios independientes para los datos, código, figuras, resultados y manuscrito; (iii) los datos originales permanecen inalterados en un directorio aparte; (iv) los datos derivados se generan mediante 'scripts'; (v) las funciones se definen en ficheros independientes del código que ejecuta el análisis; (vi) en el directorio raíz hay un fichero README que describe el proyecto y sus componentes, y un 'script' maestro ('makefile') que ejecuta todos los análisis.
Convenientemente, todos estos principios son compatibles con la estructura de un paquete de R (**Fig. 5**). Un paquete de R no es más que una forma estándar de organizar el código que nos permite ser más eficientes a la hora de utilizarlo, compartirlo y editarlo [@Varela2015]. Todos los paquetes de R tienen una estructura estándar con una carpeta 'R' donde residen las funciones, una carpeta 'man' que contiene los ficheros de ayuda de esas funciones, un fichero de texto 'NAMESPACE' (generado automáticamente) que especifica las funciones contenidas en el paquete y si dependen de funciones contenidas en otros paquetes, y un fichero 'DESCRIPTION' con los metadatos del paquete: nombre, objetivos, autores, y sus dependencias de otros paquetes. Además pueden añadirse carpetas incluyendo archivos de datos, tests para las funciones, etc. [@Wickham2015b] por lo que la estructura, siendo estándar, mantiene su flexibilidad.
Crear un paquete de R es mucho más fácil de lo que puede parecer (ver **Apéndice 2**), y organizar un proyecto de investigación utilizando esa estructura estándar tiene muchas ventajas (cf. https://github.com/ropensci/rrrpkg), entre ellas: (i) el paquete provee una estructura de directorios para mantener los archivos organizados; (ii) las funciones creadas para el análisis quedan documentadas, facilitando su reutilización posterior; (iii) las funciones pueden llevar tests asociados para comprobar que funcionan correctamente, incrementando la robustez del análisis; (iv) se describen explícitamente las dependencias de nuestro análisis en otros paquetes o programas externos, facilitando la reproducibilidad del proyecto.
## Dependencias externas
Todo análisis reposa sobre plataformas, paquetes o programas que cambian a lo largo del tiempo. En consecuencia, es muy frecuente que un código deje de funcionar al introducirse cambios en alguno de los paquetes de los que depende el proyecto [@Ooms2013]. Igualmente, para poder reproducir un análisis en otro ordenador habrá que instalar primero todas los programas necesarios. Por estos motivos conviene documentar las dependencias externas de nuestro análisis (por ejemplo qué paquetes de R se utilizan, especificando la versión), y asegurarse de que dicho software estará disponible en el futuro.
Hay muchas maneras posibles de registrar las dependencias de nuestro proyecto. En R, una de las más sencillas es ejecutar la función `sessionInfo()` (o su equivalente `session_info` del paquete `devtools`) al finalizar el análisis. Este comando devuelve un listado estructurado de todos los paquetes utilizados, especificando su versión. Esta información puede ser procesada directamente por paquetes como `switchr` [@Becker2015] para instalar todas las dependencias requeridas en cualquier otro ordenador. Otras opciones incluyen el uso de los paquetes `rctrack` [@Liu2014b], `checkpoint` [@Analytics2015] y `packrat` [@Ushey2015]. Mientras `rctrack` y `packrat` almacenan una copia local de todos los paquetes utilizados en un proyecto, `checkpoint` descarga los paquetes desde un servidor de internet cuando se ejecuta. Todos estos métodos son muy fáciles de utilizar y garantizan la reproducibilidad de nuestro proyecto en el futuro aunque cambien los paquetes o dependencias externas. Otras alternativas más avanzadas y versátiles incluyen `docker` [@Boettiger2015] y `drat` [@Eddelbuettel2015]. En el **Apéndice 1** hemos incluido enlaces para iniciarse en el uso de todas ellas.
# Conclusiones
La trazabilidad y reproducibilidad de los resultados científicos son cualidades inherentes a la ciencia de calidad. Hacer ciencia de manera reproducible no sólo es un requisito creciente en muchas revistas y fuentes de financiación sino que además aporta muchas ventajas para el investigador. A la larga, la ciencia reproducible ahorra tiempo y esfuerzo, reduce el riesgo de cometer errores y aumenta el impacto y utilidad de los trabajos en la comunidad científica.
Desarrollar estudios plenamente reproducibles requiere un esfuerzo inicial de aprendizaje. Creemos que aquí se aplica bien la máxima de que 'es importante aprender a nadar antes de estar hundiéndonos'. Invertir esfuerzo en adoptar flujos reproducibles puede parecer una pérdida de tiempo al principio, pero en el futuro puede ahorrarnos muchos problemas. El tiempo invertido en aprender a utilizar herramientas como `git` o `rmarkdown` se ve recompensado cuando podemos regenerar todo un manuscrito, tablas y figuras incluidas, con un solo clic. No solo ahorramos esfuerzo, sino que nos aseguramos de que los resultados están actualizados y libres de errores.
La transición hacia la reproducibilidad puede hacerse gradualmente. Un buen punto de partida es la utilización de código ('scripts') para todo el proceso de manejo y análisis de datos, así como producción de figuras. Este código debe ser capaz de generar los resultados finales a partir de los datos originales, y ambos pueden publicarse junto con el manuscrito para hacerlo más reproducible. Igualmente, podríamos empezar a utilizar repositorios de datos en la nube (e.g. Open Science Framework, Figshare) para almacenar, versionar y compartir nuestros datos. El siguiente paso podría ser estructurar nuestro código en un documento dinámico (Rmarkdown/IPython). Finalmente puede incorporarse un sistema de control de versiones (e.g. git/GitHub) para guardar un registro del desarrollo del proyecto y facilitar la colaboración con otros investigadores. Esperamos que este artículo anime a muchos investigadores a adoptar estas prácticas, y que las pautas y recursos aquí recogidos faciliten la transición hacia una ciencia más reproducible.
# Agradecimientos
FRS está financiado por una ayuda de formación postdoctoral del Ministerio de Economía y Competitividad. SV tiene un contrato postdoctoral del programa propio de la Universidad de Alcalá. Los autores desean agradecer expresamente a todos los programadores, instituciones y empresas que hacen posible, muchas veces de manera altruista, la ciencia reproducible.
# Referencias
###### TABLA 1
**Tabla 1**. Ventajas para el investigador derivadas de la adopción de flujos de trabajo reproducibles.
**Table 1**. Personal benefits for researchers from developing reproducible workflows .
```{r tabla1, echo = FALSE, results = "asis"}
tabla1 <- read.csv("tablas/tabla_ventajas_reproducibilidad.csv", header = FALSE)
colnames(tabla1) <- "Beneficios de la ciencia reproducible para el investigador"
pander::pandoc.table(tabla1, split.table = Inf, split.cells = 100, justify = "left")
```
###### TABLA 2
**Tabla 2**. Criterios y recomendaciones para incrementar la reproducibilidad de nuestra investigación.
**Table 2**. Checklist of criteria and recommendations to increase the reproducibility of our research.
```{r tabla2, echo = FALSE, results = "asis"}
tabla2 <- read.csv("tablas/checklist.csv", header = FALSE)
colnames(tabla2) <- "Criterios de reproducibilidad"
pander::pandoc.table(tabla2, split.table = Inf, split.cells = 100, justify = "left")
```
###### PIES DE FIGURA
**Figura 1**. La reproducibilidad no es una cualidad binaria sino un gradiente [@Peng2011]. Los artículos científicos que sólo contienen el texto, resultados y figuras finales (por ejemplo en un único archivo pdf) son los menos reproducibles: es imposible reconstruir detalladamente el proceso de análisis desde los datos originales hasta los resultados finales. La publicación de los datos y/o el código empleado para el análisis contribuyen a mejorar la reproducibilidad. Igualmente, la existencia de un sistema de control de versiones (como `git`) permite reconstruir perfectamente la historia del proyecto. Finalmente, en el extremo del gradiente de reproducibilidad se encuentran los documentos dinámicos (por ejemplo, Rmarkdown o IPython) que integran perfectamente texto, datos y código ejecutable.
**Figura 2**. Esquema de un flujo de trabajo reproducible. En primer lugar, los datos se recogen según un protocolo bien diseñado, se documentan con metadatos (e.g. usando el estándar EML, 'Ecological Metadata Language'), se someten a un control de calidad (idealmente de manera automática, esto es, mediante funciones de código), y se almacenan en un repositorio de datos en la nube. Después procederíamos al análisis, siempre utilizando 'scripts' para manipular los datos, y creando funciones que pueden almacenarse en un paquete (para facilitar su documentación y posterior reutilización). El análisis propiamente dicho se haría mediante documentos de Rmarkdown o IPython que integran texto, código y resultados (tablas y figuras). Estos documentos pueden convertirse fácilmente en presentaciones, páginas web, o artículos científicos plenamente reproducibles.
**Figura 3**. Los documentos dinámicos que integran texto, código y resultados (e.g. Rmarkdown, IPython) son una herramienta revolucionaria para hacer ciencia reproducible. Por ejemplo, un archivo Rmarkdown que contiene texto y código (a) puede ejecutarse y producir automáticamente documentos integrados (b) en múltiples formatos incluyendo html, pdf, o Word. Los documentos Rmarkdown permiten trazar todo el proceso desde los datos originales a los resultados, y son plenamente reproducibles de manera que si hacemos cualquier cambio en los datos o el código, los resultados se actualizan automáticamente.
**Figura 4**. Almacenar copias de archivos con distintos nombres (a) es un sistema de control de versiones muy ineficiente. El número de archivos crecerá desmesuradamente, y no es fácil comparar los cambios entre distintos archivos o reconstruir la historia del proyecto. Existen sistemas de control de versiones muy eficientes (como `git`) que registran perfectamente quién hizo qué cambio, cuándo y por qué (b). Cuando se sincronizan con plataformas en línea como GitHub (www.github.com), resulta muy fácil trabajar conjuntamente en proyectos incluyendo manejo de datos, análisis y redacción de artículos.
**Figura 5**. Organización de directorios y archivos en un proyecto siguiendo la estructura de un paquete de R. Los datos brutos no deben modificarse y se encuentran separados de los datos depurados, que se generan mediante 'scripts'. Las funciones se definen en ficheros independientes (carpeta `R`), y van acompañadas de documentación (carpeta `man`) y tests (para comprobar que funcionan adecuadamente). Los análisis se realizan mediante documentos Rmarkdown. Existe un script maestro (`makefile`) que ejecuta el análisis (completo o por partes). Esta estructura es flexible y puede modificarse según las preferencias del investigador (e.g. ver https://github.com/ropensci/rrrpkg).
###### FIGURE LEGENDS
**Figure 1**. Reproducibility is not a binary quality but a gradient [@Peng2011]. Scientific articles that contain only the final text, results and figures (e.g. in a single pdf document) are the least reproducible - it is impossible to reconstruct the whole analytic process from data to results. Publication of the data and/or code used for the analysis greatly improve reproducibility. Likewise, usage of a version control system (like `git`) permits navigating through the complete history of the project. Finally, the most reproducible studies are those using dynamic reports (e.g. Rmarkdown or IPython notebooks) that integrate text, code and data in a fully executable environment.
**Figure 2**. Sketch of a reproducible data analysis workflow. First, data are collected following a well-designed plan, documented with metadata (e.g. using EML, the Ecological Metadata Language), quality-controlled (ideally through automated functions), and stored in an online repository. For the data analysis, we would always use scripts for data wrangling and preparation, as well as functions to perform repeated tasks. These functions could be wrapped into a package to facilitate their share and reuse. The actual analysis would be done using literate programming (e.g. Rmarkdown or IPython). These documents integrate text, code and results (tables and figures) and are fully executable, so they can be easily converted into presentations, web pages, or fully reproducible manuscripts.
**Figure 3**. Dynamic documents integrating text, code and results (e.g. Rmarkdown, IPython) are revolutionary tools for reproducible science. For example, an Rmarkdown document (a) contaning text and code can be automatically converted into an integrated document with text, code and results (b) in one of multiple formats including html, pdf, and Word. Rmarkdown documents are fully reproducible: they permit tracing exactly how results are derived from data, and if we change anything in the data or code, results will be updated automatically.
**Figure 4**. Storing file copies with distinct names (a) is a very inefficient system of version control. The number of files will grow fast, and it is hard to compare changes between files, or navigate the history of the project. In contrast, version control systems such as `git` are very efficient to record who did what change, when, and why (b). When used in conjunction with online platforms like GitHub (www.github.com), it is easy to work collaborately in research projects involving data management, analysis, and manuscript writing.
**Figure 5**. Organisation of files and folders for a research project following the structure of an R package. Raw data are separated from derived (clean) data, which are obtained through scripts. Functions are defined as independent files (`R` folder), have documentation (`man` folder) and tests (to check that they work correctly). Analyses are done in Rmarkdown. There is also a `makefile` that executes all or parts of the analysis. This structure is flexible and highly customisable to follow preferences of the researcher (e.g. see https://github.com/ropensci/rrrpkg).
###### FIGURA 1
###### FIGURA 2
###### FIGURA 3
###### FIGURA 4
###### FIGURA 5
###### Mover lista de referencias a la sección de 'Referencias' más arriba.