class: center, middle, inverse, title-slide .title[ # MT611 - Quantitative Research Methods ] .subtitle[ ## Lecture 8: Introduction to Quarto for Research ] .author[ ### Damien Dupré - Dublin City University ] --- # Objectives In this lecture, with Posit Cloud, we will see how to create **Quarto** files (.qmd) to embed text and code output and generate professional outputs. -- #### What do I need to do before starting? - Sign up for a free Posit cloud account - https://posit.cloud/ -- #### Where can I find more resources? - [Official Quarto Website](https://quarto.org/) - [R for Data Science](https://r4ds.hadley.nz/quarto.html) - [Appsilon](https://appsilon.com/r-quarto-tutorial/) - [Making shareable documents with Quarto](https://openscapes.github.io/quarto-website-tutorial/) - [Quarto 2hr webinar](https://jthomasmock.github.io/quarto-2hr-webinar/materials/01-intro-quarto.html) --- # What is Quarto? Quarto is an open-source scientific and technical publishing system that builds on standard markdown with features essential for scientific communication. - Computations: Python, R, Julia, Observable JS - Markdown: Pandoc flavored markdown with many enhancements - Output: Documents, presentations, websites, books, blogs See https://quarto.org for more details -- The Goal is to create a document that is all-in-one - Documents that include source code for their production - Notebook AND plain-text flavors - Programmatic automation and reproducibility --- # Two Sides of Quarto Files .pull-left[ ### On the editor side... - Write text in markdown - Insert code using R or Python - Write "metadata" with YAML ] .pull-right[ ### On the output side... - Output to HTML - Output to PDF - Output to Word - Many other variations too ] -- Try it by yourself! --- class: title-slide, middle ## Your turn! In your Posit Cloud: 1/ Create a new Quarto document: `File > New File > Quarto Document` 2/ A popup will appear, untick **"Use visual markdown editor"** 3/ Leave everything else as default and click `Create` 4/ If a warning appears, click `Install` on the message to install the {rmarkdown} package <!-- --> 5/ Click the blue arrow `Render` and save the document as `report.qmd`
−
+
05
:
00
--- # Simple Example <img src="https://quarto.org/docs/tools/images/new-quarto-doc.png" width="80%" /> --- # Simple Example .pull-left[ <!-- --> ] .pull-right[ <!-- --> ] --- # Quarto Structure Quarto files have 3 different types of content: #### 1. The YAML Displayed between two series of `---` signs, it corresponds to the metadata shown in the header of the output file (e.g., title, author, date, ...) and the type of output (e.g., pdf, html, doc, ...) #### 2. The Text Written in Markdown style (i.e., text without formatting), it is used as core description in the output document #### 3. The Code Inserted in the Quarto inside "chunks", the code is processed when creating the output and can display figures and tables --- # The "YAML" <img src="https://raw.githubusercontent.com/damien-dupre/img/main/quarto_default_yaml.png" width="80%" /> --- # The Markdown Text <img src="https://raw.githubusercontent.com/damien-dupre/img/main/quarto_default_markdown.png" width="80%" /> --- # The R Code <img src="https://raw.githubusercontent.com/damien-dupre/img/main/quarto_default_code.png" width="80%" /> --- # Create the Output File .pull-left[ To generate the output file: 1/ Go to `File > Render Document` (a Use the `Render` shortcut icon is also displayed in the menu bar) <kbd></kbd> <!-- --> 2/ Give a name to your document, click `OK`, and voila! ] .pull-right[ <img src="https://raw.githubusercontent.com/damien-dupre/img/main/quarto_create.png" width="100%" /> ] --- # Quarto Editor vs Output .pull-left[ <!-- --> ] .pull-right[ <!-- --> ] --- class: inverse, mline, center, middle # 1. The YAML --- # Output HTML ### Simple ``` --- format: html --- ``` -- ### Default ``` --- title: "My First Quarto Document" format: html date: "99/99/9999" --- ``` -- ### Elaborated ``` --- title: "My First Quarto Document" subtitle: "My Subtitle" author: "Damien Dupre" date: "99/99/9999" format: html --- ``` --- # Execute Code Quarto can use R or Python to execute code: - R code is executed natively with the `{knitr}` engine - Quarto can _also_ use the `Jupyter` engine to execute Julia, Python, or other languages that Jupyter supports -- .pull-left[ If R code is found first will default to `knitr` ```yaml --- format: html --- ``` Or can force using `knitr` if you're mixing R/Python content or if your first code chunk is not R. ```yaml --- format: html engine: knitr --- ``` ] -- .pull-right[ You can specify Jupyter to use defaults: ```yaml --- engine: jupyter --- ``` Or a specific Python version ```yaml --- engine: python3 --- ``` ] --- # Execute Code Quarto also introduces some of these as options for `execute:` in YAML, for similar concepts in other languages. ```yaml --- format: html execute: echo: false warning: false message: false --- ``` --- class: inverse, mline, center, middle # 2. Markdown Style --- # Emphasising Text .pull-left[ <br><br> ### What you type... <br> ``` this is *italics* this is **bold** this is ***bold italics*** ``` ] -- .pull-right[ <br><br> ### What you get... <br> this is *italics* this is **bold** this is ***bold italics*** ] --- # Creating Lists .pull-left[ <br><br> ### What you type... <br> ``` - unnumbered lists - look like this 1. numbered lists 2. look like this ``` ] -- .pull-right[ <br><br> ### What you get... <br> - unnumbered lists - look like this 1. numbered lists 2. look like this ] --- # Creating Headings .pull-left[ <br><br> ### What you type... <br> ``` # Level 1 heading ## Level 2 heading ### Level 3 heading ``` ] -- .pull-right[ <br><br> ### What you get... <br> ## Level 1 heading ### Level 2 heading #### Level 3 heading ] --- # LaTeX Equations .pull-left[ <br><br> ### What you type... <br> ``` $$ JS_i = b_0 + b_1 Salary_i + b_2 Perf_i + e_i $$ $$ e_{i} \sim \mathcal{N}(0, \sigma_{i}) $$ ``` ] -- .pull-right[ <br><br> ### What you get... <br> $$ JS_i = b_0 + b_1 Salary_i + b_2 Perf_i + e_i $$ $$ e_i \sim \mathcal{N}(0, \sigma_i) $$ ] --- # Markdown Example .pull-left[ **Example of a markdown document...** ``` ## Introduction Welcome to my **awesome** class. You will learn all kinds of useful things about Quarto. - Markdown is simple - You can add R code - You can add $\LaTeX$ inline - You can add LaTex equations: $$y=ax+b$$ ``` ] .pull-right[ **Here's what the output looks like...** ## Introduction <br> Welcome to my **awesome** class. You will learn all kinds of useful things about Quarto. - Markdown is simple - You can add R code - You can add `\(\LaTeX\)` inline - You can add LaTeX equations: `$$y=ax+b$$` ] --- class: title-slide, middle ## Your turn! In Posit Cloud, with the file that you have previously created: 1/ Remove all content except the YAML 2/ Modify the YAML to include: ```yaml --- format: html execute: echo: false warning: false message: false --- ``` 3/ Write a sentence about your emotions (positive and negative) triggered by R, use `*` and `**` to highlight some part of your text in italic and bold 4/ Add a section title with `##` and a subsection title with `###` 5/ Click "Render" once finished
−
+
05
:
00
--- class: inverse, mline, center, middle # 3. The R Code Chunks --- # Anatomy of a Code Chunk ````markdown ```{r} #| label: organisation-beta-lm #| echo: false model <- lm(formula = js_score ~ salary + perf, data = organisation_beta) ``` ```` - Has 3x backticks on each end ` ``` ` - Place engine (`r`) between curly braces `{r}` - Place options underneath, behind the `#|` (hashpipe): `#| option1: value` --- # First Code Chunk In the first code chunk, will be added all the __actions that will be applied to the following chunks__ (e.g., code option, library used, data downloaded, ...). ````markdown ```{r} #| label: setup #| include: false # libraries library(tidyverse) # data organisation_beta <- read_csv("/cloud/project/organisation_beta.csv") ``` ```` --- # Code Chunk Options Chunk output can be customized with hashpipe options (i.e., arguments set after the `#|`). Above, we use 1 argument: - `#| include: false` prevents code and results from appearing in the finished file. Quarto still runs the code in the chunk, and the results can be used by other chunks. Additional options can be turned on only for one chunk: - `#| results: asis` will display the output of the code as regular text See the **[Quarto Reference Guide](https://quarto.org/docs/reference/cells/cells-knitr.html)** for a complete list of chunk options. --- # Figures in the Output Document As long as the package {tidyverse} is loaded and the data object created in the first setup chunk, then a __ggplot visualisation can be used in a separated chunk__: .small[ ````markdown --- title: "Untitled" output: html execute: echo: false warning: false message: false --- ```{r} #| label: setup #| include: false library(tidyverse) organisation_beta <- read_csv("/cloud/project/organisation_beta.csv") ``` # My Section Title My text followed by my figure. ```{r} ggplot(organisation_beta) + aes(salary, js_score) + geom_point() ``` ```` ] --- # Working with Code To display the output of your code in the final document, just include your code in a chunk: ````markdown ```{r} lm(formula = js_score ~ salary + perf, data = organisation_beta) ``` ```` ``` ## ## Call: ## lm(formula = js_score ~ salary + perf, data = organisation_beta) ## ## Coefficients: ## (Intercept) salary perf ## -49.48511 0.00187 0.08285 ``` --- # Working with Code Remember, when the code results in creating an object, while the object is created, no output is printed in the final document: ````markdown ```{r} model <- lm(formula = js_score ~ salary + perf, data = organisation_beta) ``` ```` --- # Working with Code To create an object and print your code in the same chunk, the name of the object has to be included in the chunk. This will print the content of the object: ````markdown ```{r} model <- lm(formula = js_score ~ salary + perf, data = organisation_beta) model ``` ```` ``` ## ## Call: ## lm(formula = js_score ~ salary + perf, data = organisation_beta) ## ## Coefficients: ## (Intercept) salary perf ## -49.48511 0.00187 0.08285 ``` --- # Visualisation Specific Options Some chunk options are specific to visualisations outputs: - fig-cap: "caption of the figure" - fig-height: 5 - fig-width: 5 Note, the default unit for height and width is inches. ````markdown ```{r} #| fig-cap: "caption of the figure" #| fig-height: 5 #| fig-width: 5 ggplot(organisation_beta) + aes(salary, js_score) + geom_point() ``` ````  --- class: title-slide, middle ## Live Demo --- class: title-slide, middle ## Your turn! In your **report.qmd** document: 1/ **Create a first code chunk** called `setup`. In this chunk, load the `{tidyverse}` and `{report}` packages and create your data object with the following code: ```markdown organisation_beta <- read_csv("/cloud/project/organisation_beta.csv") ``` 3/ **Create a second code chunk**. In this chunk, run the following linear regression and add `#| results: asis` in its options: ```markdown lm_js <- lm(formula = js_score ~ salary + perf, data = organisation_beta) report(lm_js) ```
−
+
05
:
00
--- class: title-slide, middle ## Your turn! 4/ Create a third code chunk. In this chunk, include the following visualisation: ```markdown ggplot(organisation_beta) + aes(salary, js_score) + geom_point() + geom_smooth(method = "lm") + theme_bw() + labs( x = "Employee Salary (Eur)", y = "Employee's Job Satisfaction" ) ``` 5/ Render the default document obtained to observe its structure
−
+
03
:
00
--- class: inverse, mline, center, middle # 4. Gallery --- # Professional Websites <img src="https://raw.githubusercontent.com/damien-dupre/img/main/example_professional_site.png" width="70%" /> --- # Books <img src="https://raw.githubusercontent.com/damien-dupre/img/main/example_book.png" width="100%" /> --- # Slide Decks <img src="https://raw.githubusercontent.com/katiejolly/blog/master/assets/slide-design/twitter_img_march.png" width="100%" /> --- # CV <img src="https://kevinrue.github.io/post/writing-my-cv-using-pagedown/featured_hu415bb52acda44839a73c9c4234bb7d44_345471_720x0_resize_lanczos_2.png" width="80%" /> --- # Academic Papers <img src="https://raw.githubusercontent.com/damien-dupre/img/main/example_papers.png" width="60%" /> --- class: inverse, mline, center, middle # 5. Quarto Journal Templates --- # Quarto Journal Templates The Quarto team has developed several Journal formats and made them available within the [quarto-journals GitHub organization](https://github.com/quarto-journals/). These formats include the following Journal/Publisher: - Association of Computing Machinery - American Chemical Society - American Geophysical Union - Biophysical journal - Elsevier Journals - American Statistical Association - Journal of Statistical Software Many more formats will be added over time. The quarto use template command can be used to create an article from one these formats from the terminal (and not the console). For example: ``` quarto use template quarto-journals/acm quarto use template quarto-journals/acs quarto use template quarto-journals/agu quarto use template quarto-journals/biophysical-journal quarto use template quarto-journals/elsevier quarto use template quarto-journals/jasa quarto use template quarto-journals/jss quarto use template quarto-journals/plos ``` --- class: title-slide, middle ## Live Demo --- class: title-slide, middle ## Your turn! In your Posit Cloud: 1/ Create a new quarto-journals document using one of the following template from the terminal: ``` quarto use template quarto-journals/acm quarto use template quarto-journals/acs quarto use template quarto-journals/agu quarto use template quarto-journals/biophysical-journal quarto use template quarto-journals/elsevier quarto use template quarto-journals/jasa quarto use template quarto-journals/jss quarto use template quarto-journals/plos ``` Say `Y` when asked if you trust the authors of this template and choose a directory name of your choice. 2/ Render the default .qmd document obtained to observe its structure
−
+
05
:
00
--- class: title-slide, middle ## Your turn! In this new .qmd document: 1/ Remove everything except the YAML 2/ Create a first `setup` chunk. In this chunk, load the `{tidyverse}` and `{report}` packages and create your data object with the following code: ```markdown organisation_beta <- read_csv("/cloud/project/organisation_beta.csv") ``` 3/ Create a second code chunk. In this chunk, run the following linear regression and add `#| results: asis` in its options: ```markdown lm_js <- lm(formula = js_score ~ salary + perf, data = organisation_beta) report(lm_js) ```
−
+
05
:
00
--- class: title-slide, middle ## Your turn! 4/ Create a third code chunk. In this chunk, include the following visualisation: ```markdown ggplot(organisation_beta) + aes(salary, js_score) + geom_point() + geom_smooth(method = "lm") + theme_bw() + labs( x = "Employee Salary (Eur)", y = "Employee's Job Satisfaction" ) ``` 5/ Render the default document obtained to observe its structure
−
+
03
:
00
--- class: inverse, mline, center, middle # 6. Quarto Website Templates --- # Quarto Websites Quarto Websites are a convenient way to publish groups of documents. Documents published as part of a website share navigational elements, rendering options, and visual style. Website navigation can be provided through a global navbar, a sidebar with links, or a combination of both for sites that have multiple levels of content. You can also enable full text search for websites. <!-- --> --- class: title-slide, middle ## Your turn! 1/ In the Terminal window, run the following instructions: ```markdown quarto create project website mysite ``` and ```markdown quarto render mysite ``` 2/ Go to any `.qmd` file and click **Render** Note: If you proceed these instructions from your desktop, you need to install quarto first: https://quarto.org/ ]
−
+
03
:
00
--- # Quarto Websites ```markdown quarto create project website mysite ``` Creates a new website project from the Terminal. This website project is initiated by a folder called `mysite` located on the root of your terminal. -- The folder contains only 4 files: - `_quarto.yml` is a yaml file, it design the overall style and the navbar - `index.qmd` is a quarto file, it corresponds to the homepage - `about.qmd` is another quarto file which is displayed when about is clicked on the navbar - `styles.css` is for additional style not defined in `_quarto.yml` -- Improve your Website: - Navigation instructions here: https://quarto.org/docs/websites/website-navigation.html - Option instructions here: https://quarto.org/docs/reference/projects/websites.html --- # Quarto Websites ```markdown quarto render mysite ``` These commands are used to render the website by converting all the `.qmd` files to `.html` files stored in a `_site` folder. The website preview will open in a new web browser. As you edit and save `index.qmd` (or other files like `about.qmd`) the preview is automatically updated. <!-- --> --- class: title-slide, middle ## Your turn! 1/ Open the first file created `report.qmd`, change `format: pdf` to `format: html` and save it in the folder `mysite` 2/ Open the file `_quarto.yml` and modify it as follow: ```markdown website: title: "Mysite" navbar: left: - href: index.qmd text: Home - about.qmd - report.qmd ``` 4/ In the same Terminal window, run the following instructions: ```markdown quarto render mysite ``` 5/ Go to any `.qmd` file and click **Render**
−
+
10
:
00
--- class: inverse, mline, center, middle # 7. Publish this website on GitHub --- # Render the Website docs Folder In the `_quarto.yml` file, simply **change the output directory folder** to a folder named `docs` as follow: ```markdown project: type: website output-dir: docs ``` -- Then render the website: ```markdown quarto render mysite ``` -- .pull-left[ Your website default folder should look like that → Note: the old folder `_site` will not be used any more and is now useless. ] .pull-right[ <img src="https://raw.githubusercontent.com/damien-dupre/img/main/mysite_docs.png" width="80%" /> ] --- # Add a .nojekyll File Add a `.nojekyll` file to the root of your repository that tells GitHub Pages not to do additional processing of your published site using Jekyll (the GitHub default site generation tool): You can create an empty text file by yourself or you can download this `nojekyll` file here:
Click here to download nojekyll
--- # Upload your Files to GitHub Just drag and drop all the files in GitHub at once like this: <img src="https://raw.githubusercontent.com/damien-dupre/img/main/github_drop_mysite.gif" width="90%" /> --- class: title-slide, middle ## Your turn! .pull-left[ 1/ **Change the output directory folder** to a folder named `docs` in the `_quarto.yml` file: ```markdown project: type: website output-dir: docs ``` Then, preview or render the website ```markdown quarto render mysite ``` 2/ **Upload and commit all the files contained in the website folder** on your GitHub repository, not the website folder itself. ] .pull-right[ 3/ **Upload and commit a nojekyll file** that tells GitHub to not run its default html website processing You can download this `nojekyll` file here:
Click here to download nojekyll
4/ Finally, in **GitHub**, click **Settings** -> **Pages** choose: - `main` branch - `/docs` folder - and Save ]
−
+
10
:
00
--- class: inverse, mline, left, middle <img class="circle" src="https://github.com/damien-dupre.png" width="250px"/> # Thanks for your attention and don't hesitate to ask if you have any questions! [
@damien_dupre](http://twitter.com/damien_dupre) [
@damien-dupre](http://github.com/damien-dupre) [
damien-datasci-blog.netlify.app](https://damien-datasci-blog.netlify.app) [
damien.dupre@dcu.ie](mailto:damien.dupre@dcu.ie)