railroad crossing sign cropped to only show one R
PHOTO: Cris DiNoto

Business analysts, budding data scientists and marketers need the ability to quickly create reproducible reports. And they've all worked out which analytic solution they prefer to accomplish the task. But for those who prefer using programming to create a data model for analysis, an extra step is required: creating a document for colleagues to view and understand the results without an understanding of the supporting code.

Teams using R programming can do this by collaborating on Markdown documents. Markdown is a document structure that generates reports containing computing code, graphs and associated text in a user-friendly structure. The features in Markdown allow multiple people to access to the work while maintaining a central document.

R Markdown: Separating the Code from the Results

In my previous article, "Here’s Why Every Modern Marketer Needs R Programming," I noted many instances where marketers can conduct a few lines of code and save it in a script file or project file. Those choices work fine for someone who is walking through a programming logic and needs to document it for their own purposes.

But what happens once other people who are unfamiliar with R but interested in the results are included?

R Markdown addresses that by breaking down the code and supporting material into sections, giving readers a clear focus on the details that relate to their decision needs. That prevents people from being overwhelmed by programming syntax, especially if other non-technical professionals are involved.  

Related Article: How Marketers Can Plan Data Mining With R Programming

Getting Started With R Markdown

Let’s say a paragraph describing the result of the code is required, a description that other managers can read easily rather than a terminal-like programming output as the answer.

To use Markdown, a user must download the knit library, which places the code and associated files in an .RMD file. The library and steps to create a Markdown file can be done without an IDE, but most professionals uses R Studio.

Users go into R Studio IDE and create a Markdown file by navigating to the menu options “file,” then “new file” and then “markdown” which shows a menu with key choices. The menu contains document choices, presentation choices, Shiny (an app designed to host an R function) and a template choice. Templates are a custom layout format for applying a standard format, such as a corporate layout that includes company colors and logo image.

R markdown

Users can then insert a section of code, called a "chunk" in developer language. The chunk is highlighted with three back apostrophes like the following:


```{r}’’’ is typed where r indicates the language name that the Markdown file is meant to use and ends with three back apostrophe.

Users can incorporate chunks from a few other languages, including SQL and Python. This can save time if other codes and graphs are in a different format than R.  

Users can then add other parameters within the brackets, designed to specify how the code is managed within the Markdown document. Two basic parameters that marketers will likely use are include and echo. Include can be set to TRUE if the code appears in the document chunk or FALSE if the code doesn't appear. The parameter echo is set to TRUE if the code appears with the results or FALSE if you just want the results.

echo knit

Once done, you use the knit button to create the actual Markdown file.

The resulting R Markdown file saves code, output and associated commentary in a single file.

markdown document

Users also have the option to publish reports into other formats such as HTML, PDF and Microsoft Word. Markdown can also be issued as a Notebook, another document format for sharing how a project evolved, putting teams on the same page regarding project needs and workflow.

Related Article: 4 Skills Modern Developers Need

Providing a Window Into Analysis

The basic result of this process is it gives you the ability to understand the assumptions being placed into models when code is run. A marketer can use Markdown to review and adjust the order of the chunks and text, seeing how the results from an analysis changes without having to use the developer interface or worrying about mishandling a line of code.

Other libraries and parameters can add flexibility when working with Markdown features. RStudio provides a cheatsheet that summarizes the basic available Markdown features.  

Markdown documents can be a great way to establish a central view of data to serve the individual needs of multiple stakeholders. The shared understanding then allows everyone, including marketing managers, to examine any assumptions made in an analysis and to make sure data-driven decisions are really leading to solid business objectives.