1 Rmarkdown

Rmarkdown allows you to generate html, pdf and even word files. You can easily integrate R as Python and make your analyses in the document in order to communicate your code or their outputs (e.g. automate a report).

Unlike latex and html markdown is very easy to read in its raw state. The layout, titles, tables etc… are very easy to handle and do not hinder readability.

Before going deeper into details, see how to easily create an html or a pdf (or others) with Rmarkdown using R studio:

1.1 Create a new Rmarkdown document

Fill name and title

It automaticcaly creates a report example

Modify the file structure, see how you can put both r and python code in your report

To create the html document clic on ‘knit’, you can choose html or pdf as outputs (and others).

See the results in html

in PDF

1.2 Rmarkdown structure

Check this cheatsheet: https://rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf

1.2.1 YAML Header

The header of a Rmarkdown file is by default structured as follow :

---
title: "My Title"
author: "Name"
date: "10/02/2021"
output: html_document
---

You can remove some if you don’t want the date to be in the document for example. You can also specify more details to custom the output. For example you may want to add the table of contents at the begining of your document, the YALM will be then :

---
title: "My Title"
author: "Name"
date: "10/02/2021"
output:
  html_document:
    toc: true
    number_sections: true
---

You can add an abstract to your document directly in the YAML header :

---
author: "Name"
abstract: "Abstract"
output:
  pdf_document:
    toc: true
    number_sections: true
---

You can change the theme of your html output choosing in this list : https://bootswatch.com/3/ For example, the theme of this website is Flatly.

---
output:
  html_document:
    theme: flatly
---

More information here for html document: https://bookdown.org/yihui/rmarkdown/html-document.html

1.2.2 Text

To create a title in markdown you need to use a # each # represents a title level. ## returns a level two title.
To create a new paragraph just end a line with two spaces. Otherwise you can skip a line to start a new paragraph but there will be a space between the two paragraphs.
To write in italics or bold you only have to specify one * or two ** respectively.
Escaped character (remember it from chap 3 ;) ) must be specified with a \ before. \* give *
To write example of code without running it like this import numpy as np just use ```import numpy as np```
Show image from your computer in the output ![title](path/to/img.jpg)
You can write directly in html, for example add a link to an external webpage : <a href="https://www.google.com/">Google</a>
You can write in $\LaTeX$: $\frac{1}{2}$ . You just need to write the equation between two $
To make bulletpoints like this:
- here
  - and here, please use * then + then - for different levels. Also just using - and four whitespaces for each level works also.

1.2.3 Code chunks

By default the first chunk is about chunk options. It is presented like this :

knitr::opts_chunk$set(echo = TRUE)

You can set there chunk option for all you document, you can specify if we will see the code, the output, warnings, errors etc etc. Please see all options on the cheatsheet.
As you noted a chunk start with ```{}. First you specify the language used within the chunk and then the title of the chunk, after the comma, specify options for the given chunk :
```{r chunk1, error = T}

1.2.4 Slides

You can create slides directly with Rmarkdown also , ioslide and slidy will be used to create html slides, which are cool if you want to put interactive stuff in your slides, otherwise beamer can be used for static presentation in pdf

To create a new slide just type --- between two empty lines or create a new title.

1.3 Execute rmd automatically

From R :

rmarkdown::render('C:/Users/Beta/Documents/GitHub/M1_TDP/examples/Markdown/test.Rmd', 'pdf_document')

From Shell:

R -e "rmarkdown::render('C:/Users/Beta/Documents/GitHub/M1_TDP/examples/Markdown/test.Rmd', 'pdf_document')"

From Python :

import os 
os.system('''R -e "rmarkdown::render('C:/Users/Beta/Documents/GitHub/M1_TDP/examples/Markdown/test.Rmd', 'pdf_document')" ''')

2 GitHub

Github is a company that creates products that use the open source tool git. From wikipedia: “Git is a distributed version-control system for tracking changes in any set of files, originally designed for coordinating work among programmers cooperating on source code during software development.”.

2.1 Create a repository

A repository is usually used to organize a single project. Repositories can contain folders and files, images, videos, spreadsheets, and data sets etc, etc.

On your GitHub account create a new repository:

Name the project, Add a README, gitignore is used to ignore some files format that are stored in the same folder on your computer.

Now that you have a repository, you may want to invite people to collaborate with you and give them writing rights to the project. Conversely, these collaborators can also clone the project and then ask to attach their versions to yours afterwards.

Invite a collaborator

2.2 Clone a repository

If you are not the creator of the repository, you can clone the repository to have it on your computer and then modify the project. In the same way you can easily use other people’s programs by cloning their repository.

2.3 Create branches

Now that the directory is created, collaborators can work on it and contribute to the project. The final version of the project can be found on the ‘main’ branch.
You can create a branch in order to start editing the project and save your changes on your own branch. Often branches will be linked to specific aspects of the project and will then be removed once the changes have been integrated into the final version.

You can publish this branch if you want it to be merged to the main branch after your changes.

2.4 Commit your changes

Once you have finished your changes for the day but you are still not at the stage where your branch has to be merged with the main branch you can push your commits to save them and make them available to the other one (still on your branch).

On github you can see the project as well as the two branches that compose it

2.5 Create Pull Request

Once your changes are complete you can now submit your changes to the community and create a pull request.

This will signal to others that your changes are ready and that adding them to the final project needs to be discussed. You can also check the changes approved by the main branch before merging them.

Then the authors of the repository will be able to approve or not the merge of the two branches. As I’m a collaborator of the project I can do it by myself.

Once the modifications are validated, you can delete the branch that was created for the occasion.

So we only have one branch left in our repository with the modifications made on the solutions folder.

Keeping your folder update
If you are working on different aspects of your project you probably want to integrate into your computer folder the changes made by your collaborators, so you should regularly check if any changes have been made to a given branch and pull origin if necessary. Make sure you check the changes made to the files before doing it!

Best Practices