diff --git a/AEET_2025/exercises/callout-boxes.log b/AEET_2025/exercises/callout-boxes.log new file mode 100644 index 0000000..ac036fd --- /dev/null +++ b/AEET_2025/exercises/callout-boxes.log @@ -0,0 +1,30 @@ +This is XeTeX, Version 3.141592653-2.6-0.999994 (TeX Live 2022) (preloaded format=xelatex 2023.1.20) 31 MAY 2025 00:09 +entering extended mode + restricted \write18 enabled. + %&-line parsing enabled. +**callout-boxes.tex +(./callout-boxes.tex +LaTeX2e <2022-11-01> patch level 1 +L3 programming layer <2023-01-16> + +! LaTeX Error: File `scrartcl.cls' not found. + +Type X to quit or to proceed, +or enter new name. (Default extension: cls) + +Enter file name: +! Emergency stop. + + +l.10 ^^M + +Here is how much of TeX's memory you used: + 31 strings out of 478750 + 575 string characters out of 5848503 + 1841991 words of memory out of 5000000 + 20157 multiletter control sequences out of 15000+600000 + 512287 words of font info for 32 fonts, out of 8000000 for 9000 + 14 hyphenation exceptions out of 8191 + 19i,0n,29p,111b,17s stack positions out of 10000i,1000n,20000p,200000b,200000s + +No pages of output. diff --git a/AEET_2025/exercises/callout-boxes.qmd b/AEET_2025/exercises/callout-boxes.qmd index 2c2418d..cb47408 100644 --- a/AEET_2025/exercises/callout-boxes.qmd +++ b/AEET_2025/exercises/callout-boxes.qmd @@ -1,6 +1,6 @@ --- title: "Callout boxes" -format: html +format: pdf --- ::: callout-note diff --git a/AEET_2025/exercises/callout-boxes.tex b/AEET_2025/exercises/callout-boxes.tex new file mode 100644 index 0000000..aaa357e --- /dev/null +++ b/AEET_2025/exercises/callout-boxes.tex @@ -0,0 +1,187 @@ +% Options for packages loaded elsewhere +\PassOptionsToPackage{unicode}{hyperref} +\PassOptionsToPackage{hyphens}{url} +\PassOptionsToPackage{dvipsnames,svgnames,x11names}{xcolor} +% +\documentclass[ + letterpaper, + DIV=11, + numbers=noendperiod]{scrartcl} + +\usepackage{amsmath,amssymb} +\usepackage{iftex} +\ifPDFTeX + \usepackage[T1]{fontenc} + \usepackage[utf8]{inputenc} + \usepackage{textcomp} % provide euro and other symbols +\else % if luatex or xetex + \usepackage{unicode-math} + \defaultfontfeatures{Scale=MatchLowercase} + \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1} +\fi +\usepackage{lmodern} +\ifPDFTeX\else + % xetex/luatex font selection +\fi +% Use upquote if available, for straight quotes in verbatim environments +\IfFileExists{upquote.sty}{\usepackage{upquote}}{} +\IfFileExists{microtype.sty}{% use microtype if available + \usepackage[]{microtype} + \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts +}{} +\makeatletter +\@ifundefined{KOMAClassName}{% if non-KOMA class + \IfFileExists{parskip.sty}{% + \usepackage{parskip} + }{% else + \setlength{\parindent}{0pt} + \setlength{\parskip}{6pt plus 2pt minus 1pt}} +}{% if KOMA class + \KOMAoptions{parskip=half}} +\makeatother +\usepackage{xcolor} +\setlength{\emergencystretch}{3em} % prevent overfull lines +\setcounter{secnumdepth}{-\maxdimen} % remove section numbering +% Make \paragraph and \subparagraph free-standing +\ifx\paragraph\undefined\else + \let\oldparagraph\paragraph + \renewcommand{\paragraph}[1]{\oldparagraph{#1}\mbox{}} +\fi +\ifx\subparagraph\undefined\else + \let\oldsubparagraph\subparagraph + \renewcommand{\subparagraph}[1]{\oldsubparagraph{#1}\mbox{}} +\fi + + +\providecommand{\tightlist}{% + \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}\usepackage{longtable,booktabs,array} +\usepackage{calc} % for calculating minipage widths +% Correct order of tables after \paragraph or \subparagraph +\usepackage{etoolbox} +\makeatletter +\patchcmd\longtable{\par}{\if@noskipsec\mbox{}\fi\par}{}{} +\makeatother +% Allow footnotes in longtable head/foot +\IfFileExists{footnotehyper.sty}{\usepackage{footnotehyper}}{\usepackage{footnote}} +\makesavenoteenv{longtable} +\usepackage{graphicx} +\makeatletter +\def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth\else\Gin@nat@width\fi} +\def\maxheight{\ifdim\Gin@nat@height>\textheight\textheight\else\Gin@nat@height\fi} +\makeatother +% Scale images if necessary, so that they will not overflow the page +% margins by default, and it is still possible to overwrite the defaults +% using explicit options in \includegraphics[width, height, ...]{} +\setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio} +% Set default figure placement to htbp +\makeatletter +\def\fps@figure{htbp} +\makeatother + +\KOMAoption{captions}{tableheading} +\makeatletter +\@ifpackageloaded{tcolorbox}{}{\usepackage[skins,breakable]{tcolorbox}} +\@ifpackageloaded{fontawesome5}{}{\usepackage{fontawesome5}} +\definecolor{quarto-callout-color}{HTML}{909090} +\definecolor{quarto-callout-note-color}{HTML}{0758E5} +\definecolor{quarto-callout-important-color}{HTML}{CC1914} +\definecolor{quarto-callout-warning-color}{HTML}{EB9113} +\definecolor{quarto-callout-tip-color}{HTML}{00A047} +\definecolor{quarto-callout-caution-color}{HTML}{FC5300} +\definecolor{quarto-callout-color-frame}{HTML}{acacac} +\definecolor{quarto-callout-note-color-frame}{HTML}{4582ec} +\definecolor{quarto-callout-important-color-frame}{HTML}{d9534f} +\definecolor{quarto-callout-warning-color-frame}{HTML}{f0ad4e} +\definecolor{quarto-callout-tip-color-frame}{HTML}{02b875} +\definecolor{quarto-callout-caution-color-frame}{HTML}{fd7e14} +\makeatother +\makeatletter +\@ifpackageloaded{caption}{}{\usepackage{caption}} +\AtBeginDocument{% +\ifdefined\contentsname + \renewcommand*\contentsname{Table of contents} +\else + \newcommand\contentsname{Table of contents} +\fi +\ifdefined\listfigurename + \renewcommand*\listfigurename{List of Figures} +\else + \newcommand\listfigurename{List of Figures} +\fi +\ifdefined\listtablename + \renewcommand*\listtablename{List of Tables} +\else + \newcommand\listtablename{List of Tables} +\fi +\ifdefined\figurename + \renewcommand*\figurename{Figure} +\else + \newcommand\figurename{Figure} +\fi +\ifdefined\tablename + \renewcommand*\tablename{Table} +\else + \newcommand\tablename{Table} +\fi +} +\@ifpackageloaded{float}{}{\usepackage{float}} +\floatstyle{ruled} +\@ifundefined{c@chapter}{\newfloat{codelisting}{h}{lop}}{\newfloat{codelisting}{h}{lop}[chapter]} +\floatname{codelisting}{Listing} +\newcommand*\listoflistings{\listof{codelisting}{List of Listings}} +\makeatother +\makeatletter +\makeatother +\makeatletter +\@ifpackageloaded{caption}{}{\usepackage{caption}} +\@ifpackageloaded{subcaption}{}{\usepackage{subcaption}} +\makeatother +\ifLuaTeX + \usepackage{selnolig} % disable illegal ligatures +\fi +\usepackage{bookmark} + +\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available +\urlstyle{same} % disable monospaced font for URLs +\hypersetup{ + pdftitle={Callout boxes}, + colorlinks=true, + linkcolor={blue}, + filecolor={Maroon}, + citecolor={Blue}, + urlcolor={Blue}, + pdfcreator={LaTeX via pandoc}} + +\title{Callout boxes} +\author{} +\date{} + +\begin{document} +\maketitle + +\begin{tcolorbox}[enhanced jigsaw, coltitle=black, opacityback=0, toptitle=1mm, rightrule=.15mm, colback=white, colframe=quarto-callout-note-color-frame, breakable, left=2mm, opacitybacktitle=0.6, title=\textcolor{quarto-callout-note-color}{\faInfo}\hspace{0.5em}{Note}, colbacktitle=quarto-callout-note-color!10!white, bottomtitle=1mm, bottomrule=.15mm, arc=.35mm, titlerule=0mm, toprule=.15mm, leftrule=.75mm] + +Note that there are five types of callouts, including: \texttt{note}, +\texttt{warning}, \texttt{important}, \texttt{tip}, and +\texttt{caution}. + +\end{tcolorbox} + +\begin{tcolorbox}[enhanced jigsaw, coltitle=black, opacityback=0, toptitle=1mm, rightrule=.15mm, colback=white, colframe=quarto-callout-tip-color-frame, breakable, left=2mm, opacitybacktitle=0.6, title=\textcolor{quarto-callout-tip-color}{\faLightbulb}\hspace{0.5em}{Tip}, colbacktitle=quarto-callout-tip-color!10!white, bottomtitle=1mm, bottomrule=.15mm, arc=.35mm, titlerule=0mm, toprule=.15mm, leftrule=.75mm] + +This should be an example of a callout with a caption. So add a caption! + +\end{tcolorbox} + +\begin{tcolorbox}[enhanced jigsaw, coltitle=black, opacityback=0, toptitle=1mm, rightrule=.15mm, colback=white, colframe=quarto-callout-caution-color-frame, breakable, left=2mm, opacitybacktitle=0.6, title=\textcolor{quarto-callout-caution-color}{\faFire}\hspace{0.5em}{Expand To Learn About Collapse}, colbacktitle=quarto-callout-caution-color!10!white, bottomtitle=1mm, bottomrule=.15mm, arc=.35mm, titlerule=0mm, toprule=.15mm, leftrule=.75mm] + +This should be an example of a ``folded'' caution callout that can be +expanded by the user. You can use \texttt{collapse="true"} to collapse +it by default or \texttt{collapse="false"} to make a collapsible callout +that is expanded by default. Try adding these to attributes. + +\end{tcolorbox} + + + +\end{document} diff --git a/AEET_2025/exercises/markdown-syntax.qmd b/AEET_2025/exercises/markdown-syntax.qmd index ad6b349..0379442 100644 --- a/AEET_2025/exercises/markdown-syntax.qmd +++ b/AEET_2025/exercises/markdown-syntax.qmd @@ -9,4 +9,4 @@ format: html 3. Add an image link to a web image you have chosen and a local image. -4. Use any markdown syntax that you can recall from the slides or refresh your memory from . +4. Use any markdown syntax that you can recall from the document or refresh your memory from . diff --git a/AEET_2025/images/FINALdoc.png b/AEET_2025/images/FINALdoc.png new file mode 100644 index 0000000..ca85d7b Binary files /dev/null and b/AEET_2025/images/FINALdoc.png differ diff --git a/AEET_2025/images/Logo_ecoinf_10.jpg b/AEET_2025/images/Logo_ecoinf_10.jpg new file mode 100644 index 0000000..232c68a Binary files /dev/null and b/AEET_2025/images/Logo_ecoinf_10.jpg differ diff --git a/AEET_2025/images/RStudio.JPG b/AEET_2025/images/RStudio.JPG new file mode 100644 index 0000000..742897b Binary files /dev/null and b/AEET_2025/images/RStudio.JPG differ diff --git a/AEET_2025/images/UCM-Logo.png b/AEET_2025/images/UCM-Logo.png new file mode 100644 index 0000000..afc5f49 Binary files /dev/null and b/AEET_2025/images/UCM-Logo.png differ diff --git a/AEET_2025/images/advisor.png b/AEET_2025/images/advisor.png new file mode 100644 index 0000000..7da6e4a Binary files /dev/null and b/AEET_2025/images/advisor.png differ diff --git a/AEET_2025/images/arboles.jpg b/AEET_2025/images/arboles.jpg new file mode 100644 index 0000000..a30066d Binary files /dev/null and b/AEET_2025/images/arboles.jpg differ diff --git a/AEET_2025/images/cant_merge.png b/AEET_2025/images/cant_merge.png new file mode 100644 index 0000000..c127709 Binary files /dev/null and b/AEET_2025/images/cant_merge.png differ diff --git a/AEET_2025/images/cant_merge2.png b/AEET_2025/images/cant_merge2.png new file mode 100644 index 0000000..4c245bf Binary files /dev/null and b/AEET_2025/images/cant_merge2.png differ diff --git a/AEET_2025/images/cant_merge3.png b/AEET_2025/images/cant_merge3.png new file mode 100644 index 0000000..ef91112 Binary files /dev/null and b/AEET_2025/images/cant_merge3.png differ diff --git a/AEET_2025/images/climbing.png b/AEET_2025/images/climbing.png new file mode 100644 index 0000000..6a88551 Binary files /dev/null and b/AEET_2025/images/climbing.png differ diff --git a/AEET_2025/images/clipboard-1722222267.png b/AEET_2025/images/clipboard-1722222267.png new file mode 100644 index 0000000..527a0da Binary files /dev/null and b/AEET_2025/images/clipboard-1722222267.png differ diff --git a/AEET_2025/images/commit_RStudio.png b/AEET_2025/images/commit_RStudio.png new file mode 100644 index 0000000..7f9bb11 Binary files /dev/null and b/AEET_2025/images/commit_RStudio.png differ diff --git a/AEET_2025/images/conexiones.jpg b/AEET_2025/images/conexiones.jpg new file mode 100644 index 0000000..01bd696 Binary files /dev/null and b/AEET_2025/images/conexiones.jpg differ diff --git a/AEET_2025/images/drake_quarto.jpg b/AEET_2025/images/drake_quarto.jpg new file mode 100644 index 0000000..06dc0f7 Binary files /dev/null and b/AEET_2025/images/drake_quarto.jpg differ diff --git a/AEET_2025/images/git.jpg b/AEET_2025/images/git.jpg new file mode 100644 index 0000000..66796fe Binary files /dev/null and b/AEET_2025/images/git.jpg differ diff --git a/AEET_2025/images/git_RStudio.png b/AEET_2025/images/git_RStudio.png new file mode 100644 index 0000000..c3709f3 Binary files /dev/null and b/AEET_2025/images/git_RStudio.png differ diff --git a/AEET_2025/images/github_code.png b/AEET_2025/images/github_code.png new file mode 100644 index 0000000..5028cb0 Binary files /dev/null and b/AEET_2025/images/github_code.png differ diff --git a/AEET_2025/images/github_pag_ini.JPG b/AEET_2025/images/github_pag_ini.JPG new file mode 100644 index 0000000..3824ad5 Binary files /dev/null and b/AEET_2025/images/github_pag_ini.JPG differ diff --git a/AEET_2025/images/github_repositorio.JPG b/AEET_2025/images/github_repositorio.JPG new file mode 100644 index 0000000..7a7b590 Binary files /dev/null and b/AEET_2025/images/github_repositorio.JPG differ diff --git a/AEET_2025/images/github_repositorio2.JPG b/AEET_2025/images/github_repositorio2.JPG new file mode 100644 index 0000000..07edae7 Binary files /dev/null and b/AEET_2025/images/github_repositorio2.JPG differ diff --git a/AEET_2025/images/hist.jpg b/AEET_2025/images/hist.jpg new file mode 100644 index 0000000..7c0f28b Binary files /dev/null and b/AEET_2025/images/hist.jpg differ diff --git a/AEET_2025/images/in_case_of_fire.png b/AEET_2025/images/in_case_of_fire.png new file mode 100644 index 0000000..fb432f1 Binary files /dev/null and b/AEET_2025/images/in_case_of_fire.png differ diff --git a/AEET_2025/images/merge.jpg b/AEET_2025/images/merge.jpg new file mode 100644 index 0000000..f84e485 Binary files /dev/null and b/AEET_2025/images/merge.jpg differ diff --git a/AEET_2025/images/pullrequest1.1.jpg b/AEET_2025/images/pullrequest1.1.jpg new file mode 100644 index 0000000..1fa54c3 Binary files /dev/null and b/AEET_2025/images/pullrequest1.1.jpg differ diff --git a/AEET_2025/images/pullrequest1.jpg b/AEET_2025/images/pullrequest1.jpg new file mode 100644 index 0000000..9c1c674 Binary files /dev/null and b/AEET_2025/images/pullrequest1.jpg differ diff --git a/AEET_2025/images/pullrequest2.jpg b/AEET_2025/images/pullrequest2.jpg new file mode 100644 index 0000000..2f96c79 Binary files /dev/null and b/AEET_2025/images/pullrequest2.jpg differ diff --git a/AEET_2025/images/pullrequest3.1.jpg b/AEET_2025/images/pullrequest3.1.jpg new file mode 100644 index 0000000..4a7ddb9 Binary files /dev/null and b/AEET_2025/images/pullrequest3.1.jpg differ diff --git a/AEET_2025/images/pullrequest3.jpg b/AEET_2025/images/pullrequest3.jpg new file mode 100644 index 0000000..27a1b4c Binary files /dev/null and b/AEET_2025/images/pullrequest3.jpg differ diff --git a/AEET_2025/images/quarto_render.jpg b/AEET_2025/images/quarto_render.jpg new file mode 100644 index 0000000..1ee5550 Binary files /dev/null and b/AEET_2025/images/quarto_render.jpg differ diff --git a/AEET_2025/images/ralph_learning.jpg b/AEET_2025/images/ralph_learning.jpg new file mode 100644 index 0000000..61ec153 Binary files /dev/null and b/AEET_2025/images/ralph_learning.jpg differ diff --git a/AEET_2025/images/ramas.png b/AEET_2025/images/ramas.png new file mode 100644 index 0000000..b9e4ed6 Binary files /dev/null and b/AEET_2025/images/ramas.png differ diff --git a/AEET_2025/images/rmarkdown.png b/AEET_2025/images/rmarkdown.png new file mode 100644 index 0000000..e46e3b6 Binary files /dev/null and b/AEET_2025/images/rmarkdown.png differ diff --git a/AEET_2025/images/terminal.png b/AEET_2025/images/terminal.png new file mode 100644 index 0000000..9b611f9 Binary files /dev/null and b/AEET_2025/images/terminal.png differ diff --git a/AEET_2025/images/tracker.png b/AEET_2025/images/tracker.png new file mode 100644 index 0000000..7c3d7d2 Binary files /dev/null and b/AEET_2025/images/tracker.png differ diff --git a/AEET_2025/images/workflow_git_github.jpg b/AEET_2025/images/workflow_git_github.jpg new file mode 100644 index 0000000..acc07d0 Binary files /dev/null and b/AEET_2025/images/workflow_git_github.jpg differ diff --git a/AEET_2025/intro_qmd_en.qmd b/AEET_2025/intro_qmd_en.qmd deleted file mode 100644 index 65eea22..0000000 --- a/AEET_2025/intro_qmd_en.qmd +++ /dev/null @@ -1,1283 +0,0 @@ ---- -title: "Intro Quarto Elena" -format: html ---- - -This part of the course is designed to provide an introduction to **Quarto**, a modern, open-source scientific and technical publishing system. Participants will learn the basics of creating dynamic documents, integrating code and text, and producing reproducible reports in multiple formats. - -In addition to learning how to use Quarto, this section will also cover some essential first steps for practicing **reproducible research**, including the importance of literate programming, documenting analysis workflows, and properly licensing and sharing materials. - -Some of the materials and ideas included here are inspired by openly available resources shared under Creative Commons licenses. - -Specifically, parts of this course draw inspiration from: - -- **Casajus et al. (2021)**: *Data Toolbox for Reproducible Research in Computational Ecology*. [Zenodo DOI](https://doi.org/10.5281/zenodo.4262978) -- The *"Reproducible publishing with Quarto"* short course by [Mine Çetinkaya-Rundel](https://mine-cetinkaya-rundel.github.io/quarto-jsm24/) at JSM 2024. - -## Quarto - -### What is Quarto - -Quarto is a dynamic document publishing system that allows you to create reports, books, manuscripts, presentations, and websites. It is a very versatile tool that supports multiple programming languages (R, Python, Julia, etc.) and output formats (HTML, PDF, Word, etc.). Quarto is based on R Markdown but offers a number of improvements and new features that make it more powerful and flexible. It can be used in different workspaces (e.g., RStudio, Jupyter) and has a visual editing interface in RStudio. - -![Figure from jthomasmock.github.io/quarto-2hr-webinar](images/qmd-universe.png) - -### Why use Quarto - -Quarto is an ideal tool for creating *reproducible scientific documents* and for *collaborative work*. It allows you to integrate code, text, and results into a **single document**, making it easier to produce scientific reports and publications. In addition, Quarto is **compatible with Git and GitHub**, enabling version control and efficient collaboration with others. - -![](images/visual-editing-toolbar.png) - -![](images/visual-rstudio.png) - -### Brief history: Evolution from R Markdown - -Quarto () began as an open-source project in 2021 by Posit Software (formerly RStudio) and is based on over 10 years of experience with R Markdown. Quarto functions as an open-source scientific and technical publishing system built on top of **Pandoc** (). It converts plain text formats (e.g., .md, .Rmd) or mixed formats (e.g., .ipynb) into static reports and more. It can interweave narrative text and code to produce elegantly formatted results in the form of documents, web pages, blog posts, books, and so on. - -The Quarto file extension is .qmd, and it uses Lua filters, which is Pandoc’s extension language (). To do this, Quarto uses an engine like knitr to execute the code and generate a temporary .md output. The .md file is then processed by Pandoc and Quarto’s Lua filters, plus Bootstrap CSS for HTML or LaTeX for PDF. Lua filters written by R/Python/Julia developers should be interchangeable between formats — they are typically not language-specific. - -![Diagram of how Quarto works. Figure from \](images/qmd-knitr.jpeg) - -### Quarto installation - -Quarto comes pre-installed with the latest versions of RStudio (v2022.07 and later). However, if you want to use it in other interfaces as well, you can follow the installation instructions on the official website: . - -To use Quarto from within R, you need to have the rmarkdown package installed: - -``` r -#|eval: false -install.packages("rmarkdown") -``` - -You can also verify the Quarto installation and its location with the following command: - -``` r -#|eval: false -quarto::quarto_path() -``` - -### Key differences between R Markdown and Quarto - -The main difference between Quarto and R Markdown is that Quarto was designed for collaboration across multiple communities (i.e., not just R or Python users) and uses a shared syntax and format across different languages. Additionally, as more capabilities were added to R Markdown through external R packages, the syntax for basic tasks became inconsistent. Some differences between Quarto and R Markdown in terms of code are:Diferencias clave entre R Markdown y Quarto - -- **YAML structure -** both follow `key: value` but Quarto is more flexible and nested - -- **code chunk header syntax -** `#|` syntaxis *(hash pipe)*. This is the preferred syntax in Quarto, although it is compatible with the older R Markdown syntax. The hash pipe adds more consistency across engines (Jupyter, knitr) and gives us more control over the order and spacing of chunk options (it’s not limited to a single line of options). Each #\| line is interpreted as a key: value pair. - -Enhanced tab completion: start typing a word and press Tab to auto-complete, or use Ctrl + Space to view all available options. - -```{r} -#| label: example -#| echo: true -2 * 2 -``` - -### Why use Quarto instead of R Markdown? - -- Shared syntax (choose your preferred editor and language) -- Greater versatility -- Better features and further improvements in the future (R Markdown is still maintained, but most new features will be incorporated into Quarto) - -### What should I do with my existing `.Rmd` files? - -No problem! Most existing `.Rmd` or .`ipynb` files can be converted as-is using Quarto. To do this from the terminal command line, type: - -`quarto render file.Rmd --to html` - -Additionally, there are various options for converting `.Rmd` files to `.qmd`: - -1. Rename `.Rmd` to `.qmd` (this will always use Quarto for rendering) -2. Update the YAML output: change html_document to format: html -3. Use the R function: `knitr::convert_chunk_header("file.Rmd", "file.qmd")` - -You don’t have to convert the syntax of all your old documents. Quarto is backward compatible with R Markdown. - -### Getting started with Quarto - -![](images/hello_quarto.png) - -::: {.your-turn style="background: lightblue"} -**📝 Your turn** - -### Creating a Quarto document - -To create a Quarto document in RStudio, follow these steps: - -1. In RStudio, go to File → New File → Quarto Document - -2. A window will open where you can choose the type of document you want to create (for example, a report, a presentation, etc.). - -3. Select the type you want and click OK. A file with the extension `.qmd` (Quarto Markdown) will be created, containing a basic document structure. -::: - -### Quarto workflow - -Rendering a Quarto file in RStudio via the Render button calls `quarto render` in a **background job**, preventing Quarto rendering from cluttering up the R console, and gives you and easy way to stop: - -#### Rendering - -1. Option 1: In RStudio as a background job, and preview the output. - -2. Option 2: In the Terminal via `quarto render`: - -```{bash} -#| eval: false -#| echo: true - -quarto render document.qmd # defaults to html -quarto render document.qmd --to pdf -quarto render document.qmd --to docx -``` - -3. Option 3: In the R console, via the `quarto` R package: - -```{r} -#| eval: false -#| echo: true - -library(quarto) - -quarto_render("document.qmd") # defaults to html -quarto_render("document.qmd", output_format = "pdf") -``` - -::: {.your-turn style="background: lightblue"} -**📝 Your turn** - -- Open `hello-penguins.qmd`. -- Render the document. -- Update your name and re-render. -- Inspect components of the document and make one more update and re-render. -- Compare behavior of rendering with - - RStudio \> Render, - - using the CLI with `quarto render`, and - - in the R console via `quarto::quarto_render()`. -- If you're an RStudio user, brainstorm why you might still want to know about the other two ways of rendering Quarto documents. -::: - -### Anatomy of a Quarto document {#quarto-anatomy} - -It contains three types of content: - -1. Metadata: YAML header surrounded by ---s. - -2. Markdown. Text mixed with simple text formatting like \## heading, **bolds** and *italics*. - -3. Code: Executed via `knitr` or `jupyter` - -**Weave it all together**, and you have beautiful, powerful, and useful outputs! - -::: columns -```{bash} -#| eval: false -#| echo: true -#| code-line-numbers: "|1-6|8-15|17-29|" - ---- -title: "Hello, Penguins" -format: html -execute: - echo: false ---- - -## Meet the penguins - -The __penguins__ data contains size measurements for -penguins from three islands in the Palmer Archipelago, -Antarctica. - -The _three_ species of penguins have quite distinct -distributions of physical dimensions (@fig-penguins). - -#| label: fig-penguins -#| fig-cap: "Dimensions of penguins across three species." -#| warning: false -library(tidyverse, quietly = TRUE) -library(palmerpenguins) -penguins |> - ggplot(aes(x = flipper_length_mm, y = bill_length_mm)) + - geom_point(aes(color = species)) + - scale_color_manual( - values = c("darkorange", "purple", "cyan4")) + - theme_minimal() - -``` - -::: {.column .center width="40%"} -![](images/penguins_render.png) -::: -::: - -#### 1. YAML header - -The YAML header is demarcated by three dashes (---) on either end. It informs on some documents meta-data and sets up many generic and output format specific options. The YAML consists of `key: values` pairs. The **colon** and **space** are **required**. - -YAML header can be very simple - -"Yet Another Markup Language" or "YAML Ain't Markup Language" is used to provide document level metadata. - -```{bash} -#| eval: false -#| echo: true - ---- -title: "Hello, Penguins" -format: html -execute: - echo: false ---- - -``` - -The YAML header is demarcated by three dashes (---) on either end. It informs on some documents meta-data and sets up many generic and output format specific options. The YAML consists of `key: values` pairs. The **colon** and **space** are **required**. - -As well as much more elaborated, e.g. when [scholarly writing](https://quarto.org/docs/authoring/front-matter.html) - -```{bash} -#| eval: false -#| echo: true - ---- -title: "Toward a Unified Theory of High-Energy Metaphysics: Silly String Theory" -date: 2008-02-29 -author: - - name: Josiah Carberry - id: jc - orcid: 0000-0002-1825-0097 - email: josiah@psychoceramics.org - affiliation: - - name: Brown University - city: Providence - state: RI - url: www.brown.edu -abstract: > - The characteristic theme of the works of Stone is - the bridge between culture and society. ... -keywords: - - Metaphysics - - String Theory -license: "CC BY" -copyright: - holder: Josiah Carberry - year: 2008 -citation: - container-title: Journal of Psychoceramics - volume: 1 - issue: 1 - doi: 10.5555/12345678 -funding: "The author received no specific funding for this work." ---- - -``` - -YAML headers can operate at the document level to manage execute options: - -```{bash} -#| eval: false -#| echo: true -#| code-line-numbers: "|8|" - ---- -title: "Hello, Penguins" -subtitle: "Penguins are vertebrates" -execute: - echo: false - eval: true - warning: false - error: true ---- - -``` - -Or can set format specific options (here for html output): - -```{bash} -#| eval: false -#| echo: true -#| code-line-numbers: "|7-8|" - ---- -title: "Hello, Penguins" -subtitle: "Penguins are vertebrates" -format: - html: - theme: united - code-fold: true - code-summary: "see the code" -execute: - echo: true - eval: true - warning: false - error: true ---- - -``` - -All format specific options are listed in the [`Quarto` official documentation](https://quarto.org/docs/reference/). - -**YAML Intelligence**: YAML code completion is available for project files, YAML front matter, and executable cell options: - -![](images/rstudio-yaml-completion.png){width="400" fig-align="center"} - -If you have incorrect YAML it will also be highlighted when documents are saved: - -![](images/rstudio-yaml-diagnostics.png){width="400" fig-align="center"} - -``` yaml ---- -key: value ---- -``` - -##### Output options - -``` yaml ---- -format: something ---- -``` - -``` yaml ---- -format: html ---- -``` - -``` yaml ---- -format: pdf ---- -``` - -``` yaml ---- -format: revealjs ---- -``` - -Indentation matters! - -``` yaml ---- -format: - html: - toc: true - code-fold: true ---- -``` - -##### YAML validation {.smaller} - -- Invalid: No space after `:` - -``` yaml ---- -format:html ---- -``` - -- Invalid: Read as missing - -``` yaml ---- -format: -html ---- -``` - -- Valid, but needs next object - -``` yaml ---- -format: - html: ---- -``` - -There are multiple ways of formatting valid YAML: - -- Valid: There's a space after `:` - -``` yaml -format: html -``` - -- Valid: There are 2 spaces a new line and no trailing `:` - -``` yaml -format: - html -``` - -- Valid: `format: html` with selections made with proper indentation - -``` yaml -format: - html: - toc: true -``` - -##### Why YAML? - -To avoid manually typing out all the options, every time when rendering via the CLI: - -``` bash -quarto render document.qmd --to html -``` - -``` bash -quarto render document.qmd --to html -M code-fold:true -``` - -``` bash -quarto render document.qmd --to html -M code-fold:true -P alpha:0.2 -P ratio:0.3 -``` - -::: {.your-turn style="background: lightblue"} -**📝 Your turn** - -Open `hello-penguins.qmd` in RStudio. - -- Try `Ctrl + space` to see the available YAML options. -- Try out the tab-completion of any options you remember. -- You can use the [HTML reference](https://quarto.org/docs/reference/formats/html.html) as needed. -::: - -##### List of valid YAML fields - -- Many YAML fields are common across various outputs - -- But also each output type has its own set of valid YAML fields and options - -- Definitive list: [quarto.org/docs/reference/formats/html](https://quarto.org/docs/reference/formats/html.html) - -#### 2. Markdown - -The markdown you know from R Markdown will work in Quarto. - -Quarto is based on Pandoc and uses its variation of markdown as its underlying document syntax. Pandoc markdown is an extended and slightly revised version of John Gruber’s [Markdown](https://daringfireball.net/projects/markdown/) syntax. - -Markdown is a plain text format that is designed to be easy to write, and, even more importantly, easy to read: - -> A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. – John Gruber - -##### Text Formatting - -+-----------------------------------+-----------------------------------+ -| Markdown Syntax | Output | -+===================================+===================================+ -| ``` | *italics* and **bold** | -| *italics* and **bold** | | -| ``` | | -+-----------------------------------+-----------------------------------+ -| ``` | superscript^2^ / subscript~2~ | -| superscript^2^ / subscript~2~ | | -| ``` | | -+-----------------------------------+-----------------------------------+ -| ``` | ~~strikethrough~~ | -| ~~strikethrough~~ | | -| ``` | | -+-----------------------------------+-----------------------------------+ -| ``` | `verbatim code` | -| `verbatim code` | | -| ``` | | -+-----------------------------------+-----------------------------------+ - -: {tbl-colwidths="\[50,50\]"} - -##### Headings {.smaller} - -+-----------------------------------+-----------------------------------+ -| Markdown Syntax | Output | -+===================================+===================================+ -| ``` | # Header 1 | -| # Header 1 | | -| ``` | | -+-----------------------------------+-----------------------------------+ -| ``` | ## Header 2 | -| ## Header 2 | | -| ``` | | -+-----------------------------------+-----------------------------------+ -| ``` | ### Header 3 | -| ### Header 3 | | -| ``` | | -+-----------------------------------+-----------------------------------+ -| ``` | #### Header 4 | -| #### Header 4 | | -| ``` | | -+-----------------------------------+-----------------------------------+ -| ``` | ##### Header 5 | -| ##### Header 5 | | -| ``` | | -+-----------------------------------+-----------------------------------+ -| ``` | ###### Header 6 | -| ###### Header 6 | | -| ``` | | -+-----------------------------------+-----------------------------------+ - -: {tbl-colwidths="\[50,50\]"} - -##### Links {.smaller} - -There are several types of "links" or hyperlinks. - -**Markdown** - -``` {.markdown .code-overflow-wrap} -You can embed [named hyperlinks](https://quarto.org/), -direct urls like https://quarto.org/, and links to -[other places](#quarto-anatomy) in -the document. - -The syntax is similar for embedding an -inline image: ![Penguins playing with ball](images/penguins-quarto-ball.png). -``` - -**Output** - -You can embed [named hyperlinks](https://quarto.org/), direct urls like , and links to [other places](#quarto-anatomy) in the document. - -The syntax is similar for embedding an inline image: ![Penguins playing with ball](images/penguins-quarto-ball.png){alt="Penguins playing with ball" style="width:250px;"}. - -##### Lists {.smaller} - -Unordered list: - -::: columns -::: {.column width="50%"} -**Markdown:** - -``` markdown -- unordered list - - sub-item 1 - - sub-item 1 - - sub-sub-item 1 -``` -::: - -::: {.column .fragment width="50%" fragment-index="1"} -**Output** - -- unordered list - - sub-item 1 - - sub-item 1 - - sub-sub-item 1 -::: -::: - -Ordered list: - -::: columns -::: {.column width="50%"} -**Markdown:** - -``` markdown -1. ordered list -2. item 2 - i. sub-item 1 - A. sub-sub-item 1 -``` -::: - -::: {.column .fragment width="50%" fragment-index="2"} -**Output** - -1. ordered list -2. item 2 - i. sub-item 1 - A. sub-sub-item 1 -::: -::: - -##### Quotes - -**Markdown:** - -``` markdown -> Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. -> - Donald Knuth, Literate Programming -``` - -**Output:** - -> Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. - Donald Knuth, Literate Programming - -::: aside -"Literate Programming", The Computer Journal 27 (1984), p. 97. (Reprinted in Literate Programming, 1992, p. 99.) Literate Programming (1984) -::: - -Rstudio's visual editor toolbar includes buttons for the most commonly used formatting commands: - -![](https://quarto.org/docs/visual-editor/images/visual-editing-toolbar.png){fig-alt="A snippet of an RStudio window showing the options bar at the top of an RMarkdown document."} - -Additional commands are available on the **Format**, **Insert**, and **Table** menus: - -+-----------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| Format | Insert | Table | -+:=============================================================================================:+:=============================================================================================:+:============================================================================================:+ -| ![](https://quarto.org/docs/visual-editor/images/visual-editing-format-menu.png){width="60%"} | ![](https://quarto.org/docs/visual-editor/images/visual-editing-insert-menu.png){width="60%"} | ![](https://quarto.org/docs/visual-editor/images/visual-editing-table-menu.png){width="60%"} | -+-----------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ - -Rstudio's visual editor toolbar includes buttons for the most commonly used formatting commands: - -![](https://quarto.org/docs/visual-editor/images/visual-editing-toolbar.png){fig-alt="A snippet of an RStudio window showing the options bar at the top of an RMarkdown document."} - -Check out the `Quarto` official documentation to learn more about visual markdown editing: - -- [Technical Writing](https://quarto.org/docs/visual-editor/technical.html) covers features commonly used in scientific and technical writing, including citations, cross-references, footnotes, equations, embedded code, and LaTeX. - -- [Content Editing](https://quarto.org/docs/visual-editor/content.html) provides more depth on visual editor support for tables, lists, pandoc attributes, CSS styles, comments, symbols/emojis, etc. - -- [Shortcuts & Options](https://quarto.org/docs/visual-editor/options.html) documents the two types of shortcuts you can use with the editor: standard keyboard shortcuts and markdown shortcuts and describes various options for configuring the editor. - -- [Markdown Output](https://quarto.org/docs/visual-editor/markdown.html) describes how the visual editor parses and writes markdown and describes various ways you can customize this. - -A complete guide to `Quarto` authoring is available in the [official documentation](https://quarto.org/docs/authoring). - -::: {.your-turn style="background: lightblue"} -**📝 Your turn** - -- Skim the previous content. Share one new that's new to you with your neighbor. -- Open `markdown-syntax.qmd` in RStudio. -- Follow the instructions in the document. -::: - -##### Divs and spans {.smaller} - -Pandoc, and therefore Quarto, can parse ["fenced div blocks"](https://pandoc.org/MANUAL.html#divs-and-spans): - -- You can think of a `:::` **div** as a HTML `
` but it can also apply in specific situations to content in PDF: - -``` markdown -::: {style="border-left:10px solid red"} -This content can be styled with a border -::: -``` - -::: {style="border-left:10px solid red"} -This content can be styled with a border -::: - -. . . - -- `[text]{.class}` **span**s can be thought of a `Text` but again are a bit more transferable if using Pandoc/Quarto native attributes. - -``` markdown -This is text with [special]{style="color:red;"} formatting. -``` - -This is text with [special]{style="color:red;"} formatting. - -##### Divs with pre-defined classes - -These can often apply between formats: - -**Single class**: Two equivalent syntaxes - -::: columns -::: column -No `{`, and no `.`: - -``` markdown -::: unnumbered -Text -::: -``` -::: - -::: column -`{` and `.`: - -``` markdown -::: {.unnumbered} -Text -::: -``` -::: -::: - -**Multiple classes**: use `{` and `.`, separate with spaces - -``` markdown -::: {.unnumbered .unlisted} -Text -::: -``` - -##### Callouts - -``` -::: callout-note -Note that there are five types of callouts, including: -`note`, `tip`, `warning`, `caution`, and `important`. -::: -``` - -Note that there are five types of callouts, including: `note`, `tip`, `warning`, `caution`, and `important`. - -##### More callouts - -::: callout-warning -Callouts provide a simple way to attract attention, for example, to this warning. -::: - -::: callout-important -Danger, callouts will really improve your writing. -::: - -::: callout-caution -Here is something under construction. -::: - -::: callout-tip -### Caption - -Tip with caption. -::: - -::: your-turn -::: {style="background: lightblue"} -**📝 Your turn** -::: - -Open `callout-boxes.qmd` and render the document. - -- Using the visual editor, change the type of the first callouts box and then re-render. Also play with the options to change its appearance. -- Add a caption to the second callout box. -- Make the third callout box collapsible. Then, switch over to the source editor to inspect the markdown code. -- Change the format to PDF and re-render. -::: - -##### Footnotes - -Pandoc supports numbering and formatting footnotes. - -###### Inline footnotes - -``` -Here is an inline note.^[Inlines notes are easier to write, -since you don't have to pick an identifier and move down to -type the note.] -``` - -Here is an inline note.[^1] - -[^1]: Inlines notes are easier to write, since you don't have to pick an identifier and move down to type the note. - -``` -Here is an footnore reference[^1] - -[^1]: This can be easy in some situations when you have a really long note or -don't want to inline complex outputs. -``` - -Here is an footnote reference[^2] - -[^2]: This can be easy in some situations when you have a really long note or don't want to inline complex outputs. - -Notice in both situations that the footnote is placed at the bottom of the page in presentations, whereas in a document it would be hoverable or at the end of the document. - -### Tables and figures - -- In reproducible reports and manuscripts, the most commonly included code outputs are **tables** and **figures**. - -- So they get their own special sections! - -#### Tables - -**Markdown:** - -``` markdown -| Right | Left | Default | Center | -|------:|:-----|---------|:------:| -| 12 | 12 | 12 | 12 | -| 123 | 123 | 123 | 123 | -| 1 | 1 | 1 | 1 | -``` - -**Output:** - -| Right | Left | Default | Center | -|------:|:-----|---------|:------:| -| 12 | 12 | 12 | 12 | -| 123 | 123 | 123 | 123 | -| 1 | 1 | 1 | 1 | - -: Grid tables - -**Markdown:** - -``` markdown -+----------------------+------------+-------------------------------+ -| Variable | Valor | Ventajas | -+======================+============+===============================+ -| Café_consumido | 12 tazas | - mantiene vivo al investigador | -| | | - mejora los plots | -+----------------------+------------+-------------------------------+ -| R_script_rotura | 3 veces | - fomenta trabajo en equipo | -| | | - excusa para otra ronda | -+----------------------+------------+-------------------------------+ -| GPS_marmotas | 7 activos | - datos en tiempo real | -| | | - posible reality show | -+----------------------+------------+-------------------------------+ -| Bicho_raro_observado | 2 | - oportunidad de nuevo paper | -| | | - nombre gracioso asegurado | -+----------------------+------------+-------------------------------+ - - -: Sample grid table. -``` - -**Output:** - -+----------------------+-------------+----------------------------------------------------------------+ -| Variable | Valor | Ventajas | -+:=====================+:============+:===============================================================+ -| Café_consumido | 12 tazas | \- mantiene vivo al investigador
- mejora los plots | -+----------------------+-------------+----------------------------------------------------------------+ -| R_script_rotura | 3 veces | \- fomenta trabajo en equipo
- excusa para otra ronda | -+----------------------+-------------+----------------------------------------------------------------+ -| GPS_marmotas | 7 activos | \- datos en tiempo real
- posible reality show | -+----------------------+-------------+----------------------------------------------------------------+ -| Bicho_raro_observado | 2 | \- oportunidad de nuevo paper
- nombre gracioso asegurado | -+----------------------+-------------+----------------------------------------------------------------+ - -#### Grid tables: Alignment - -- Alignments can be specified as with pipe tables, by putting colons at the boundaries of the separator line after the header: - -``` -+---------------+---------------+--------------------+ -| Right | Left | Centered | -+==============:+:==============+:==================:+ -| Bananas | $1.34 | built-in wrapper | -+---------------+---------------+--------------------+ -``` - -. . . - -- For headerless tables, the colons go on the top line instead: - -``` -+--------------:+:--------------+:------------------:+ -| Right | Left | Centered | -+---------------+---------------+--------------------+ -``` - -#### Grid tables: Authoring - -- Note that grid tables are quite awkward to write with a plain text editor because unlike pipe tables, the column indicators must align. - -- The Visual Editor can assist in making these tables! - -### Tables from code {.smaller} - -The **knitr** package can turn data frames into tables with `knitr::kable()`: - -```{r} -library(knitr) -library(palmerpenguins) - -head(penguins) |> - kable() -``` - -If you want fancier tables, try the **gt** package and [all that it offers](https://gt.rstudio.com/)! - -```{r} -#| output-location: column-fragment - -library(gt) - -head(penguins) |> - gt() |> - tab_style( - style = list( - cell_fill(color = "pink"), - cell_text(style = "italic") - ), - locations = cells_body( - columns = bill_length_mm, - rows = bill_length_mm > 40 - ) - ) -``` - -## Figures - -### Markdown figures - -``` -![Penguins playing with a Quarto ball](images/penguins-quarto-ball.png) -``` - -![Penguins playing with a Quarto ball](images/penguins-quarto-ball.png) - -### Markdown figures with options - -::: columns -::: {.column width="50%"} -``` -![Penguins playing with a Quarto ball](images/penguins-quarto-ball.png){fig-align="left"} -``` - -![](images/penguins-quarto-ball.png) -::: - -::: {.column width="50%"} -``` -![](images/penguins-quarto-ball.png){fig-align="right" fig-alt="Illustration of two penguins playing with a Quarto ball."} -``` - -![](images/penguins-quarto-ball.png){fig-align="right" fig-alt="Illustration of two penguins playing with a Quarto ball."} -::: -::: - -### Subfigures - -**Markdown:** - -``` -::: {#fig-penguins layout-ncol=2} - -![Blue penguin](images/blue-penguin.png){#fig-blue width="250px"} - -![Orange penguin](images/orange-penguin.png){#fig-orange width="250px"} - -Two penguins - -::: -``` - -**Output:** - -::: {#fig-penguins layout-ncol="2"} -![Blue penguin](images/blue-penguin.png){#fig-blue width="250px"} - -![Orange penguin](images/orange-penguin.png){#fig-sleep width="250px"} - -Two penguins -::: - -### Figure divs - -**Markdown:** - -``` code -::: {#fig-penguin} - - - -Baby penguin tries to make friends -::: - -Last paragraph in the div block is used as the figure caption. - -### Finding the figures to include - -In places like markdown, YAML, or the command line/shell/terminal, you'll need to use **absolute** or **relative** file paths: - -. . . - -- Absolute = BAD: `"/Users/mine/quarto-asa-nebraska"` - Whose computer will this work on? - -. . . - -- Relative = BETTER: - - - `"../` = up one directory, `../../` = up two directories, etc. - - `/..` or `/` = start from `root` directory of your current computer - -### Figures from code - -```{r} -#| fig-width: 6 -#| fig-asp: 0.618 -#| echo: fenced - -library(ggplot2) - -ggplot(penguins, aes(x = species, fill = species)) + - geom_bar(show.legend = FALSE) -``` - -::: {.your-turn style="background: lightblue"} -**📝 Your turn** - -- Open `tables-figures.qmd`. -- Follow the instructions in the document, then exchange one new thing you've learned with your neighbor. -::: - -## Cross references - -> Quarto cross references provide automatic numbering and reference creation for figures, tables, equations, sections, listings, theorems, and proofs. In books, cross references work the same way except they can reach across chapters. - -You can cross reference almost everything : [figures]{.green}, [tables]{.yellow}, [equations]{.purple}, [sections]{.cyan}, ... - -Cross reference identifiers - -To reference an item later we need an identifier for it. - -Identifiers must start with the type of the item: - -- figures: fig- - -- tables: tbl- - -- equations: eq- - -- section: sec- - -Check reserved/appropriate prefixes at the [official documentation](https://quarto.org/docs/authoring/cross-references.html). - -### **Figures** - -**Markdown:** - -``` -![Programmer meme](images/programmer.jpeg){#fig-programmer fig-align="center"} -``` - -![Programmer meme](images/programmer.jpeg){#fig-programmer fig-align="center"} - -See @fig-programmer for an illustration. - -### Tables - -```{r} -#| label: tbl-penguins -#| tbl-cap: "Penguin bill lengths over 40 mm are highlighted." -library(gt) -library(palmerpenguins) - -head(penguins) |> - gt() |> - tab_style( - style = list( - cell_fill(color = "lightblue"), - cell_text(style = "italic") - ), - locations = cells_body( - columns = bill_length_mm, - rows = bill_length_mm < 37 - ) - ) - -``` - -And here we reference it again: @tbl-penguins shows how longer bills get a pink highlight. - -### Equations - -Provide an #eq- label immediately after an equation to make it referenceable. For example: - -The AEET Conference coffee consumption model - -```{bash} -#| eval: false -#| echo: true - -$$ -\frac{\partial C}{\partial t} + \frac{1}{2}\alpha^2 E^2 -\frac{\partial^2 C}{\partial A^2} -+ \beta T \frac{\partial C}{\partial A} = -\gamma C -$$ {#eq-eco-coffee} - -``` - -::: fragment -As shown in Equation @eq-eco-coffee, coffee consumption increases quadratically with talk excitement and linearly with tweet rate — until supplies run out or the poster session begins: - -$$ -\frac{\partial C}{\partial t} + \frac{1}{2}\alpha^2 E^2 -\frac{\partial^2 C}{\partial A^2} -+ \beta T \frac{\partial C}{\partial A} = -\gamma C -$$ {#eq-eco-coffee} -::: - -Where: $C$ = Coffee consumption rate (cups per minute) $t$ = Time since the first plenary session (minutes) $E$ = Talk excitement level (log-scale of standing ovations) $A$ = Coffee availability (cups remaining) $T$ = Tweet rate about the talk (tweets per minute) $\alpha, \beta, \gamma$ = Ecological conference constants empirically calibrated at multiple symposia - -As always, check the [official documentation](https://quarto.org/docs/authoring/cross-references.html). - -### Citations - -Quarto uses Pandoc to automatically format in text citations and create a reference list properly styled. You'll need: - -- A quarto document formatted with citations (see next slide). - -- A bibliographic data source, for example a BibLaTeX (.bib) or BibTeX (.bibtex) file. This can be automatically generated when using the visual `Quarto` editor. - -- Optionally, a CSL file which specifies the formatting to use when generating the citations and bibliography. - -::: fragment -#### Bibliography Files - -Quarto supports bibliography files in a wide variety of formats including BibLaTeX and CSL. Add a bibliography to your document using the bibliography YAML metadata field. For example: - -```{bash} -#| eval: false -#| echo: true -#| code-line-numbers: "|3" - ---- -title: "AEET 2025 talk" -bibliography: references.bib ---- - -``` -::: - -Visual mode uses the standard Pandoc markdown representation for citations (e.g. `[@citation]`). Citations can be inserted from a variety of sources: - -1. **Your document bibliography.** (`bibliography: references.bib`) -2. **Zotero** personal or group libraries. -3. **DOI** (Document Object Identifier) references. -4. Searches of [Crossref](https://www.crossref.org/), [DataCite](https://datacite.org/), or [PubMed](https://pubmed.ncbi.nlm.nih.gov/). - -If you insert citations from Zotero, DOI look-up, or a search then they are automatically added to your document bibliography. - -Use the **Insert \> Citation** or the `ctrl + shift + F8` keyboard shortcut to show the **Insert Citation** dialog: - -![](images/quarto_course_citations.png) - -Note that you can insert multiple citations by using the add button on the right side of the item display. - -## Quarto aplicabiltiy - -Many Quarto formats - -+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Feature | Quarto | -+==================+=========================================================================================================================================================================================================================================================+ -| Basic Formats | [html](https://quarto.org/docs/output-formats/html-basics.html), [pdf](https://quarto.org/docs/output-formats/pdf-basics.html), [docx](https://quarto.org/docs/output-formats/ms-word.html), [typst](https://quarto.org/docs/output-formats/typst.html) | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Beamer | [beamer](https://quarto.org/docs/presentations/beamer.html) | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| PowerPoint | [pptx](https://quarto.org/docs/presentations/powerpoint.html) | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| HTML Slides | [revealjs](https://quarto.org/docs/presentations/revealjs/) | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Advanced Layout | [Quarto Article Layout](https://quarto.org/docs/authoring/article-layout.html) | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Cross References | [Quarto Crossrefs](https://quarto.org/docs/authoring/cross-references.html) | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Websites & Blogs | [Quarto Websites](https://quarto.org/docs/websites/), [Quarto Blogs](https://quarto.org/docs/websites/website-blog.html) | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Books | [Quarto Books](https://quarto.org/docs/books/) | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Interactivity | [Quarto Interactive Documents](https://quarto.org/docs/interactive/shiny/) | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Journal Articles | [Journal Articles](https://quarto.org/docs/journals/index.html) | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Dashboards | [Quarto Dashboards](https://quarto.org/docs/dashboards/) | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -: {tbl-colwidths="\[25,75\]"} - -::: {.your-turn style="background: lightblue"} -**📝 Your turn** - -Go to File \> New File \> Quarto document to create a Quarto document with HTML output. Render the document, which will ask you to give it a name -- you can use `my-first-document.qmd`. - -Use the visual editor for the next steps. - -- Add a title and your name as the author. -- Create two sections, one with fact you want to learn and your favorite thing about R. -- Add a table of contents. -- **Stretch goal:** Change the html theme to `sketchy`. -::: - -### Presentations - -Quarto supports a variety of formats for creating presentations, including: - -`revealjs` — [reveal.js](https://quarto.org/docs/presentations/revealjs/) (HTML) - -`pptx` — [PowerPoint](https://quarto.org/docs/presentations/powerpoint.html) (MS Office) - -`beamer` — [Beamer](https://quarto.org/docs/presentations/beamer.html) (LaTeX/PDF) - -The most capable format by far is `revealjs`, so it is highly recommended unless you have specific Office or LaTeX output requirements. Note that revealjs presentations can be presented as HTML slides or can be printed to PDF for easier distribution. - -- Slides are delineated using headings (##) or horizontal rules (---). - -::: panel-tabset -### Code - -```{markdown} -## Getting up -- Turn off alarm -- Get out of bed -``` - -### Output - -## Getting up - -- Turn off alarm -- Get out of bed -::: - -- Separate in columns - -::: panel-tabset -### Code - -```{markdown} -:::: {.columns} -::: {.column width="40%"} -Content in the left side. -::: -::: {.column width="60%"} -![Picture here](https://upload.wikimedia.org/wikipedia/commons/b/ba/Flower_jtca001.jpg) -::: -:::: -``` - -### Output - -::: columns -::: {.column width="40%"} -Content in the left side. -::: - -::: {.column width="60%"} -![Picture here](https://upload.wikimedia.org/wikipedia/commons/b/ba/Flower_jtca001.jpg) -::: -::: -::: - -### Quarto Projects - -When projects are larger than a simple analysis (e.g. a paper with additional analyses presented in supplementary material), it is useful to split the project reporting in several Quarto documents. - -Quarto projects are such collections of Quarto documents, which can be rendered together or separately. They are defined by a `quarto.yml` file in the root directory of the project. This file contains metadata and configuration options for the project, such as the title, author, output formats, and more. - -Quarto projects are directories that provide: - -A way to render all or some of the files in a directory with a single command (e.g. quarto render myproject). A way to share YAML configuration across multiple documents. The ability to redirect output artifacts to another directory. - -In addition, projects can have special “types” that introduce additional behavior (e.g. websites, books or manuscripts). \### Useful Links - -- [Quarto](https://quarto.org) - -- [Quarto workshop](https://www.youtube.com/watch?v=yvi5uXQMvu4) - -- [What is Quarto? RStudio rolls out next-generation R Markdown](https://www.infoworld.com/article/3666743/what-is-quarto-rstudio-quietly-rolls-out-next-generation-r-markdown.html) - -- [Install TinyTeX to create PDF reports](https://yihui.org/tinytex/) - -- [How to create Word docs from R or Python with Quarto](https://www.infoworld.com/article/3671668/how-to-create-word-docs-from-r-or-python-with-quarto.html) diff --git a/AEET_2025/material_reproducible_science_AEET_2025.zip b/AEET_2025/material_reproducible_science_AEET_2025.zip new file mode 100644 index 0000000..56d8452 Binary files /dev/null and b/AEET_2025/material_reproducible_science_AEET_2025.zip differ diff --git a/AEET_2025/intro_qmd_en.html b/AEET_2025/reproducible_science.html similarity index 53% rename from AEET_2025/intro_qmd_en.html rename to AEET_2025/reproducible_science.html index e78b853..775f7d8 100644 --- a/AEET_2025/intro_qmd_en.html +++ b/AEET_2025/reproducible_science.html @@ -6,8 +6,10 @@ + + -Intro Quarto Elena +Improving scientific workflows with reproducible and collaborative projects in R - - - - - - - - - - + + + + + + + + + + @@ -104,19 +106,99 @@
-

Intro Quarto Elena

+

Improving scientific workflows with reproducible and collaborative projects in R

+

III SIBECOL and IV AEET meeting. Another science is possible

+
+
Author
+
+

Verónica Cruz-Alonso, Elena Quintero, Julen Astigarraga and Guillermo Fandos

+
+
+
+
Published
+
+

02/06/2025

+
+
@@ -126,18 +208,332 @@

Intro Quarto Elena

-

This part of the course is designed to provide an introduction to Quarto, a modern, open-source scientific and technical publishing system. Participants will learn the basics of creating dynamic documents, integrating code and text, and producing reproducible reports in multiple formats.

+

+
+

1 Introduction

+

The objectives of this workshop are:

+
    +

  • Effective collaboration, using the version control Git within RStudio.

    • +

  • Pushing local changes in R to a remote repository.

    • +

  • Sharing reproducible research with the community through GitHub.

    • +

  • Meet Quarto and learn the anatomy of a qmd file to authoring Quarto documents

    • +

  • Basic functionalities of Quarto, enabling attendees to create good-looking and easily shareable documents.

    • +
+
+

1.1 Workshop structure

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BloquesTiempo estimado
Introduction to Git and GitHub30 min
Repositories and R projects15 min
Working flow in Git and GitHub45 min
Break30 min
Introduction to Quarto15 min
Structure of a Quarto document15 min
Create a Quarto document40 min
Break10 min
Collaborative work with Git and GitHub40 min
+
+
+

1.2 Who we are?

+

Verónica Cruz Alonso (veronica.cral@gmail.com), Elena Quintero (elenaquintero.qb@gmail.com) and Guillermo Fandos (gfandos@ucm.es)

+

And you… who are you?

+

https://www.menti.com/alefzp9t3t17

+
+
+
+

2 Introduction to Git and GitHub

+

Probably, at some point, you’ve struggled with broken scripts that no longer work, repeated the same calculations multiple times to update a manuscript, or dealt with co-authors’ comments while working on different versions of a document. To help avoid these situations and other challenges in scientific workflows, this workshop explores the powerful combination of GitHub and Quarto in RStudio to author scientific documents. The aim is to foster among researchers the adoption of open and reproducible practices while improving their project and data management skills. In particular, we will introduce the version control system Git, the remote repository GitHub, and the publishing framework Quarto. Quarto is the next generation of R Markdown for publishing dynamic documents with multi-lingual programming language support. These tools are becoming increasingly useful in ecology, as they allow the creation of reproducible documents —including text and analyses— while tracking changes in R and facilitating collaboration among multiple users.

+
+

2.1 Git

+

Git (https://git-scm.com/) and GitHub (https://github.com/) are becoming increasingly relevant in various fields as data volumes increase and analyses become more complex. We will learn how Git can be used to control versioning in projects or files, and how this is especially useful in collaborative projects using GitHub.

+

Though there are many manuals available on Git and GitHub, these are complex tools. Git was created to help software developers collaborate on large-scale projects, so it can be convoluted, offer multiple solutions to the same problem, and have a steep learning curve. Still, Git and GitHub solve many common problems:

+
    +

  • File overwriting

    • +

  • Endless “final” versions

    +
    +
    +

    +
    “FINAL.doc”
    +
    +
    • +

  • Working by mistake on a non-final version

    • +

  • Conflicting copies when two people edit simultaneously

    • +

  • Edits without change tracking

    +
    +
    +

    +
    Ediciones sin control de cambios
    +
    +
    • +
+
+
+

2.2 What is Git

+

Git is a distributed version control system (like MS Word’s track changes). It tracks project progress through snapshots. These allow you to see what changed, who did it, and why — and return to earlier versions.

+
+
+

+
Ejemplo de un proyecto rastreado por Git con indicaciones de cómo se registran los cambios y la evolución del proyecto, el autor o autora de los cambios (¿quién?), el momento en que se han registrado (¿cuándo?), en qué documentos o líneas se han producido cambios (¿dónde?) y qué ha cambiado (¿qué?)
+
+
+

Moreover, Git facilitates parallel work among multiple collaborators. While in other version control systems (e.g., Subversion (SVN, https://subversion.apache.org/) or Concurrent Versions System (CVS, http://cvs.nongnu.org/)) there is a central server and any change made by a user is synchronized with this server and then with the rest of the users, Git is a distributed version control system that allows all users to work on the project simultaneously and take individual “snapshots” of their work, which can later be merged. Other distributed version control alternatives comparable to Git include Mercurial (https://www.mercurial-scm.org/) and Bazaar (https://bazaar.canonical.com/), but Git is by far the most widely used.

+
+
+

+
Interacción entre Git y GitHub. Git, al ser un control de versiones distribuido, permite que todos los usuarios trabajen paralelamente sin interferir en el trabajo de los demás. Luego cada usuario sincroniza su trabajo con la copia principal del proyecto ubicado en GitHub
+
+
+

Git emerged in 2005, following the breakdown of the relationship between the community developing Linux and the commercial company behind BitKeeper (a distributed version control system). At that point, BitKeeper stopped being free, which led the Linux developer community (particularly Linus Torvalds, the creator of Linux) to develop their own version control tool based on their experience using BitKeeper. Some of the main goals for the new system were speed, simple design, strong support for non-linear development (branches), a distributed model, and the ability to handle large datasets. Therefore, the original purpose of Git was to help teams of software developers collaborate on large-scale software projects. In this regard, we will see that there are multiple ways to solve the same problem and that the learning curve can be steep for non-developers.

+
+
+

2.3 What is GitHub

+

GitHub is an online hosting server or remote repository for storing Git-based projects, enabling collaboration between different users or even with oneself [@galeano2018; @perez-riverol2016]. A repository is a directory where a project is developed, containing all the necessary files for it. Although there are other remote repositories (e.g., GitLab, https://gitlab.com/, or Bitbucket, https://bitbucket.org/) with similar functionality, GitHub is currently the most widely used. GitHub records the development of projects remotely, allows users to share projects with others, and provides cloud-based security, among other features.

+
+
+

+
Página inicial de GitHub
+
+
+

When working on collaborative projects, the foundation of the interaction between Git and GitHub is that all collaborators agree that GitHub hosts the main copy of the project — that is, GitHub serves as the centralized copy of the otherwise distributed or decentralized version control system.

+
+
+

2.4 Git instalation

+
+

📝 Your turn

+

At this point, you need to have the latest version of R installed (https://cloud.r-project.org/), RStudio (https://www.rstudio.com/products/rstudio/download/), Git (https://happygitwithr.com/install-git.html) and an account in GitHub (https://github.com/) created.

+
    +

  1. Introduce yourself to Git (Chapter 7: Git-Intro)

    +
    +
    #|eval: false    
+# install.packages("usethis")  
+# library(usethis)  
+# use_git_config(user.name = "Monchi", user.email = "monchi@example.org")}
    +
    2. +
+

💡You must use the email address associated with your GitHub account

+
    +

  1. In the terminal, check that Git is installed correctly:

    +

    git --version

    +

    To see the user configured for Git:

    +

    git config user.name

    +

    To view both the user and the associated email:

    +

    git config user.email

    +

    To view both the user and the associated email:

    +

    git config --global --list

    2. +
+

⚡What is the shell? The shell (or terminal) is a program on your computer whose job is to run other programs (see https://happygitwithr.com/shell.html#shell). RStudio includes a terminal that you can use to interact with Git; however, it also has a tab called “Git” that provides basic Git functionalities and makes its use much easier.

+
+
+

+
Terminal
+
+
+

💡For troubleshooting installation issues, we recommend checking here: https://happygitwithr.com/troubleshooting.html

+
    +

  1. Generate a PAT (Personal Access Token) for HTTPS

    +

    Git can communicate with a remote server using one of two protocols: HTTPS or SSH. We will use HTTPS with a personal access token (PAT, https://happygitwithr.com/https-pat.html).

    2. +
+
+
#|eval: false
+
+# install.packages("gitcreds")  
+# library(gitcreds)  
+# create_github_token() # generar un token, elegir temporalidad 
+# gitcreds_set() # acceder al Git credential store
+
+

👀 It’s a good idea to describe the purpose of the token in the Note field, since you can have several PATs. You won’t be able to view this token again, so don’t close or leave the browser window until you’ve stored the PAT locally. Treat this PAT like a password!

+
+
+
+

2.5 Git repositories and projects

+

Un repositorio es como un “contenedor” donde desarrollar un proyecto.

+

To create a repository on GitHub, click “+ New repository”. Here you’ll enter the name, a brief description, and decide whether you want it to be public or private. It’s recommended to initialize the repository with a “README” file (Initialize this repository with a README) to record essential information about the repository’s use (structure, more detailed description of contents, etc.).

+

In RStudio, create a new project and connect it to the repository: File > New project > Version control > Git > copy the URL of the repository you created on GitHub (you’ll find it on the main page of your repository, under “clone or download”). Choose the local directory where you want to save the project and click “Create project”.

+

If you go to the selected local directory, you’ll find the folder connected to Git and GitHub that you created on your computer. You can copy here all the files you need for the project (data, images, etc).

+

💡For more information on how to clone the repository from GitHub (remote repository) to your computer (local repository), see https://happygitwithr.com/rstudio-git-github.html for doing it from RStudio and @galeano2018 for doing it via command line.

+

💡If you want to connect an existing RStudio project to Git and GitHub, you can follow the steps described here: https://happygitwithr.com/existing-github-first.html.

+
+

📝 Your turn

+
    +
  1. Create a repository on GitHub and connect it to a new RStudio project (this will generate a repository (folder) on your computer in the location you specified). Include a “.gitignore” file. Create a new R script in the working directory (that is, create an R script and save it inside the repository you just created)
    2. +
  2. In RStudio, go to the Git tab to see all the documents that have been identified by Git
    3. +
+
+
+
+

+
Git en RStudio
+
+
+
+
+

2.6 Git ignore

+

When creating a repository, it’s recommended to create a *.gitignore* file. This file will list the names or extensions of project files that, by default, we don’t want to share even though they exist in the local repository (e.g., the *.Rhistory* file that RStudio creates by default). It’s good practice to ignore files that won’t be useful to other collaborators, as well as very large files (e.g., a database generated by running a script) so they aren’t repeatedly uploaded and downloaded from GitHub.
+To add files to the gitignore, you can right-click on the file in RStudio’s Git tab, or you can manually add the file name you wish to ignore to the *.gitignore* file.

+
+

📝 Your turn

+
    +

  1. Add your project’s .Rproj file to the *.gitignore* file.

    2. +

  2. Create a folder named datos (data) in your working directory. Add it to the *.gitignore* file and save. What happened in the Git tab?

    3. +
+
+
+
+

2.7 Structure of a GitHub repository

+

On the main page of your repository on GitHub you’ll find the following tabs:

+
    +

  • Code: project content.

    • +

  • Issues: a project forum to discuss bugs, pending tasks, make requests to developers, ask questions, etc. You can assign tasks or questions to project members by writing @ before the collaborator’s name. Once resolved, the issue is closed (Close issue).

    • +

  • Pull requests: we’ll see what this is for later.

    • +

  • Actions: small applications that perform actions every time a commit is pushed (e.g., tests).

    • +

  • Projects: like a spreadsheet for tasks, assignees, deadlines, status, etc. It integrates with issues and pull requests to help plan and track project work.

    • +

  • Wiki: a space to document the project (roadmap, status, detailed documentation, etc.).

    • +

  • Security: security options.

    • +

  • Insights: project statistics.

    • +

  • Settings

    • +
+
+
+

+
GitHub repository highlighting some important tabs
+
+
+
+
+

2.8 GitHub: the social network

+

GitHub is not just a remote repository for storing different versions of your work or developing collaborative projects — it’s also a social network for programmers. Like on other platforms, you can browse profiles, follow people, gain followers, and save projects you like.

+

Using the search tool (🔍), you can look for content that interests you. The search is organized into categories (Repositories, Commits, Issues, Users, etc.), which makes it easier to find what you’re looking for. To follow a user, you can use the Follow option. By clicking Star ⭐, you can bookmark any repository in your GitHub account. With Fork, you’re saving a personal copy of a repository that you can interact with. Watch 👁️ lets you follow activity in a repository. Download allows you to save a copy of any public repository to your computer.

+
+
+

2.9 Workflow in Git and GitHub

+

Git is able to track all the files contained in a repository. To understand how Git records changes and how we can share those changes with collaborators, it’s important to grasp how Git is structured and how it synchronizes with GitHub. There are four main “working areas”:

+
    +

  1. Working directory: this is where you actively work. This area is synchronized with the local files on your computer.

    2. +

  2. Staging area or Index: this is the intermediate zone between the working directory and the local Git repository. It acts as a draft space. The user must select which files will be recorded in the next Git “snapshot.”

    3. +

  3. Local repository or HEAD: this is where all the changes captured by Git on your computer are recorded.

    4. +

  4. Remote repository: this is where all the changes captured by Git are stored in the cloud (GitHub).

    5. +
+
+
+

+
Graphical representation of the different working areas in Git and GitHub: working directory, staging area (or index), local repository (HEAD), and remote repository. Background image by Philip Brookes (https://creativecommons.org/licenses/by-nc-nd/2.0/legalcode)
+
+
+
+

2.9.1 How to move from one area to another?

+

It can be done through the command line in the terminal as well as through the integrated tab in RStudio, but the process is the same.

+
+
+

+
Options of Git in RStudio
+
+
+

At first, all the changes made appear in yellow because Git doesn’t know what to do with them. We are in the working directory, and we might not want to save all the changes for the future.

+

To add a change from the working directory to the staging area, you need to use git add (in RStudio’s Git tab, this is done by selecting the file). This command tells Git that you want to include the updates of a file in the next “snapshot” of the project and that Git should record them. However, git add does not affect the local repository.

+
    +
  • git add <file name>: adds an update of a file from the working directory to the staging area.
    • +
+

To record the changes we are interested in, you need to use git commit (in RStudio’s Git tab, this is done by clicking the “Commit” button). When you run git commit, a “snapshot” of the project’s state is taken. Along with the commit, a message is added with a brief explanation of the changes made and why (e.g., “include formatted references”). Each git commit has a SHA (Secure Hash Algorithm), which is an alphanumeric code that uniquely identifies that commit (e.g., 1d21fc3c33cxxc4aeb7823400b9c7c6bc2802be1). It seems hard to understand, but don’t worry, you only need to remember the first seven digits 1d21fc3 😮 (just kidding). With the SHA, you can always see the changes made in that commit and easily go back to that version.

+
    +
  • git commit -m "short and descriptive message"
    • +
+
+
+

+
Commit in RStudio
+
+
+

💡Using git commit for the project is like using anchors when climbing a rock wall. Developing a script without commits is like climbing without securing yourself: you can move much faster in the short term, but in the long run, the chances of catastrophic failure are high. On the other hand, making too many commits will slow down your progress. The best approach: use more commits when you are in uncertain or dangerous territory.

+
+
+

+
Working lines (ropes) secured with multiple commits (anchors)
+
+
+

Finally, git push allows you to upload the changes you have made to GitHub, making them visible to your collaborators (in RStudio’s Git tab, this is done by clicking the “Push” button). Basically, git commit records the changes in the local repository, and git push updates the remote repository with the changes and associated files.

+

When resuming a project after hours, days, or even months, git pull downloads all updates from GitHub (ours or from our collaborators), which are merged (merge) with the latest commit in our local repository (in RStudio’s Git tab, this is done by clicking the “Pull” button).

+
+
+

+
Workflow in Git and GitHub showing the different work areas and the commands used to transition from one work area to another
+
+
+

In addition to the main buttons described earlier, in RStudio’s Git tab we can see the “Diff” button, which shows the changes made to each file since the last commit, and the branches (which we will explain later). By right-clicking, we can open the modified files using “Open file”, and with the “Revert” button, we return to the state of the last commit (⚠️ be careful with this because it will delete the changes made in your working directory).

+
+

📝 Your turn

+

In the project previously created, save and upload the changes made to GitHub (git add + git commit + git push)

+

💡 git status: shows the branch we are on and the changes made and added since the last commit.

+
+

In the remote GitHub repository, in the Code tab, we can see the contents of our project, including every commit made:

+

+
+ +
+
+
+

3 Quarto

+

This part of the workshop is designed to provide an introduction to Quarto, a modern, open-source scientific and technical publishing system. Participants will learn the basics of creating dynamic documents, integrating code and text, and producing reproducible reports in multiple formats.

In addition to learning how to use Quarto, this section will also cover some essential first steps for practicing reproducible research, including the importance of literate programming, documenting analysis workflows, and properly licensing and sharing materials.

Some of the materials and ideas included here are inspired by openly available resources shared under Creative Commons licenses.

Specifically, parts of this course draw inspiration from:

-
-

Quarto

-
-

What is Quarto

+
+

3.1 Introduction to Quarto

+
+

3.1.1 What is Quarto

Quarto is a dynamic document publishing system that allows you to create reports, books, manuscripts, presentations, and websites. It is a very versatile tool that supports multiple programming languages (R, Python, Julia, etc.) and output formats (HTML, PDF, Word, etc.). Quarto is based on R Markdown but offers a number of improvements and new features that make it more powerful and flexible. It can be used in different workspaces (e.g., RStudio, Jupyter) and has a visual editing interface in RStudio.

@@ -146,14 +542,14 @@

What is Quarto

-
-

Why use Quarto

+
+

3.1.2 Why use Quarto

Quarto is an ideal tool for creating reproducible scientific documents and for collaborative work. It allows you to integrate code, text, and results into a single document, making it easier to produce scientific reports and publications. In addition, Quarto is compatible with Git and GitHub, enabling version control and efficient collaboration with others.

-
-

Brief history: Evolution from R Markdown

+
+

3.1.3 Brief history: Evolution from R Markdown

Quarto (https://quarto.org/) began as an open-source project in 2021 by Posit Software (formerly RStudio) and is based on over 10 years of experience with R Markdown. Quarto functions as an open-source scientific and technical publishing system built on top of Pandoc (https://pandoc.org). It converts plain text formats (e.g., .md, .Rmd) or mixed formats (e.g., .ipynb) into static reports and more. It can interweave narrative text and code to produce elegantly formatted results in the form of documents, web pages, blog posts, books, and so on.

The Quarto file extension is .qmd, and it uses Lua filters, which is Pandoc’s extension language (https://quarto.org/docs/extensions/lua.html). To do this, Quarto uses an engine like knitr to execute the code and generate a temporary .md output. The .md file is then processed by Pandoc and Quarto’s Lua filters, plus Bootstrap CSS for HTML or LaTeX for PDF. Lua filters written by R/Python/Julia developers should be interchangeable between formats — they are typically not language-specific.

@@ -163,41 +559,41 @@

Br

-
-

Quarto installation

+
+

3.1.4 Quarto installation

Quarto comes pre-installed with the latest versions of RStudio (v2022.07 and later). However, if you want to use it in other interfaces as well, you can follow the installation instructions on the official website: https://quarto.org/docs/get-started/.

To use Quarto from within R, you need to have the rmarkdown package installed:

-
#|eval: false
-install.packages("rmarkdown")
+
#|eval: false
+install.packages("rmarkdown")

You can also verify the Quarto installation and its location with the following command:

-
#|eval: false
-quarto::quarto_path()
+
#|eval: false
+quarto::quarto_path()
-
-

Key differences between R Markdown and Quarto

+
+
+

3.2 Key differences between R Markdown and Quarto

The main difference between Quarto and R Markdown is that Quarto was designed for collaboration across multiple communities (i.e., not just R or Python users) and uses a shared syntax and format across different languages. Additionally, as more capabilities were added to R Markdown through external R packages, the syntax for basic tasks became inconsistent. Some differences between Quarto and R Markdown in terms of code are:Diferencias clave entre R Markdown y Quarto

  • YAML structure - both follow key: value but Quarto is more flexible and nested

  • code chunk header syntax - #| syntaxis (hash pipe). This is the preferred syntax in Quarto, although it is compatible with the older R Markdown syntax. The hash pipe adds more consistency across engines (Jupyter, knitr) and gives us more control over the order and spacing of chunk options (it’s not limited to a single line of options). Each #| line is interpreted as a key: value pair.

    • +

  • Enhanced tab completion: start typing a word and press Tab to auto-complete, or use Ctrl + Space to view all available options.

-

Enhanced tab completion: start typing a word and press Tab to auto-complete, or use Ctrl + Space to view all available options.

-
2 * 2
+
2 * 2
[1] 4
-
-
-

Why use Quarto instead of R Markdown?

+
+

3.2.1 Why use Quarto instead of R Markdown?

  • Shared syntax (choose your preferred editor and language)
  • Greater versatility
  • Better features and further improvements in the future (R Markdown is still maintained, but most new features will be incorporated into Quarto)
-
-

What should I do with my existing .Rmd files?

+
+

3.2.2 What should I do with my existing .Rmd files?

No problem! Most existing .Rmd or .ipynb files can be converted as-is using Quarto. To do this from the terminal command line, type:

quarto render file.Rmd --to html

Additionally, there are various options for converting .Rmd files to .qmd:

@@ -208,13 +604,14 @@

-

Getting started with Quarto

+
+
+

3.3 Getting started with Quarto

📝 Your turn

-
-

Creating a Quarto document

+
+

3.3.1 Creating a Quarto document

To create a Quarto document in RStudio, follow these steps:

  1. In RStudio, go to File → New File → Quarto Document

    2. @@ -224,28 +621,38 @@

    Creating a Quar

-
-

Quarto workflow

+
+

3.4 Quarto workflow

Rendering a Quarto file in RStudio via the Render button calls quarto render in a background job, preventing Quarto rendering from cluttering up the R console, and gives you and easy way to stop:

-
-

Rendering

+
+

3.4.1 Rendering

  1. Option 1: In RStudio as a background job, and preview the output.

  2. Option 2: In the Terminal via quarto render:

-
quarto render document.qmd # defaults to html
-quarto render document.qmd --to pdf
-quarto render document.qmd --to docx
+
quarto render document.qmd # defaults to html
+quarto render document.qmd --to pdf
+quarto render document.qmd --to docx
  1. Option 3: In the R console, via the quarto R package:
-
library(quarto)
-
-quarto_render("document.qmd") # defaults to html
-quarto_render("document.qmd", output_format = "pdf")
+
library(quarto)
+
+quarto_render("document.qmd") # defaults to html
+quarto_render("document.qmd", output_format = "pdf")
+
+
+
+
+ +
+
+Figure 1 +
+

📝 Your turn

@@ -258,15 +665,15 @@

Rendering

  • RStudio > Render,
  • using the CLI with quarto render, and
    • -
  • in the R console via quarto::quarto_render().
    • +
  • in the R console via quarto::quarto_render(). You need library(quarto)
  • If you’re an RStudio user, brainstorm why you might still want to know about the other two ways of rendering Quarto documents.
    • -
    -

    Anatomy of a Quarto document

    +
    +

    3.5 Anatomy of a Quarto document

    It contains three types of content:

    1. Metadata: YAML header surrounded by —s.

      2. @@ -274,114 +681,113 @@

      Anatomy of a Quarto document

    2. Code: Executed via knitr or jupyter

    Weave it all together, and you have beautiful, powerful, and useful outputs!

    -
    -
    -
    ---
-title: "Hello, Penguins"
-format: html
-execute:
-  echo: false
----
-
-## Meet the penguins
-
-The __penguins__ data contains size measurements for 
-penguins from three islands in the Palmer Archipelago, 
-Antarctica.
-
-The _three_ species of penguins have quite distinct 
-distributions of physical dimensions (@fig-penguins).
-
-#| label: fig-penguins
-#| fig-cap: "Dimensions of penguins across three species."
-#| warning: false
-library(tidyverse, quietly = TRUE)
-library(palmerpenguins)
-penguins |>
-  ggplot(aes(x = flipper_length_mm, y = bill_length_mm)) +
-  geom_point(aes(color = species)) +
-  scale_color_manual(
-    values = c("darkorange", "purple", "cyan4")) +
-  theme_minimal()
    -
    +
    #| eval: false
+#| echo: true
+#| code-line-numbers: "|1-6|8-15|17-29|"
+
+---
+title: "Hello, Penguins"
+format: html
+execute:
+  echo: false
+---
+
+## Meet the penguins
+
+The __penguins__ data contains size measurements for 
+penguins from three islands in the Palmer Archipelago, 
+Antarctica.
+
+The _three_ species of penguins have quite distinct 
+distributions of physical dimensions (@fig-penguins).
+
+#| label: fig-penguins
+#| fig-cap: "Dimensions of penguins across three species."
+#| warning: false
+library(tidyverse, quietly = TRUE)
+library(palmerpenguins)
+penguins |>
+  ggplot(aes(x = flipper_length_mm, y = bill_length_mm)) +
+  geom_point(aes(color = species)) +
+  scale_color_manual(
+    values = c("darkorange", "purple", "cyan4")) +
+  theme_minimal()

    -
    -
    -
    -

    1. YAML header

    +
    +

    3.5.1 YAML header

    The YAML header is demarcated by three dashes (—) on either end. It informs on some documents meta-data and sets up many generic and output format specific options. The YAML consists of key: values pairs. The colon and space are required.

    YAML header can be very simple

    “Yet Another Markup Language” or “YAML Ain’t Markup Language” is used to provide document level metadata.

    -
    ---
-title: "Hello, Penguins"
-format: html
-execute:
-  echo: false
----
    +
    ---
+title: "Hello, Penguins"
+format: html
+execute:
+  echo: false
+---

    The YAML header is demarcated by three dashes (—) on either end. It informs on some documents meta-data and sets up many generic and output format specific options. The YAML consists of key: values pairs. The colon and space are required.

    As well as much more elaborated, e.g. when scholarly writing

    -
    ---
-title: "Toward a Unified Theory of High-Energy Metaphysics: Silly String Theory"
-date: 2008-02-29
-author:
-  - name: Josiah Carberry
-    id: jc
-    orcid: 0000-0002-1825-0097
-    email: josiah@psychoceramics.org
-    affiliation: 
-      - name: Brown University
-        city: Providence
-        state: RI
-        url: www.brown.edu
-abstract: > 
-  The characteristic theme of the works of Stone is 
-  the bridge between culture and society. ...
-keywords:
-  - Metaphysics
-  - String Theory
-license: "CC BY"
-copyright: 
-  holder: Josiah Carberry
-  year: 2008
-citation: 
-  container-title: Journal of Psychoceramics
-  volume: 1
-  issue: 1
-  doi: 10.5555/12345678
-funding: "The author received no specific funding for this work."
----
    +
    ---
+title: "Toward a Unified Theory of High-Energy Metaphysics: Silly String Theory"
+date: 2008-02-29
+author:
+  - name: Josiah Carberry
+    id: jc
+    orcid: 0000-0002-1825-0097
+    email: josiah@psychoceramics.org
+    affiliation: 
+      - name: Brown University
+        city: Providence
+        state: RI
+        url: www.brown.edu
+abstract: > 
+  The characteristic theme of the works of Stone is 
+  the bridge between culture and society. ...
+keywords:
+  - Metaphysics
+  - String Theory
+license: "CC BY"
+copyright: 
+  holder: Josiah Carberry
+  year: 2008
+citation: 
+  container-title: Journal of Psychoceramics
+  volume: 1
+  issue: 1
+  doi: 10.5555/12345678
+funding: "The author received no specific funding for this work."
+---

    YAML headers can operate at the document level to manage execute options:

    -
    ---
-title: "Hello, Penguins"
-subtitle: "Penguins are vertebrates"
-execute:
-  echo: false
-  eval: true
-  warning: false
-  error: true
----
    +
    ---
+title: "Hello, Penguins"
+subtitle: "Penguins are vertebrates"
+execute:
+  echo: false
+  eval: true
+  warning: false
+  error: true
+---

    Or can set format specific options (here for html output):

    -
    ---
-title: "Hello, Penguins"
-subtitle: "Penguins are vertebrates"
-format:
-  html:
-    theme: united
-    code-fold: true
-    code-summary: "see the code"
-execute:
-  echo: true
-  eval: true
-  warning: false
-  error: true
----
    +
    ---
+title: "Hello, Penguins"
+subtitle: "Penguins are vertebrates"
+format:
+  html:
+    theme: united
+    code-fold: true
+    code-summary: "see the code"
+execute:
+  echo: true
+  eval: true
+  warning: false
+  error: true
+---

    All format specific options are listed in the Quarto official documentation.

    YAML Intelligence: YAML code completion is available for project files, YAML front matter, and executable cell options:

    @@ -396,76 +802,76 @@

    1. YAML header

    -
    ---
-key: value
----
    -
    -
    Output options
    -
    ---
-format: something
----
    ---
-format: html
+key: value
 ---
    +
    +
    3.5.1.0.1 Output options
    ---
-format: pdf
+format: something
 ---
    ---
-format: revealjs
+format: html
 ---
    -

    Indentation matters!

    ---
-format: 
-  html:
-    toc: true
-    code-fold: true
----
    -
    -
    -
    YAML validation
    +format: pdf +---
    +
    ---
+format: revealjs
+---
    +

    Indentation matters!

    +
    ---
+format: 
+  html:
+    toc: true
+    code-fold: true
+---
    + +
    +
    3.5.1.0.2 YAML validation
    • Invalid: No space after :
    -
    ---
-format:html
----
    +
    ---
+format:html
+---
    • Invalid: Read as missing
    -
    ---
-format:
-html
----
    +
    ---
+format:
+html
+---
    • Valid, but needs next object
    -
    ---
-format: 
-  html:
----
    +
    ---
+format: 
+  html:
+---

    There are multiple ways of formatting valid YAML:

    • Valid: There’s a space after :
    -
    format: html
    +
    format: html
    • Valid: There are 2 spaces a new line and no trailing :
    -
    format:
-  html
    +
    format:
+  html
    • Valid: format: html with selections made with proper indentation
    -
    format: 
-  html:
-    toc: true
    +
    format: 
+  html:
+    toc: true
    -
    -
    Why YAML?
    +
    +
    3.5.1.0.3 Why YAML?

    To avoid manually typing out all the options, every time when rendering via the CLI:

    -
    quarto render document.qmd --to html
    -
    quarto render document.qmd --to html -M code-fold:true
    -
    quarto render document.qmd --to html -M code-fold:true -P alpha:0.2 -P ratio:0.3
    +
    quarto render document.qmd --to html
    +
    quarto render document.qmd --to html -M code-fold:true
    +
    quarto render document.qmd --to html -M code-fold:true -P alpha:0.2 -P ratio:0.3

    📝 Your turn

    Open hello-penguins.qmd in RStudio.

    @@ -476,8 +882,8 @@
    Why YAML?
    -
    -
    List of valid YAML fields
    +
    +
    3.5.1.0.4 List of valid YAML fields

    • Many YAML fields are common across various outputs

    • But also each output type has its own set of valid YAML fields and options

      • @@ -485,16 +891,21 @@
      List of valid YA
    -
    -

    2. Markdown

    +
    +

    3.5.2 Markdown

    The markdown you know from R Markdown will work in Quarto.

    Quarto is based on Pandoc and uses its variation of markdown as its underlying document syntax. Pandoc markdown is an extended and slightly revised version of John Gruber’s Markdown syntax.

    Markdown is a plain text format that is designed to be easy to write, and, even more importantly, easy to read:

    A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. – John Gruber

    -
    -
    Text Formatting
    +
    +
    +

    +
    +
    +
    +

    3.5.2.1 Text Formatting

    @@ -526,8 +937,8 @@
    Text Formatting
    -
    -
    Headings
    +
    +

    3.5.2.2 Headings

    @@ -542,56 +953,55 @@
    Headings
    - + - + - + - + - + - +
    # Header 1

    Header 1

    4 Header 1

    		 
    ## Header 2

    Header 2

    4.1 Header 2

    		 
    ### Header 3

    Header 3

    4.1.1 Header 3

    		 
    #### Header 4

    Header 4

    4.1.1.1 Header 4

    		 
    ##### Header 5
    Header 5
    4.1.1.1.1 Header 5
    		 
    ###### Header 6
    Header 6
    4.1.1.1.1.1 Header 6
    -