1Articles with code vs articles from code¶

One of the main advantages of articles written in MyST Markdown is the fact that you can bundle several types of outputs (such as figures, tables, equations, etc.) from your Jupyter Notebooks in a single document. This is made possible by the use of directives, which are special commands that instruct MyST Markdown to include the content of a notebook, a file, or a chunk of text in your document or cite references. You can use DOIs, Karakuzu et al. (2022) or a local bibliography file (paper.bib) for citations Boudreau et al. (2023).

Let’s see how directives work with a simple example by rendering a video from an external source:

Yet, the main purpose of this article is to not to showcase all the authoring tools available in MyST Markdown, but rather to provide a simple template to get you started with your own article to publish on NeuroLibre.

Typically, when publishing an article following the traditional route, you would write your article in a word processor where you need to deal with the generation of figures, tables etc. elsewhere, and then bring them together in the final document manually. This eventually leads to a cluttered set of files, code, dependencies, and even data that are hard to manage in the long run. If you’ve been publishing articles for a while, you probably know what we are talking about:

Where is the endnote reference folder I used for this article?

What is the name of the script I used to generate the second figure? This script has the title fig_2_working.py and is in the karakuzu_et_al_2016_mrm folder, but it does not seem to be the one that generated the figure...

I cannot create the same runtime environment that I used for this analysis in my current project because python 3.8 is not available in the current distribution of Anaconda... It is so tricky to get this running on my new computer...

MyST Markdown offers a powerful solution to this by allowing you to create an article ✨from code✨, linking all the pieces of your executable and narrative content together in the body of this one document: your canvas.

For example, the following figure is the output of the content/fig_1.ipynb notebook:

Here is another figure generated from another notebook:

Both interactive, cool right! All your assets are centralized in this one document, which ideally lives in a GitHub repository. You may forget what you did, but your commit history will be there to remind you.

2NeuroLibre and MyST Markdown¶

NeuroLibre is a reproducible preprint publisher that makes it a seamless experience to publish preprints written in MyST Markdown, and commits to the long term preservation of the content, runtime, data, and the functionality of the code.

Data¶

Unless your preprint does not include any output that requires computational resources, you typically need to provide a set of inputs to supplement the generation of the assets in your article. The type and size of the data can vary greatly from one article to another, from a 50KB excel spreadsheet to a 2GB neuroimaging dataset of brain images.

The only requirement is that the data must be publicly available to be accessed by NeuroLibre. To specify your data dependencies, you can provide a binder/data_requirement.json file in the root of your repository, with the following structure:

{
  { "src": "https://drive.google.com/uc?id=1hOohYO0ifFD-sKN_KPPXOgdQpNQaThiJ",
  "dst": "../data",
  "projectName": "neurolibre-demo-dataset"
  }
}

2.1How can I get NeuroLibre to cache my data dependencies?¶

You can use this issue template to request the caching of your data dependencies.

Code¶

NeuroLibre follows the reproducible runtime environment specification (REES) to define a runtime environment for your preprint. Any programming language supported by Project Jupyter (e.g. python, R, julia, etc.) can be used to create your executable content, where you place necessary BinderHub configuration files in the binder folder.

2.2How much computational resources are available and for how long my notebooks can run to generate the outputs?¶

For each preprint, we guarantee a minimum of 1 CPU core and 4 GB of RAM (8GB maximum), and a maximum of 1 hours of runtime to execute all the notebooks in the content folder.

Do you really want someone to run your code for 1 hour? Probably not.

Even though long-running code cells may be of interest to interactive tutorials, a reader who is interested in reproducing your Figure would be less likely to wait for more than a few minutes for the outputs to be generated. This is why we encourage you to create notebooks that can be run in the “attention span” of a reader.

Preview your preprint¶

2.3Locally¶

It is always a good practice to be able to build your MyST article locally before publishing it to NeuroLibre. If you install MyST as described here, in a virtual environment that has all your code dependencies installed, you can build your myst article:

cd path/to/your/repo
myst build --execute --html

2.4Roboneuro preview service¶

If you have a data dependency and have NeuroLibre cached it for you, you can start using the Roboneuro preview service to build your preprint: https://robo.neurolibre.org

2.5Technical screening¶

Once you submit your preprint to NeuroLibre, our team will perform a technical screening to ensure that your preprint can be built successfully. This is to make sure that your preprint is in line with our guidelines and to avoid any issues that may arise during the build process.

You can visit our technical screening repository neurolibre/neurolibre-reviews to see examples of this process.

After your preprint is published¶

We archive all the reproducibility assets of your preprint on Zenodo and link those objects to your reproducible preprint that is assigned a DOI and indexed by Crossref (also by Google Scholar, Researchgate, and other platforms that use Crossref metadata).

Your preprint can be found, cited, and more importantly, reproduced by any interested reader, and that includes you (probably a few years after you published your preprint)!

Is the idea of wanting to publish a dashboard with your preprint too crazy?¶

Absolutely not! We encourage you to publish your dashboard alongside your preprint to showcase your results in the best way possible.

These dashboards Fig. 6 and Fig. 7 are embedded in their respective NeuroLibre preprints! If you are interested in publishing your own dashboard with NeuroLibre, please open an issue using this template.

If you have any questions or need further assistance, please reach out to us at [email protected].