Scroll down to the section labeled ## Using RMarkdown

Using RMarkdown

RMarkdown is a file format that allows us to interleave text (with some simple formatting control), code, the output of code, and plots produced by code, in a single file.

This gives us less to keep track of, and it also ensures that our data, our code and the output or plots we’re reporting are consistent with each other.

Since the whole document is plain text, it’s small, fully portable, and we don’t need to use any paid software to open it.

However, even though what you’re looking at now is plain text, we can produce a more elegant looking version of the document by “compiling”, or what’s called “Knitting”, the plain text into one of several formats: HTML, PDF, or Word.

  1. Try this now: Look for a button above that says “Knit”. In the dropdown menu, select HTML. You should get a popup window (your popup blocker might complain initially; just allow it to display the popup).

As you work on a project or assignment, you should periodically Knit your file, to verify that your formatting is correct (do it often enough that if you get an error you don’t have to hunt through a large swath of text and code to locate the source)

The document “metadata”

At the very top of this file, above the three dashes, is a section that defines some “metadata” for ths document. This includes things like the title, author, and formatting instructions for the document as a whole.

  1. Before moving on, fill in the “Author” field in the metadata section with your names.

Section headers

The ## in this context indicates a heading. One # is a document title level heading. More #s means a subheading.

Subheadings

The section “Subheadings” is a subsection of “Section headers”

Text formatting

Adding emphasis

Text can be decorated with bold or italics (equivalently, italics).

Lists

We can make bulleted lists like this:

  • My first item
  • My second item

Be sure to put a space after the * when you are creating bullets and a space after # when creating section headers.

Code chunks

Creating and running code chunks

We can embed “chunks” of R code inside our document by containing it in a “fence”, which looks like this:

  1. Add a blank line after the word ‘here’ in the chunk above, and in that line, type 2 + 2.

To see the output the chunk, click on the “Play” button (the green triangle in the upper right corner of the chunk).

You can insert a new R code chunk either with the Insert > R menu in RStudio, or with a keyboard shortcut (See the Code dropdown menu for the shortcut for “Insert Chunk”). Or you can just type the “fence” directly (though this is easy to mess up at first)

Chunks Producing Graphics

If the code of an R chunk produces a plot, this plot can be displayed in the resulting file.

The chunk below creates a scatterplot using a dataset called Births78. Don’t worry about what the code does for now; we’ll get to that soon.

  1. Try running the chunk using the “Run chunk” button (looks like a ‘play’ button). (Emphasis on ‘try’: You may well get an error message; we’ll get to that below)
## Warning: `data_frame()` was deprecated in tibble 1.1.0.
## Please use `tibble()` instead.

Running previous chunks

You probably got an error message when you tried to run the chunk above. That’s because it relies on other code to have been run (loading the data and the package that supplies gf_point) for the things it uses to be defined.

You can run all previous chunks with the second-to-rightmost button in the upper right.

  1. Go back to the chunk above and ues the ‘Run All Chunks Above Button’ to run the prerequisite code. Then run that chunk again. You should now get the scatterplot displaying just beneath the code.

Aside: Chunk settings

There are also some chunk settings you can modify by clicking the “gear”. This includes

  • whether or not we want the code in that chunk to be run when we produce the output file
  • whether we want the code itself to appear in the output
  • whether we want the results of the code to appear in the output
  • how large or small we want plots produced by the code chunk to be
  • as well as others

R output

Other forms of R output are also displayed as they are produced. The chunk below will display the average number of daily births for each calendar month for this dataset as “raw text” output.

Again, don’t worry about the specific command for now; we’re just trying to get a feel for how chunks work.

##        1        2        3        4        5        6        7        8 
## 8732.097 8924.107 8922.065 8485.900 8735.871 9025.200 9506.484 9767.581 
##        9       10       11       12 
## 9796.367 9321.129 9155.700 9191.194

“Knitting” the Markdown document

Once again, to “render” the complete document, we “Knit” the file, either to HTML, PDF, or Word.
Just select the desired output file type and click on Knit HTML, Knit PDF, or Knit Word (there are also keyboard shortcuts to Knit to the default format if you prefer that)

  1. Try this again, to get into the habit: Knit this document into an HTML file, and look over it to see how each section is rendered.

Turning in Files on the Server

  1. This orientation lab is not being graded, but let’s turn it in anyway to get used to turning in files on the server. When you’re done, go to the Files tab in the lower right, and find the folder inside stat213 called turnin. Within that there’s a folder called R-orientation. Do Save As... with your .Rmd file, and put it in the stat213/turnin/R-orientation folder as markdown-tutorial.Rmd. Now, go back to your project folder in the Files tab, and find the Knitted file called markdown-tutorial.html. In the Files tab, click the “gear” icon that says “More”, and choose “Copy To…”. Save a copy of markdown-tutorial.html in stat213/turnin/R-orientation as well.

Documenting file creation

It’s useful to record some information about how your file was created at the very end of the file. I will typically include the following ‘footer’ in the templates I provide you.

  • File creation date: 2021-05-28
  • R version 3.6.0 (2019-04-26)
  • R version (short form): 3.6.0
  • mosaic package version: 1.5.0
  • tidyverse package version: 1.3.1
  • Additional session information
## R version 3.6.0 (2019-04-26)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 18.04.5 LTS
## 
## Matrix products: default
## BLAS:   /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.7.1
## LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.7.1
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
##  [1] mosaic_1.5.0      Matrix_1.2-17     mosaicData_0.17.0
##  [4] ggformula_0.9.1   ggstance_0.3.1    lattice_0.20-38  
##  [7] forcats_0.5.1     stringr_1.4.0     dplyr_1.0.5      
## [10] purrr_0.3.4       readr_1.4.0       tidyr_1.1.3      
## [13] tibble_3.1.1      ggplot2_3.3.3     tidyverse_1.3.1  
## 
## loaded via a namespace (and not attached):
##  [1] ggdendro_0.1-20  httr_1.4.2       jsonlite_1.7.2   splines_3.6.0   
##  [5] modelr_0.1.8     shiny_1.3.2      assertthat_0.2.1 cellranger_1.1.0
##  [9] yaml_2.2.0       ggrepel_0.8.1    pillar_1.6.0     backports_1.1.4 
## [13] glue_1.4.2       digest_0.6.21    promises_1.0.1   rvest_1.0.0     
## [17] colorspace_1.4-1 htmltools_0.3.6  httpuv_1.5.1     pkgconfig_2.0.3 
## [21] broom_0.7.6      haven_2.4.1      xtable_1.8-4     scales_1.0.0    
## [25] later_0.8.0      generics_0.0.2   ellipsis_0.3.0   withr_2.4.2     
## [29] lazyeval_0.2.2   cli_2.5.0        magrittr_2.0.1   crayon_1.4.1    
## [33] readxl_1.3.1     mime_0.7         evaluate_0.14    fs_1.3.1        
## [37] fansi_0.4.0      MASS_7.3-51.4    xml2_1.3.2       tools_3.6.0     
## [41] hms_1.0.0        lifecycle_1.0.0  munsell_0.5.0    reprex_2.0.0    
## [45] compiler_3.6.0   rlang_0.4.11     grid_3.6.0       rstudioapi_0.13 
## [49] htmlwidgets_1.3  crosstalk_1.0.0  labeling_0.3     mosaicCore_0.6.0
## [53] rmarkdown_2.5    gtable_0.3.0     curl_3.3         DBI_1.0.0       
## [57] R6_2.4.0         gridExtra_2.3    lubridate_1.7.10 knitr_1.25      
## [61] utf8_1.1.4       stringi_1.4.3    Rcpp_1.0.2       vctrs_0.3.8     
## [65] leaflet_2.0.2    dbplyr_2.1.1     tidyselect_1.1.1 xfun_0.19