mlr3book
mlr3book copied to clipboard
Online version of Bischl, B., Sonabend, R., Kotthoff, L., & Lang, M. (Eds.). (2024). "Applied Machine Learning Using mlr3 in R". CRC Press.
mlr3book
Package to build the mlr3 book using quarto.
Rendered Versions
Building the book
-
Install all necessary dependencies for the book
remotes::install_github("mlr-org/mlr3book", dependencies = TRUE)
-
Install quarto
-
To build the book, run one of the following commands:
# HTML quarto render book/ --to html # PDF quarto render book/ --to pdf
Serve the book
Alternatively, you "serve" the book via a local server:
quarto preview book/
The command above starts a service which automatically (re-)compiles the book sources in the background whenever a file is modified.
Makefile approach
Alternatively, you can use the provided Makefile
(c.f. see make help
).
This way, you can
- install dependencies
- build the HTML book ->
make html
- build the PDF book ->
make pdf
File system structure
The root directory is a regular R package. The book itself is in the subdirectory "book".
Style Guide
Lists
For lists please use *
and not -
.
Chunk Names
Chunks are named automatically as [chapter-name]-#
by calling name_chunks_mlr3book()
:
mlr3book::name_chunks_mlr3book()
or alternatively executing make names
from the terminal.
Figures
You have to options to include a figure:
- Vector graphic
- In the
qmd
:knitr::include_graphics("images/some_figure.svg")
- Add
book/images/some_figure.svg
andbook/images/some_figure.pdf
to the repository.
- Pixel graphic
- In the
qmd
:knitr::include_graphics("images/some_figure.png")
- Add only
book/images/some_figure.png
to the repository.
- Do not use markdown syntax
[](<figure>)
to include figures. - Do not include
pdf
in theqmd
:knitr::include_graphics("images/some_figure.pdf")
.
Adding a new figure
To add a new figure into the repository consider the following rules:
- Add the file in the
book/images
folder without any subdirectory. - Store the original figure as a
svg
file if possible, i.e. if it is a vector graphic. This allows us to re-use or modify images in the future. -
png
files should have reasonable resolution, i.e. the width of a pixel graphic should be between400px
and2000px
. If a higher resolution is needed to obtain a readable plot you are probably doing something wrong, e.g. use a pixel graphic where you should use a vector graphic. - Please look at the file size.
- If your
pdf
orsvg
file is larger than1MB
it probably contains unnecessary hidden content or unvectorized parts. - If your
png
file is larger than1MB
the resolution is probably too big.
- If your
Further aspects
- How do I convert
svg
topdf
?- Use Inkscape or any other tool which does not convert to raster images.
- How do I convert
pdf
tosvg
?- Use Inkscape which allows you to also remove unwanted parts of the
pdf
.
- Use Inkscape which allows you to also remove unwanted parts of the
- Do not use screenshots!
-
Google Slides allows
svg
export. -
PDF can be converted to
svg
and you can even cut parts. -
HTML can be converted to
svg
.
-
Google Slides allows
- The difference between vector (
svg
) and pixel (png
) graphics should be known.- Attention:
svg
andpdf
also support to include pixel graphics. There is no guarantee that asvg
orpdf
is a pure vector graphic. If you paste a pixel graphic (e.g. a screenshot) into Inkscape and save it assvg
it does not magically become a vector graphic.
- Attention:
Spacing
- Always start a new sentence on a new line, this keeps the diff readable.
- Put an empty line before and after code blocks.