mlr3book style

[RaphaelS1]

Listing here style choices that should be made consistent throughout the book. We can check this at the very end before publication but ideally we should make this changes as we go along with edits:

R

• mlr3 styleguide will be explained in the preamble, stick to it everywhere, e.g. = not <-
• For all examples use: mtcars (regression) or penguins (classification). In the appendix we will show the str and head of these so you don't need to repeat this in the text. Post here if you need to use a different one and we'll add to the list.
• In all code chunks use named arguments for all optional arguments (i.e., always include parameter names), e.g. as_task_regr(iris, "sepal_length", id = "flowers")
• In the main body of text use sugar functions.
• Avoid use of comments in code chunks, try to prioritise explaining things in text https://github.com/mlr-org/mlr3book/issues/431
• Do not overload functions in variable names, for example when constructing a learner never call it lrn !
• Ensure all code chunks are explained - https://github.com/mlr-org/mlr3book/issues/428

English

• "R6 Classes" -> "R6" (unless need to explicit discuss different paradigms)
• Do not use contractions, e.g. 'don't' -> 'do not'
• Check the glossary in the appendix to avoid duplicating terms of changing use of terms, add new entries to glossary as you go along

Quarto

• Format code as below. Links to internal API fine but remember these won't be rendered in print:
  • package
  • package::function()
  • function()
  • $field
  • $method()
• Avoid external hyperlinks unless strictly required. When required use r link() function.
• Reference figures, tables, and other environments (Fig X, Table X). In general don't assume placement unless it's a code chunk
• Mark optional and complex sections by adding {{< include _optional.qmd >}} after the section title (make sure to leave an empty line between them)
• Numbers: (1, 1, $1$): No formatting unless it's for code or mathematical equation
• Use the define function when you want to define a new term. This will print the term, add an entry to the index and highlight the term in the margin, e.g. r define("benchmark")
• Use the index function when you want to print a term and add an index entry for a term, e.g. r index("benchmark")
• Use the link function to create accessible external links
• Use #| fig-alt: in front matter of R code to add alternative figure text. This is NOT the same as the caption but should describe what is shown in a figure for people with screen readers who cannot see the image.
• Use %%| alt-text: in front matter or mermaids diagrams to add alternative figure text.
• ALL tables, figures, etc. must have captions and a reference key. The key must match the float type, e.g. for tables tbl-X or for figures fig-X
• When using the ref function, add the pkg name and double colon for any function outside of the mlr3verse or to reduce ambiguity, for example in Chapter 4 we write paradox::to_tune as without this a reader assumes the function comes from mlr3tuning.
• Never use [some topic](#topic) for sections, always topic (@sec-...)
• When referencing learners, e.g. regression featureless, use lrn("regr.featureless")
• When referencing measures, e.g. RMSE, use msr("regr.rmse")
• Callout boxes:
  • Warning :::{.callout-warning} ::: When to use: Important exceptions that readers should be aware of, e.g. a mistake that could happen if a naive approach is used or the software is used wrongly.
  • Tip :::{.callout-tip} ::: When to use: Optional useful points about code or other content, more advanced notes.
  • Note :::{.callout-note} ::: When to use: NEVER directly use this callout block. Instead use ​​{{< include _optional.qmd >}} to mark optional (sub)sections which can be skipped on first reading, e.g. complex stuff or tangential stuff
  • Important :::{.callout-important} ::: When to use: NEVER
  • Caution :::{.callout-caution} ::: When to use: NEVER

[sebffischer]

Have we had a decision on how we format numbers, i.e. 1 vs 1 vs $1$?

[RaphaelS1]

No formatting unless it's for code or mathematical equation

[sebffischer]

Ok, I added it to the list above.

[sebffischer]

Do we want a point at the end of figure / table descriptions?

[jemus42]

Regarding internal references, is everyone aware of how quarto cross references work, especially in relation to hyperlinks? See https://quarto.org/docs/books/book-crossrefs.html#hyperlinks

The gist is:

• Chapters and sections need a sec prefix, e.g. # Pipelines {#sec-pipelines} to make them referencable with @sec-pipelines
• Hyperlinks, like [pipelines](pipelines.qmd) or [some topic](#topic), won't work for the printed version, so the @sec-xyz version should probably be preferred?

I bring this up because I cleaned up some hyperlinks in Chapter 3, and because I wanted to refer to the overview tables in the appendix, which failed I think because #appendix-overview-tables lacks the sec prefix.

Then again, this might be "fix/unify that in one big editing pass at the end" kind of thing.

[RaphaelS1]

Thanks @jemus42 good point will add referencing above