MH Tutorial Preparation Guide

Accepted formats

With code execution

Format	File extension	Notes
Quarto	.qmd
Jupyter Notebook Format	.ipynb	Limited to a single programming language.
R Markdown	.rmd	If possible, should be ported to Quarto.

Without code execution

For example, web tools.

Format	File extension	Notes
Quarto	.qmd	Preferable format as it supports citations and cross references.
(Pandoc) Markdown	.md
Microsoft Word	.docx	Not fully supported.

Headings

There are some suggested headings. See template.qmd and template.ipynb for the suggested headings.

Reproducibility

image source

All submitted tutorials will be converted to both .html and .ipynb by magdalena using Quarto.

The .html version is used as the landing page on Methods Hub.

The .ipynb version is available for download from Methods Hub.

Use the template

If you use the quarto template above, you can get both HTML (for preview) and ipynb by running:

quarto render template.qmd

Use the Jupyter notebook template

Jupyter notebooks are rendered into HTML with quarto using the Jupyter kernel. Comparing to native quarto documents, the following features are not supported.

• BibTex citation and bibliography (you have to do citation manually, this method does not work for HTML rendering)
• Cross referencing

Please also note how to handle the YAML Front Matter for notebook. An example is provided in template.ipynb.

It can be rendered with quarto like so:

quarto render notebook.ipynb --execute

Conversion

Content converstion magdalena uses quarto to do the conversion. You can try the same conversion yourself.

qmd to ipynb

quarto convert input.qmd --output output.ipynb

ipynb to qmd

quarto convert input.ipynb --output output.qmd

See conv.sh on how to convert an existing ipynb-based tutorial to quarto and back. See also the note about code execution below.

Binder compatibility

quarto can make your tutorial Binder compatible. But you should have _quarto.yml in the same directory, i.e. it is a quarto project.

You can initialize a project by:

## replace `projectname` with something else
quarto create projectname
cd projectname

Suppose you have put your tutorial and its associated files in that directory.

quarto use binder

It will generate several files, e.g.

• runtime.txt (example, it configures the run time environment, e.g. r-4.3.3-2024-02-29)
• apt.txt (example, it configures the system requirements)
• postbuild (example, it configures the additional tools such as quarto)

You may still need to produce the configuration files. For Python, you can use requirements.txt or environment.yml (conda). For R, you need to provide a file called install.R with install.packages() calls (example). In most of the cases, you do not need to pin the version (e.g. with tools such as renv) because 3PM is used. It will install the latest version of R packages according to the snapshot date recorded in runtime.txt.

You can check whether your tutorial is binder compatible by pushing your tutorial to GitHub (other options are also available) and launch it with this form.

This is an example.

Caution: Code execution by knitr and jupyter

There is one subtle, but important, difference between the code execution between knitr (the default renderer for R code in quarto) and jupyter. For example, this R code block (see the provided file code_exec.qmd)

```{r}
mean(mtcars$mpg)
plot(mtcars$mpg, mtcars$wt)
```

When rendering this into notebook by quarto using

quarto render code_exec.qmd --to=ipynb

All code blocks will be rendered but also will get modified with the plotting line removed. It's not ideal. So, there two ways to fix this:

Convert it is by using quarto convert instead to generate an empty ipynb.

quarto convert code_exec.qmd -o code_exec.ipynb

Or, to split the code block into one line per block. And for the plot code, you must add the execution option. Only in this case, quarto render will not eat the visualization code.

```{r}
mean(mtcars$mpg)
```

```{r}
#| echo: true
plot(mtcars$mpg, mtcars$wt)
```