Add solutions to training exercises as foldable code chunks

[RiboRings]

The Exercise chapter has plenty of exercises. Let's add solutions to them as foldable code chunks, closed by default and opened when user clicks on them.

It can be done with:

output:
  html_document:
    code_folding: hide

[antagomir]

When there is time we have received regular requests to add solutions for the exercises.. would be nice to see some community contributions here.. :-)

[RiboRings]

Link and text of pr https://github.com/microbiome/OMA/pull/390

Hi! Before switching to BiocBook we were considering to add foldable solutions to the exercises. Here I added solution chunks to a couple of exercises so if anyone is willing to expand they can use the blueprint used in this PR. For example:

#| label: exercise-name-chunk1
#| eval: FALSE
#| code-fold: true
#| code-summary: "Show solution"

# Write solution here

Ideally, break down solution chunks into steps same way as the exercises are fragmented.

[antagomir]

Giulio - could you check if this is easy to add in the new version of the book?

[antagomir]

If not easy then let's rethink.

[RiboRings]

Hi! In theory, this should be working in the current version of the book. However, the folded code doesn't appear in the chapter. Not sure yet what the problem is.

[RiboRings]

The reason could be that code folding is only supported by executed code chunks: https://quarto.org/docs/output-formats/html-code.html

Maybe we could run the code in the examples, or if that takes too long we could comment out all the lines of the example chunks and "execute" it.

[antagomir]

hmm perhaps we could first add this to some light-weight cases where it is simple; for more heavy examples there could be a link to an external file (in OMA repo but not included in the book)?

[RiboRings]

For some reason, the folded chunks appear locally, but they are not rendered in the online version of the book. Below is a picture of what is looks like when rendered locally:

[RiboRings]

Some possible actions:

• test if chunk appears in the online book when setting EVAL = TRUE (also precede all lines with # so they don't execute
• understand why code folding works only locally, and try to fix it in the online book

[ake123]

@RiboRings solution works fine. We can check it here (https://ake123.github.io/OMA/docs/devel/pages/98_exercises.html#sample-information)

[RiboRings]

Thank you @ake123

Then in principle if someone is willing, they can add solutions to selected exercises in preparation for summer schools and courses as shown in the comment above.

[ake123]

I am willing to add solutions. I can actually do all if needed

[RiboRings]

That would be super useful!

@antagomir mentioned that we might need to consider whether it makes sense to add solutions to all exercises, or if it is only necessary for the more complex exercises, and the easier exercises would just contain a link to the corresponding OMA chapter (also to avoid redundant code).

How should we proceed?

[antagomir]

I could review the exercises and see which ones would benefit from solutions. This will take some time. But next week we run a training events, this can bring some clarity.

[antagomir]

Ok @ake123 if you could do the following for the material in chapter 18.3? https://microbiome.github.io/OMA/docs/devel/pages/98_exercises.html

1. Go through those exercises, and verify that they are clear and work well. Improve the exercise text or tips where necessary.

2. Add citation to the relevant OMA chapters / function names as a tip; also the tips can be folded

3. provide brief (folded) example solutions for those exercises where it seems useful; if the solution is obvious from the material that is already provided in the proper chapters, then see if it is enough to just cite the relevant chapter. We don't want to duplicate all material from the book to the exercises as this doesn't make sense.

4. Where possible, avoid referring to specific data sets in the exercise text; the solution needs to operate on concrete data however.

Let's see how this works for chapter 18.3, then we can see how to do with the other chapters.

[ake123]

Solutions are ready!

[antagomir]

@jkc9886 could you check if the exercise chapter contains tasks for which you could propose solutions (as a PR)?

[antagomir]

Foldable chunks seems to work now. It seems we can close this.