Hello Quarto

share • collaborate • teach • reimagine

Pierre Navaro

pierre-navaro.quarto.pub/hello-quarto

artwork by allison horst

Publishing tools using Markdown

Static site generators: Jekyll, Hugo, Pelican.
Converters
- Pandoc : a universal document converter
- jupytext : Jupyter Notebooks as Markdown or Quarto documents, Julia, Python or R scripts
Slides
- pandoc + beamer : use the presentation class for \(\LaTeX\)
- remark : markdown-driven slideshow tool
- RISE : Reveal.js - Jupyter/IPython Slideshow Extension
Julia
- Remark.jl : Create markdown presentations
- Franklin.jl : Building static websites
- Weave.jl : Scientific Reports
Collaborative editing
- CodiMD: realtime collaborative markdown notes on all platforms.
- Stylo: a semantic text editor

Transform a collection of notebooks to an html or pdf document.
Nice documentation https://jupyterbook.org,
utilizes Sphinx heavily under the hood
large community, many extensions and creators are friendly.
MyST syntax is really great.
High-quality printable pdf document
Rmd files could be used through jupytext (did not try)
This is the best alternative to quarto for books.
“Guide de Bonnes Pratiques sur la gestion des données de la Recherche” : pdf, html, repo.

The R Markdown

The rmarkdown package helps you create dynamic analysis documents that combine code, rendered output (such as figures), and prose. You bring your data, code, and ideas, and R Markdown renders your content into a polished document that can be used to:

Do data science interactively within the RStudio IDE,
Reproduce your analyses,
Collaborate and share code with others, and
Communicate your results with others. R Markdown documents can be rendered to many output formats including HTML documents, PDFs, Word files, slideshows, and more, allowing you to focus on the content while R Markdown takes care of your presentation.

The R Markdown ecosystem

You can run Python or Julia code in an R Markdown document, but… you have to install R.

Quarto unifies and extends
the R Markdown ecosystem

unifies for people who love R Markdown

extends for people who don’t know R Markdown

Quarto is a new, open-source,
scientific and technical
publishing system

the goal is to make the process of creating
and collaborating dramatically better

A schematic representing the multi-language input (e.g. Python, R, Observable, Julia) and multi-format output (e.g. PDF, html, Word documents, and more) versatility of Quarto.

Quarto CLI orchestrates
each step of rendering

A schematic representing rendering of Quarto documents from .qmd, to knitr or jupyter, to plain text markdown, then converted by pandoc into any number of output types including html, PDF, or Word document.

Quarto enables contributing
from different tools

Screenshot of RStudio IDE

Screenshot of Jupyter Lab

Screenshot of GitHub IDE

Screenshot of VS Code IDE

Quarto makes moving between formats straightforward

Document

lesson-1.qmd

title: "Lesson 1"
format: html

Presentation

lesson-1.qmd

title: "Lesson 1"
format: revealjs

Website

_quarto.yml

project:
  type: website

website: 
  navbar: 
    left:
      - lesson-1.qmd

Rmd conversion with command line

Install quarto

brew install quarto

Convert the Rmd file

Rscript -e 'knitr::convert_chunk_header("document.Rmd", "document.qmd")'

Improve your document

quarto preview document.qmd

Render the final document

quarto render document.qmd

Publish the document

quarto publish

Continuous integration

.gitlab-ci.yml

image: python:3.9

variables:
  VERSION: 1.1.189
  URL : "https://github.com/quarto-dev/quarto-cli/releases/download/"

pages:
  script:
    - wget "${URL}/v${VERSION}/quarto-${VERSION}-linux-amd64.deb"
    - dpkg -i quarto-${VERSION}-linux-amd64.deb
    - quarto render
    - mv _site public
  artifacts:
    paths:
      - public

Mathematics

$$
\mathbf{t}^* \in {\rm arg}\,\min_{\mathbf{t}} P \min_{j = 1..k}\|\cdot-m(P_{t_j,h})\|^2+v(P_{t_j,h}).
$$

\[ \mathbf{t}^* \in {\rm arg}\,\min_{\mathbf{t}} P \min_{j = 1..k}\|\cdot-m(P_{t_j,h})\|^2+v(P_{t_j,h}). \]

Callout Block

Note

Note that there are five types of callouts, including: note, tip, warning, caution, and important.

::: {.callout-note icon=false}
## Definition
The <span style="color:teal">$k$-power distance-to-measure</span> ($k$-PDTM) $\rm d\it_{P,h,k}$ is
defined for $x\in \mathbb{R}^d$ by:
$$\rm d\it^2_{P,h,k}(x) = \min_{j = 1..k}\|x-m(P_{t^*_j,h})\|^2+v(P_{t^*_j,h})$$
:::

Definition

The \(k\)-power distance-to-measure (\(k\)-PDTM) \(\rm d\it_{P,h,k}\) is defined for \(x\in \mathbb{R}^d\) by: \[ \rm d\it^2_{P,h,k}(x) = \min_{j = 1..k}\|x-m(P_{t^*_j,h})\|^2+v(P_{t^*_j,h}) \]

R Code

compute_means_and_weights <- function(P, centers, Sigma){
    c = nrow(centers)
    d = ncol(centers)
    means = matrix(0, nrow = c, ncol = d)
    weights = rep(0, c)
    for (i in 1:c) {
        nn = sort(mahalanobis(P, centers[i, ], Sigma[[i]],
                  inverted = TRUE), index.return = TRUE)
        nn$ix = nn$ix[1:k]
        means[i, ] = colMeans(matrix(P[nn$ix, ], k, d))
        weights[i] = mean(mahalanobis(P[nn$ix, ], means[i, ], Sigma[[i]],
                  inverted = TRUE)) - log(det(Sigma[[i]]))
            }
    return(list(means = means, weights = weights))
}

Julia Code example

function compute_means_and_weights_with_distances(points, centers, Σ )

    d, c = size(centers)
    μ, ω = zeros(d, c), zeros(c)

    Threads.@threads for i in eachindex(ω)
        dist = SqMahalanobis(Σ[i])
        dists = pairwise(dist, data.points, centers[:,[i]], dims=2 )
        idxs = sortperm(vec(dists))[1:k]
        μ[:,i] .= vec(mean(view(points, :, idxs), dims = 2))
        ω[i] = mean(pairwise(dist, view(points,:, idxs), μ[:,[i]], dims=2))
    end

    return μ, ω

end

compute_means_and_weights_with_distances (generic function with 1 method)

Plot and folding code

Show the code

using CluGen, Plots
o = clugen(2, 4, 400, [1, 0], pi / 8, [20, 10], 10, 1, 1.5)
p = plot(o.points[:, 1], o.points[:, 2], seriestype = :scatter, group=o.clusters)

Basketball

![Basketball](images/horst_quarto_basketball.png){width=400 fig-align="center"}

Videos demos

Examples

Python tools for Big Data (Jupyter notebooks) : quarto-html, jupyterbook, repo
Statistique en grande dimension (Laurent Rouvière) : html, repo
Partitionnement élagué avec des divergences de Bregman (Claire Brécheteau) : html, repo.
Site web de l’atelier données (Marie-Claude Quidoz et Pierre Brochard) : html, repo

Journal of the French Statistical Society: computo.

A Python Package for Sampling from Copulae: clayton : html, pdf, repo.
Visualizing Data using t-SNE: a mock Computo contribution : html, repo.

Conclusion

Versatile, multi-languages, quarto is a great tool for publishing.
Quarto CLI is really a game changer.
Very well documented.
Publishing and hosting is really easy.
Very powerful syntax but the level of knowledge needed is still quite high.
Well integrated with RStudio and VSCode but can be used on the command line with a text editor which was difficult to do with the RMarkdown tools.

Tutorials

References

Slides: Mine Cetinkaya-Rundel
Slides: Aurélie Mercadié & Christophe Regouby
Video: Quarto - le nouvel outil pour créer vos dataviz
Video: Reproducible authoring with Quarto
Video: Hello Quarto with NASA Openscapes, RLadies Santa Barbara, and JJ Allaire
Video: Reproducible Publications with Julia and Quarto
Quarto documentation: quarto.org
Quarto gallery: quarto.org/docs/gallery
Quarto tip a day: rstd.io/quartotip
Create beautiful interactive slide decks with Reveal.js: html, sources