Wrap up

Specific Tips

This section goes through some of the specific questions that members of the Imago team had before putting together this workshop.

Dealing with Jupyter notebooks

This was covered a fair bit in the merge conflicts section. The best way is to:

  • clear outputs
  • don’t work on the same cells as your colleagues
  • don’t use Jupyter notebooks for production code - use them for their intended purpose (training, demos)
  • fixing them manually and overwriting the old file is often easier than trying to diff the JSON

There are tools for helping with Jupyter notebooks - e.g. one could use GitHub Actions to run nbconvert to clear outputs, nbdime can make merging easier. Prevention is better than cure however!

Creating a chapter in Quarto

The repository used to create this webpage is an example of this.

The key points are:

  • Create directories for the different chapters
  • Upload the content in those chapters. e.g. 
my-quarto-book/
├── quarto.yml
├── index.qmd
├── chapter1/
│   └── chapter1_content1.qmd
│   └── chapter1_content2.qmd
│   └── chapter1_index.qmd
├── chapter2/
│   └── chapter2_content.qmd
│   └── chapter2_index.qmd
├── chapter3/
│   └── chapter3_content.qmd
│   └── chapter2_index.qmd
│   └──assets/
│      └──picture_1.png

Here we have assets (for e.g. images) inside the chapters rather than one big assets folder at the top level.

  • Update quarto.yml under the book section to include your chapters.
    • Then, if each chapter has several files (as in the case above - we have content1 and content2), we can nest them by creating new index.qmd for each chapter

chapters:
    - index.qmd

    - part: chapter1/chapter1_index.qmd
      chapters:
        - chapter1/chapter1_content1.qmd 
        - chapter1/chapter1_content2.qmd

    - part: chapter2/chapter2_index.qmd
        chapters:
        - chapter2/chapter2_content.qmd

    - part: chapter3/chapter3_index.qmd 
        chapters:
        - chapter3/chapter3_content.qmd
  • Use relative links to link chapters together
    • e.g. from chapter3_content.qmd, you can link to chapter2_content.qmd like (link text)[../chapter2/chapter2_content.qmd].

Have a look in the workshop repo if you want an example of this in action! It has an example of a GH Actions workflow (in .github/workflows/build_quarto.yml) to automatically publish and update the site whenever a commit or PR is made into main - coming to a future workshop near you…

“How to cite effectively?”

Adding citations within Quarto Markdown

You can create a shared bibliography in BibTeX format.

@article{simpson2020,
  title={Very Cool Important Research},
  author={Simpson, Homer AND Shabadoo, Joey Jo-Jo Junior},
  journal={Nature},
  year={2020}
}

Add it to your _quarto.yml:

book:
  title: "Book of Imagery"
  chapters:
    - index.qmd
    - chapter1.qmd
    - chapter2.qmd
  
bibliography: references.bib

and then in your .qmd files you can add the bibliography in and cite papers like:

---
title: Embed2Social
bibliography: references.bib
---

Recent very cool work [@simpson2020] shows that...

You can change the citation style via adding csl to the title section, e.g.

title: some work
bibliography: references.bib
csl: nature.csl

See here for more info.

Citing GitHub repositories

There are various ways. You can cite the GitHub repository itself if you don’t have a data description paper. The best bet is to use something similar to Zenodo. The main consideration is that you need your repository to be public - but this should be the case anyway if you’re citing it…

You can also add a neat little badge to your README.md to link to the Zenodo page!

For stuff that’s more like tooling, rather than novel data analysis/processing, we could consider a submission to the Journal of Open Source Software. This differs from a normal journal in that papers are usually ~2 pages long, and focus more on the software than the application. Writing them is intended to be much simpler than a normal paper - the hard work is in developing the software itself!

Some example Issues and PRs:

Final talking points

  • Is it worth adding restrictions on committing to main directly? GitHub can let us do this.
  • Similarly, we could place restrictions on who is able to merge PRs.