Introduction to JFM Notebooks

JFM Notebooks are interactive objects that execute code and visualise data. We have partnered with CoCalc (https://cocalc.com) for cloud-based long-term hosting of Jupyter Notebooks associated with JFM papers. JFM Notebooks allow authors to provide more than a static two-dimensional snapshot of the results of research presented in article figures. Authors can link to a JFM Notebook which hosts the underlying data and code and allows readers to interrogate and probe the data to explore alternative ideas and gain further insights. JFM Notebooks increase the transparency and accessibility of research published in JFM and more fully convey the essence, complexity and beauty of fluid flow phenomena.

For a detailed introduction, please read the Editorial ‘Introducing JFM Notebooks’ which can be read here. For detailed instructions on interacting, preparing, submitting and reviewing JFM Notebooks, please see below.

As a new initiative, the procedures and workflows for JFM Notebooks will evolve over time; the support, collaboration and feedback of the fluids community is greatly appreciated as we learn how best to develop this new functionality. Please send any questions or comments to the Editorial Office (JFMEditorial@cambridge.org).

How to interact with JFM Notebooks

JFM Notebooks are hosted on CoCalc (https://cocalc.com) and, when included with an article, will be linked to from the caption of article figures. An example of a notebook (from the Editorial ‘Introducing JFM Notebooks’) is here. This link takes a reader to the Jupyter Notebook file (the directory which contains the Jupyter notebook file and associated files e.g. data can also be accessed here).

To view and interact with a JFM Notebook a reader must launch it as their own project: click ‘Edit your own copy’, ‘Create a New Project’, then open the Jupyter Notebook file (*.ipynb) to launch the online JFM notebook. Step by step instructions with screenshots are available here.

Further details and documentation on using CoCalc can be found here.

How to prepare your JFM Notebooks

A JFM Notebook should contain the data and code used to generate a figure in a JFM article and it must be linked to from the figure caption. The output of the JFM Notebook should, therefore, be identical to the image used as the figure. See the Editorial ‘Introducing JFM Notebooks’ for examples.

You can prepare Jupyter Notebooks in your own environment or in CoCalc’s online notebooks. For submission, they must be uploaded to CoCalc. It is possible to use CoCalc for free with trial projects, but projects associated with a licence have higher performance and users do not need a CoCalc account to use them. JFM Notebooks will be associated with the Cambridge University Press (CUP) licence after submission (see submission instructions below).

Please take note of the following requirements when preparing your JFM Notebook:

• JFM Notebooks must be prepared using a Python library already installed by CoCalc, the full list is here.
• You should create one CoCalc project for your paper and create a top-level directory folder called ‘JFM-Notebooks’. Include a folder underneath this for each figure that has a JFM Notebook. 
  • The figure folders should be named according to their running order (figure 1, figure 2 etc.).  
  • The figure folders should contain the Jupyter Notebook files (*.ipynb) and any other output (e.g. HTML renderings) associated with that figure.
  • Data can be included in the figure folders or in another folder if it is shared across figures. Please ensure the figure and data folders are all nested underneath the ‘JFM-Notebooks’ directory folder in the file hierarchy to ensure all necessary files are available when share links are created. 
  • For visual consistency, the JFM Notebook Jupyter file (*.ipynb) should begin with the JFM Notebook logo from the included file "JFM-notebooks-logo.jpg". It should be placed at the top of the notebook, as shown in this example.
• Share links for your JFM Notebooks are created by ‘publishing’ the top level JFM-Notebooks directory folder (choose “Published (unlisted) – only people with the link can view this”). You can find the share links for each file in the publish controls. See here for instructions.
• Include links to the Jupyter Notebook file (*.ipynb) or any HTML renderings in the figure caption in your paper. 

The CoCalc website has detailed documentation on the CoCalc platform (https://doc.cocalc.com/), getting started (https://doc.cocalc.com/getting-started.html) and Jupyter Notebooks (https://doc.cocalc.com/jupyter.html). 

How to submit your article with JFM Notebooks

If you are interested in submitting a JFM article with associated Jupyter Notebooks please prepare them as outlined above and add links to the JFM Notebooks in the figure caption of the figure that it relates to (see ‘How to prepare your JFM Notebooks’ above). Please note you should choose the unlisted share option; be aware that this will give access to anyone with the link, this is to allow your notebook to be accessed by Editors and Reviewers as part of the peer review process. The notebooks will not be publicly listed unless you choose this.

Your JFM Notebooks should be associated with the Cambridge license after submission to ensure good performance and allow referees to access the notebooks seamlessly. After submission, please follow the steps below: 

1. Re-name your CoCalc project with the manuscript ID of your Submission (this will be in the format JFM-##-####) 
2. Make CUP a Collaborator. This can be done in the ‘users’ section by searching for ‘Cambridge University Press’ in the ‘Add new collaborators’ box, instructions are here. 
3. Email JFMEditorial@cambridge.org to confirm that CUP are a collaborator and the project is now named with the manuscript ID. The Editorial Office will then apply the CUP license to your shared project.

If you would like to have the CUP license associated with your notebooks before submission, please contact the Editorial Office: JFMEditorial@cambridge.org.

Production and Publication of JFM Notebooks

After the acceptance of your article, you will be asked to provide final files. When your article contains JFM Notebooks you will receive additional final files instructions relating specifically to JFM Notebooks as outlined below. After all final files have been received the article will pass through to production.

All articles with JFM Notebooks will publish the notebook files as supplementary information on the JFM website alongside the article; this is to ensure the maintenance of the scientific record. You should include in your final files a download of the ‘JFM-Notebooks’ top level directory in a Zip file.

During production, a new Cambridge controlled CoCalc project will be created, which you will not be a collaborator on. Your ‘JFM-Notebooks’ directory folder will be copied into this and updates made to the descriptive metadata linking it to the published version of record (you will be asked to provide key words and the manuscript authors).

Persistent cambridge.org redirects will be created for each share link in the manuscript. The original share links in your manuscript will be replaced with the persistent links as part of the typesetting process. You will be asked to provide a list of all share links and the figure they relate to.

The JFM Notebooks will be made publicly available and will be discoverable by search engines as well as those with the links from the published version of record.

Information for reviewers

JFM Notebooks are an important part of an article, the information they convey is necessary for a full understanding of the scientific content and, as such, JFM Notebooks should be peer reviewed alongside the article.

If you are asked to review an article that has JFM Notebooks, links to these will be in the manuscript you receive for review. You should check the notebooks and ensure that they are scientifically sound. Please also check that they function and are in alignment with the figure they represent.

Please comment on the notebooks as part of your reviewer report so the Editor knows that they have been assessed.

If you have any questions about the notebook or require any support, please contact the Editor handling the manuscript.