My way through R and Markdown
Surgeons, from Latin “chirurgia” which means craftworker are not friends of numbers and mathematic. I am a hand surgeon and a geek and I love R. It began when I took part in the Coursera Data Science Specialisation which teaches R. When I registered for the course I had some experience with DBase, Basic and some knowledge with Neural Networks, which is strange enough for a surgeon. At the beginning it was difficult to understand the concepts of R, but diving deeper into data-science and R teaches me many things and changed the way I organize myself and my work.
R Markdown
At the early beginning of my journey with R, I wrote simple scripts to solve the assignments of the course. Then I got into contact with R Markdown which has more advantages over simple R. With a R Markdown file you can:
- execute code
- build high-quality reports for an audience
- do reproducible research
- help your future self
R Markdown combines metadata, text and code. Executing the code is obvious. The text within the R Markdown document is the important part. It is written in the Markdown syntax. This syntax covers a bunch of formatting:
- inline as italic, bold, links…
- block-level elements as sections headers, lists, block quotes…
- math expressions
We can achieve all this with simple ASCII-signs, e.g. bold text by a surrounding text with two asterisks, ** bold ** or sections headers with several pound signs #. Because all this are ASCII-signs within the document, any text editor can write and read Markdown. It does not depend on any proprietary format.
From this “simple“ texts high quality reports can be generated e.g. in HTML, PDF, .docx, ePub, LaTex, etc. The output contains all calculations and plots generated by the embedded R language.
Reproducible research
The use of simple text for programing and annotation, all steps of the calculation are reproducible, because there are no hidden formatting or calculations. Everything is simple text, which can be read forever. A theatrical short video about the advantages of reproducible research is this: Video.
R Markdown rose my interest in reproducible research, which is an interesting field of science which can I cannot cover here.
Help your future self
R Markdown is time saving and sometimes saved my butt. I work on quarterly or yearly projects. If I plan them in a R Markdown document with a bit of documentation within the text, I can understand what I have done and thought one year before. How complicated is it to understand a complicated excel sheet two years later? A R Markdown document is a sequence of commands, which can be analyzed line by line getting the sense even after years.
Markdown one step forward
Convinced by the ease and power of Markdown, I integrated it into many other parts of my workflow. I write this article within Ulysses, a Markdown editor. I create every document longer than two paragraphs with Ulysses. Brief notices go into Drafts formatted in Markdown. Drafts exports valuable informations as Markdown files in a separate directory. An Obsidian workflow organizes these files by themes. Details about my Obsidian workflow.
RStudio has many tools to make presentations from R Markdown files. I use Deckset to create scientific presentations without calculations.
Next level R, Shiny
When I became more familiar with R, I analyzed some business data from my company, first from my department, then from other departments and the entire company. Three years ago a manager, responsible for the monthly reporting, retired. Until then he has organized the reporting in some Excel-sheets, collecting the data by hand from original source, sending the sheets to all department managers. With the experience from R and Markdown, it was easy to build an online reporting based on R and Shiny. Now the monthly reporting is quick and safe. I use the export of our hospital management system (HMR), analyze (preprocessing) the data, and launch them online. An example with synthetic data is here: Hospital Reporting. Even a map with the geographic distribution of our patients was possible.
My personal experience
It’s unnecessary to learn R Markdown to become familiar with Markdown. This was my way to get into contact with Markdown. I now use Markdown daily. My personal and professional workflow is based on Markdown. Markdown creates high quality output, without the pressure to learn different programs. It’s always the same simple syntax. Even if I design documents for my department, I create them in Ulysses and export them to .docx, because my company still works with M*soft products.
I use R for business and science projects, meanwhile there are over 40 projects written in R Markdown. I use many of the projects once or twice a year. R Markdown simplifies this occasional use. Sometimes when I have sparse time I join Kaggle competitions.
The Markdown universe is still growing, many apps support Markdown in the meantime. It is becoming industrial standard. Join it.
