Format for case studies

[jmbyrne]

Here are some options for formats that case studies can be written in;

Pluto

• Positives
  • Good interface, outputs clean webpage or interactive notebook
• Negatives
  • PDF output is not great
  • Not usable for all applications, since cannot have WIP code or reassign variables

    Jupyter

• Positives
  • Good output and interactivity like Pluto, and can reassign variables
• Negatives
  • A pain to use (at least as I've found so far)
  • Still can't have WIP code

    LaTeX

• Positives
  • Looks mathsy
  • PDF output
  • Images/PDF outputs can be naturally imported
• Negatives
  • No interactivity
  • Slower to write than Word/Google Docs

    Word

• Positives
  • Can have a PDF output
  • Can copy code in from VSCode and keep the colours
• Negatives
  • No interactivity
  • Lacks the precision of LaTeX
  • No live collaboration like Google Docs
  • Doesn't look like LaTeX, might be less appealing

    Google Docs

• Positives
  • Can have PDF output
  • Can copy code in from VSCode and keep the colours
  • Multiple people can work on it at the same time (may not be necessary)
• Negatives
  • No interactivity
  • Lacks the precision of LaTeX
  • Less features than Word
  • Doesn't look like LaTeX, might be less appealing

Whether we choose between them on a case (study) by case (study) basis or pick one or two to use for everything I don't know. We should probably also create quick templates/style guides for those that we will use for consistency

[sje30]

Have you seen the following:

1. https://github.com/JunoLab/Weave.jl
2. https://jupytext.readthedocs.io/en/latest/

Weave allows you to mix Julia code and markdown, and export to various formats (including pdf via latex).

Jupytext is what I've used recently to convert raw .jl files to Jupyter notebooks, which are then convertd to pdf. So, this relies on the notebook technology really.

Both are non-interactive.

[jmbyrne]

These look promising, particularly Weave. They do have the limitation that is inevitable for notebook-style formats where the inherent meaningfulness of code means that I can't use incomplete code in the case study. For example, a long function may be useful to split up into several sections to explain them more in detail, but then the code won't function because you can't split a block of code over multiple blocks in the notebook.

[jmbyrne]

I should have an example of this written by this afternoon for a short case study that I'm writing up in Google Docs at the moment. For this case study at least, Google Docs seems to work well, although we'll probably have to discuss this later with more complicated case studies and with Valentin next week

[jmbyrne]

A case study is up now. I have got outputs in HTML and PDF style, we'll have to decide which of those is best

[jmbyrne]

Contrary to what I said on Friday, I thought I'd give Pluto another go since I realised it might not be as problematic as I once thought. Here is some Julia code in Pluto in three different forms

• The first form is a disabled code block. Functionally, this is excellent since syntax highlighting is retained while the code doesn't run (so I can include incomplete/duplicate code in Pluto without it complaining). However, I feel it might be a little too hard to read
• The second form is a markdown code block. This doesn't keep the formatting and looks obviously different from normal code blocks, but is perfectly readable and also can include incomplete code
• The third form is, of course, the normal code block. This is mainly here for comparison to the other two

If we decide that either of the first two options would be usable in case studies then that fixes my major gripe with using Pluto, and so I would suggest that we go with it for all case studies unless further problems crop up

[jmbyrne]

The latest case study that I've put up is Modelling infectious diseases. It is written in Pluto entirely, with the incomplete code problem solved by using blocks of the form

md"""
```julia
<julia-code>
```
"""

This form leaves code in clearly distinct blocks but keeps syntax formatting. In my opinion this leaves the only major problem with Pluto as the bad PDF output, but since we're using HTML output (which is good), then I think Pluto should be usable as standard.

[sje30]

super. pdf is not important, as long as the HTML looks good (which this does).

[sje30]

Shall we close this now, and stick to Pluto for the rest of the summer?

@jmb280cam @valentin-imbach

[jmbyrne]

I'm happy to

[valentin-imbach]

Yes, that works for me as well

On 3 Aug 2021, at 22:07, jmb280cam @.***> wrote:

 I'm happy to

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications on the go with GitHub Mobile for iOS or Android.