I love this book. It’s not only written in Rmarkdown but also explains the fundamentals of Python in a live book in the web; totally reproducible.
What is extraordinary is that this book has been totally computed with Python as the coding engine, while the text is in Rmarkdown. The plots have been generated by the Python package matplotlib, and seaborn.
Rmarkdown is the extended and super-powered version of Markdown, which uses some text symbols - such as
$, and others to add formatting to the document. Markdown and Rmarkdown documents are fully reproducible and can have version control with Git, since they are full text. This is continuation of literate programming1, initiated by Donald Knuth2
My contribution consists of making this Python book even more reproducible:
- adding instructions to build the Python environment with Anaconda (
- adding a
Makefileto automate the builds outside RStudio;
- making the book available online as a website through GitHub Pages here;
- adding an R script to load the Python environment for each Rmarkdown document;
- Apply some formatting with
The power of Rmarkdown
Rmarkdown opens infinite creation possibilities to data scientists, engineers and analysts for the production of documents, reports, analysis, tutorials, manuals, papers, thesis, presentations, slides, or even websites or blogs. Some of the advantages of writing your documents in Rmarkdown are:
Documents are fully written in text which can be opened at any time with a simple text editor
Documents are totally reproducible and able to be put under version control such as Git, and published to GitHub, GitLab, Bitbucket, or other cloud repositories
Multiple coding languages can be embedded in a single document and executed during builds which makes calculations less error prone, or easier to pinpoint
Plots, figures and images are generated by the code in Rmarkdown which make copy-and-paste a thing of the past
Python and R can mutually interchange values of objects or variables in the same Rmarkdown document
Rmarkdown documents can be built to be HTML books, Git books, PDF books, and other output formats
Build the book
I built this book with
R-3.6.3 in a Debian-10 Linux operating system using Visual Code Studio with the addition of some R friendly
vscode extensions and GNU
Makefile file is included in the repo.
The Anaconda version I used was the July version of 2020 (the name of the download is
Anaconda3-2020.07-Linux-x86_64.sh). The Python version of the environment is
3.7. But I also tested the book with Python
3.8 and the book works fine.
When your Anaconda is ready, is the moment to create the Python environment using
conda. The process takes few minutes - in my machine around 3 minutes). That Python environment will have all the packages necessary to run all the Python scripts in the book. Run this command from the terminal:
Build the gitbook
You don’t really need RStudio to build this book, but you need R installed. I took the challenge of building the book from the terminal window in
vscode, with a little help of
From a terminal, run:
Both do the same thing: building the Rmarkdown book. I left the two options available for the reader to get familiar with
Makefile; how to set environment variables from the shell, or set them from within R.
If the book builds successfully, it should open your browser with the main page of the book. This is all handled by
make and the commands in
Optional after building the book
If you make changes to the Rmarkdown documents, you may want to tidy up or totally clean it from auxiliary folders and files that were generated during the knitting process. The are two rules in the
Tidy up the folder
This deletes the auxiliary files that were created during the book building process.
Clean up the folder
make tidy plus deletes the publication folder, to start over fresh.
This is optional. I added it to document it for the next I have to work with book later. You activate it with:
Of course, you could have typed this such trivial command on the terminal yourself.
This is a minimal example of a book based on R Markdown and bookdown (https://github.com/rstudio/bookdown). Please see the page “Get Started” at https://bookdown.org/yihui/bookdown/ for how to compile this example into HTML. You may generate a copy of the book in
bookdown::pdf_book format by calling
bookdown::render_book('index.Rmd', 'bookdown::pdf_book'). More detailed instructions are available here https://bookdown.org/yihui/bookdown/build-the-book.html.
You can find the preview of this example at https://bookdown.org/yihui/bookdown-demo/.
1 The literate programming paradigm, as conceived by Knuth, represents a move away from writing computer programs in the manner and order imposed by the computer, and instead enables programmers to develop programs in the order demanded by the logic and flow of their thoughts. https://en.wikipedia.org/wiki/Literate_programming. ↩
2 Knuth is also the creator of the
TeX computer typesetting system, the related METAFONT font definition language and rendering system, and the Computer Modern family of
typefaces. https://en.wikipedia.org/wiki/Donald_Knuth. ↩