Merge pull request #91 from SPAAM-community/remove-eval

Remove leftover unnecssary eval:falses, update guidelines, rename som…

Author: jfy133

README.md

@@ -55,7 +55,6 @@ If adding a new section chapter:
 7. Render the book the extensions' `Quarto: Render Book` command, or run the following
 
    ```bash
-   #| eval: false
    quarto preview intro-to-ancient-metagenomics-book --render all --no-browser --no-watch-inputs
    ```
 

ancient-metagenomic-pipelines.qmd

@@ -733,7 +733,6 @@ cd /<path/<to>/ancient-metagenomic-pipelines/aMeta/
 Finally, we are ready to run aMeta, where it will automatically pick up our config and samplesheet file we placed in `config/`!
 
 ```bash 
-#| eval: false
 ## change conda-frontend to mamba if we set this up earlier!
 snakemake --snakefile workflow/Snakefile --use-conda -j 10 --conda-frontend conda
 ```
@@ -879,7 +878,7 @@ Firstly we need a method of validating that contigs are from an ancient genome (
 
 Secondly, to correct for falsely included damage bases in contigs in some contexts. As previously stated a previous chapter by Alex Hübner:
 
-> In our group we realised that the gene sequences that were annotated on the contigs of MEGAHIT tended to have a higher number of nonsense mutations compared to the known variants of the genes. After manual inspection, we observed that many of these mutations appeared because MEGAHIT chose the damage-derived T allele over the C allele or the damage-derived A allele over a G allele [see @Klapper2023-mv, Figure S1].
+> In our group we realised that the gene sequences that were annotated on the contigs of MEGAHIT tended to have a higher number of nonsense mutations compared to the known variants of the genes. After manual inspection, we observed that many of these mutations appeared because MEGAHIT chose the damage-derived T allele over the C allele or the damage-derived A allele over a G allele [see @Klapper2023-nv, Figure S1].
 
 > To overcome this issue, my colleagues Maxime Borry, James Fellows Yates and I developed a strategy to replace these damage-derived alleles in the contig sequences. This approach consists of aligning the short-read data against the contigs, performing genotyping along them, and finally replacing all alleles for which we have strong support for an allele that is different from the one selected by MEGAHIT.
 

chapter-checklist.qmd

@@ -77,7 +77,7 @@ This will help make the editing process more manageable by only considering one
 - Inline code defined with single `backticks` should be used for a single word or object (e.g., `variable`, `tool`, `.suffix`)
 - All commands or longer code related text must go in a dedicated markdown triple backticks with the language specified (e.g., ````bash`)
 - Do not prefix commands with a `$` or `>` to indicate a command prompt
-- Most code blocks with output should be set to `eval=FALSE` in the code block options, unless the code/plot is expected to executed on the fly
+- Code blocks that automatically execute in Quarto (e.g. R), output should be set to `eval=FALSE` in the code block options, unless the code/plot is expected to executed on the fly
 - Output from large/long-running output should be placed in a collapsible call-out block ([writing guidelines](chapter-writing-guidelines.qmd) for examples)
 - Code for self-guided chapter set-up should be wrapped in a collapsible note call-out block with a 'Self guided: \<title\>' format
 - Example code that should not be run by the user should wrapped in a 'warning' call-out block with the title 'Example command - do not run!'

chapter-template.qmd

@@ -34,19 +34,47 @@ echo "Hello world!"
 
 The code block above has `bash` as the code identifier. Inline text should only be used for single commands, file extensions, or paths, i.e., not whole commands.
 
-Large or long running code should be set to `eval` false, and pre-made output placed in a collapsible block.
+For code blocks that execute - by default only R - should be set to `eval=FALSE`.
+Pre-made output should be copy pasted and placed in a collapsible block.
+For example the following.
 
-```{.bash, eval = false}
-echo "SPAAM rules!"
+```{.r eval=FALSE}
+print('SPAAM Rules!')
 ```
+
 ::: {.callout-note collapse="true"}
 ## Expand see output
 
-```{.default, eval = false}
-SPAAM rules!
+```{.r eval=FALSE}
+[1] "SPAAM Rules!"
 ```
 :::
 
+Can be written as.
+
+`````verbatim
+```{.r eval=FALSE}
+print('SPAAM Rules!')
+```
+`````
+
+::: {.callout-note collapse="true"}
+## Expand see output
+`````verbatim
+```{.r eval=FALSE}
+[1] "SPAAM Rules!"
+```
+`````
+:::
+
+Other code blocks will not execute by default, and can be simply set without setting no execution.
+
+`````verbatim
+```bash
+echo "SPAAM Rules!"
+```
+`````
+
 ## Second section
 
 Here is an example of a figure. It must have a caption, and a label for referencing in text.

chapter-writing-guidelines.qmd

@@ -104,14 +104,13 @@ See the [Chapter Content](#chapter-content) for the reserved formatting. Note: I
 Single backticks for inline code should only be used for single words such as tool names, e.g. `samtools`, file extensions such as `.txt`, or single paths `<path>/<to>/<here>`.
 
 Any form of commands or code should be formatted as code in a syntax-named _triple_ backtick block.
-Execution should be turned off by default (with `eval: false` in a code block header block), unless has a very low computational overhead and can be rendered on the fly.
+Execution should be turned off by default for those languages that may auto-execute (i..e, R, with `eval=FALSE` in a code block header block), unless has a very low computational overhead and can be rendered on the fly.
 Language should be specified.
 
 For example, this is a bash code block that has a whole command.
 
-```{verbatim}
+```verbatim
     ```bash
-    #| eval: false
     echo "SPAAM rules!"
     ```
 ```
@@ -123,7 +122,7 @@ echo "SPAAM rules!"
 ```
 
 If you wish to display _large_ output from a code block that _does_ get executed, you should turn off the command execution printing in the code block itself, and use a collapsible callout block with a 'Expand to see output' title immediately after the code block itself that contains.
-The content of the output should also be in a triple backtick block, with the the `default` syntax specified.
+The content of the output should also be in a triple backtick block, with the the `verbatim` syntax specified.
 
 ```bash
 echo "SPAAM rules!"
@@ -138,18 +137,22 @@ SPAAM rules!
 
 This was generated with
 
-```markdown
-    ```bash
-    echo "SPAAM rules!"
-    ```
-    ::: {.callout-note collapse="true"}
-    ## Expand see output
+Another example, with setting `eval=FALSE` for R.
 
-    ```{.default, eval = false}
-    SPAAM rules!
-    ```
-    :::
+`````verbatim
+```{.r eval=FALSE}
+print('SPAAM Rules!')
 ```
+`````
+
+::: {.callout-note collapse="true"}
+## Expand see output
+`````verbatim
+```{.r eval=FALSE}
+[1] "SPAAM Rules!"
+```
+`````
+:::
 
 Additional guidance is as follows:
 

denovo-assembly.qmd

@@ -1,5 +1,5 @@
 ---
-title: Introduction to _de novo_ Genome Assembly
+title: _De novo_ Genome Assembly
 author: Alexander Hübner
 bibliography: assets/references/denovo-assembly.bib
 ---

python-pandas.qmd

@@ -235,15 +235,15 @@ For a more in detail pandas getting started tutorial click here ([https://pandas
 Pandas can read in _csv_ (comma separated values) files, which are tables in text format.
 It is called _c_sv because each value is separated from the others through a comma.
 
-```{text}
+```verbatim
 A,B
 5,6
 8,4
 ```
 
 Another common tabular separator are _tsv_, where each value is separated by a _tab_ `\t`.
 
-```{text}
+```verbatim
 A\tB
 5\t6
 8\t4