Expand your coding skills to share your science

Details

Nov 30, 2-3pm

CSF 1302

Bring your laptop

Please register

To help with planning, please register here. There will be PIZZA!

If you have questions or need help, please email ahurford-at-mun-dot-ca. If you would like to participate, but don’t have a laptop - we can help! (if you email and let me know)

Workshop description

Thanks to everyone who has helped further our quantitative training objectives in the Biology department at MUNL. For students, staff, and faculty who would like more, this workshop is a fun way to end the semester.

The workshop will foster community in departments that collect data for advancement of quantitative training. Interested experts are welcome to attend, but the workshop is designed with beginners in mind.

In the workshop you will learn how to use R to Share your Science. We will help, and experience in R is not required. The schedule is:

PART I. Rmarkdown (so we can integrate our code and write-up, write equations, etc)

PART II. bookdown (stitching our R markdown pages together into an ebook)

You will also learn how to host these files of the internet.

This is a hands-on workshop: you will be doing the work!

Get prepared (To do before the workshop)

All software, packages, and workshop resources are free.

You need R and RStudio. If you need to install these, see here
To participate in I., you need to install the package rmarkdown. To output to a .pdf you need to install the package tinytex (not necessary if you already have TeX installed or are fine to output to .html or .docx only)
To participate in II. you need to install the package bookdown.
To host your ebook on the internet you need a Github account. You may wish to make one ahead of time. You can make a website (but not an ebook) with an RStudio account. Both accounts are free.
For ease in data manipulation and for making beautiful plots you might install the packages dplyr and ggplot2. Also install any dependencies and if asked about sources that require compilation answer n. To install packages see instructions here

Workshop

PART I. R markdown

Why use R markdown?

Integrate code and write-up to avoid mistakes moving between .R (or other software) for analysis and .docx for write-up.
It is easier to find all your work when everything is in one file (or linked to from one file).
Run code in the background of your write-up so that if something changes the write-up automatically updates in all the relevant places. The reduces the chances of errors in your write-up.
Publish your work as a website. This facilitates hyper-linking, you can update your work at any time, avoiding emailing your work keeps email storage free, and your work can be easily shared (i.e., in conversation I might say ‘that analysis is linked off my faculty website’).
Include math symbols quickly because your hands don’t leave the keyboard to make selections from drop-down menus.
If your analysis is time-consuming you might not want the calculations in your write-up, slowing the compilation of your write-up. In this case you might have a separate .R analysis file that outputs your results as a .csv or plot. You can read these in automatically to your write-up by specifying the path to the .csv or plot.

In R Studio, select File > New Project... > R Markdown. Give the file a name, etc.
The default .Rmd opens already with some code to help you. With the default .Rmd opened, there should be a Knit button at the top and center of the Editor pane. Click the Knit button to knit to .pdf, .html, or .docx output. Alternatively, do Cmd/Ctrl + Shift + K.

(If this did not work, perhaps you have not installed the rmarkdown or tinytex packages)

Beside the Knit button is an arrow. You have the option to knit to .pdf, .html, or .docx output. Try producing other outputs.

(For me, producing a .docx opened Skype (clearly a bug). This was fixed by using Finder (on my Mac) to find the .docx file that I made, and selecting Open With > Microsoft Word)

Below are some things to try. Choose the ones that interest you most. Type the code, then Knit to see what happens.

Include variables in-text by enclosing in $x$ , i.e. this renders as $x$, which is italicized to indicate in your writing that $x$ is a variable rather than a letter.
Load data using R commands. (If you want to do this quickly copy and paste the command at the end of this section)
Hide the code that loads the data in the output. i.e., read about the options for r code chunks: echo, include, message, warning, eval, and results. Print the data in your output. Show both the code and the output. Try it all!
Show only your code print out. Can you do this?

##   Psoil Pcorn
## 1     1    64
## 2     4    71
## 3     5    54
## 4     9    81
## 5    13    93
## 6    11    76

Make a plot of your data, but hide the commands that produce the plot. Make a figure caption.
Include code in-text as `r x `. This renders as 80 because in a hidden coding block I loaded data and assigned x<-mean(data$Pcorn). Therefore, the reported value of $x$ = 80 is the mean phosphorous in the soil for the data I loaded in the background. If the data change, the mean reported in this document will automatically change too.
Make headings, subheadings, bold font, etc.
Make a hyperlink.
Include a figure that is a .png or other format. (I find using knitr::include_graphics() within a code chunk best.)
Use latex commands to include in-text equations, i.e., $y = \beta_0 + \beta_1 x$ renders as $y = \beta_0 + \beta_1 x$; $\frac{dy}{dt} = e^x$ renders as $\frac{dy}{dt} = e^x$. (The website Detexify is fun for identifying latex commands for different symbols (Some advanced symbols may require packages that your haven’t installed and therfore won’t work)).
Try some more complicated Latex.
Try to publish your .html. Knit to .html, click Publish and select RPubs (the free option).

data <- read.csv('https://raw.githubusercontent.com/ahurford/biol-4605-data/main/data/corn.csv', fill=TRUE)

If you would like a more structured introduction to R Markdown you can read R Markdown: the definitive guide.
This R markdown cheat sheet is helpful.
Some more advanced skills you might learn are making alert boxes, or changing some of the options in the YAML. The alert boxes in this document are made as div class="alert alert-info" between < >, then the text, and closed with /div between < >.
My experience making tables in .Rmd has not been good. Usually, I make the table in .docx, print to .pdf, take a screenshot and import the .png to .Rmd or .tex.

PART II. Bookdown

Why use bookdown?

The bookdown package assembles individual .Rmd into pages of an ebook and makes a table of contents.
Making an ebook allows you to have many .Rmd, organized, and to just use one url for hosting.

Read about bookdown here.
Get started making your ebook by following these instructions. To summarize the link: select File > New Project..., Create new directory > book project using bookdown (scroll down to find this option). This may be new: you have created a new project rather than a new file. This is indicated in the top right hand corner of R Studio. Later, if you open your ebook, you need to open the project, not just the files (or you will not be able to build your book).

Try to Build the example book. You need to find a hammer next to Build available from the Build tab (see below) on a pane on the top righthand side. You might need to resize panes for it to appear.

(If there is no Build tab, perhaps you do not have a Project open)

The ebook compiles index.Rmd as the first page, and then you number the .Rmd appropriately. Look at the Files tab for the example book to see how this is done:

What you learned about rmarkdown in Part I will now help you with customizing the content of your ebook. When I don’t know how to do something, I perform an internet search. Often my search refers me to the book bookdown: Authoring Books and Technical Documents with R Markdown.
I host my books using GitHub Pages. In GitHub make a new repository by clicking the green new button on GitHub when you are signed in. The repository must be public.

Choose uploading an existing file. Move everything in your folder for your ebook over to the github repository.

Once the upload is complete, commit the changes.

From the top menu, on the far right, select Settings.

From the left menu, select Pages.

Under the Branch heading, select main and click Save.

After less than 5 minutes, if you have succeeded on the Pages tab it will report your url (see below).

On your main repository page, your website will be listed as active.

If you plan to manage your online ebook this way, I recommend beginning by using GitHub Desktop, which makes it easy for beginners in GitHub to update their websites.

Feedback

Leave feedback on the workshop here.