Guidance For AGU Authors: Jupyter Notebooks

Jupyter Notebooks are increasingly being used for documenting data science workflows and replicating relevant analyses in research. The following recommendations are available to help guide authors through the process of sharing their Jupyter Notebooks when publishing in AGU journals. Please note that any data used by your notebook must be preserved and cited separately from the notebook according to AGU’s Data and Software for Authors guidance.

First, read. Ten simple rules for writing and sharing computational analyses in Jupyter Notebooks and the recommendations from Jupyter Notebooks and reproducible data science will help you with creating computational notebooks that are easier to read, run, and explore.

Second, store and preserve. Upload your notebook in a public repository that gives you a Digital Object Identifier (DOI), so that your notebook is preserved in the scholarly record and can be cited. We recommend using the following solution:

Third, execute. Facilitate the rerunning of your notebook by readers through a zero-install environment in the cloud. We recommend these instructions and the following solution:

  • Binder or Pangeo, upload your notebook and an environment.yml file, run it, and share it via link

No matter which execution environment you choose, make sure you obtain a publicly accessible link to your notebook so that it can be executed by any reader.

Fourth, cite and describe. Establish the connection between your notebook and paper using these two steps.

  • Cite your notebook, using your DOI, in the References section of your paper. Example citation below:

Fenner, M. (2019). Jupyter Notebook FREYA PID Graph Key Performance Indicators (KPIs) (Version 1.1.0). DataCite. https://doi.org/10.14454/3BPW-W381

  • Describe the availability of your notebook by including the DOI of the preserved release used by your paper, the development platform where it is hosted, and the execution link in the Availability Statement of your paper. For AGU, the Availability Statement is located in the Open Research section. Statement template is below:

“The Jupyter Notebook to execute the analysis in the paper can be found at [include link to rerunnable notebook link in the cloud], is hosted at [development platform, e.g., GitHub] and is preserved at [include the link to the preserved notebook DOI, version, and license].”

Fifth, render (optional). Consider rendering your notebook using the Executable Book Project and Jupyter Book. An example project gallery of Jupyter Books is available. The Neuro Libre Project features additional Jupyter Book examples.

Erdmann, Christopher, Stall, Shelley, Gentemann, Chelle, Holdgraf, Chris, Fernandes, Filipe P. A., Gehlen, Karsten Peters-von, Corvellec, Marianne. (2021, May 20). Guidance for AGU Authors - Jupyter Notebooks. Zenodo. http://doi.org/10.5281/zenodo.4774440 DOI