Quarto

Hvað Quarto er, hvernig það byggir á markdown og LaTeX, og keyranleg R-dæmi með mtcars og plotly.

Hvað er Quarto?

Quarto er opinn hugbúnaður til að búa til skjöl, vefsíður, glærur og bækur út frá einföldum textaskrám. Skrárnar hafa endinguna .qmd og eru í grunninn markdown — sama einfalda orðalag og notað er í README.md skrám á GitHub — en með þeirri viðbót að hægt er að skjóta inn keyranlegum kóðabútum (R, Python, Julia).

Þegar Quarto þýðir (e. renders) skrána:

  1. keyrir það kóðabútana,
  2. skýtur niðurstöðum (tölum, töflum, myndum) inn í skjalið, og
  3. skilar statísku úttaki — oftast HTML.

Þessi vefsíða sem þú ert að lesa er einmitt gerð í Quarto.

Þetta er bara markdown

Grunnurinn er hefðbundið markdown. Til vinstri er það sem þú skrifar, til hægri hvernig það birtist:

Þú skrifar Útkoma
# Fyrirsögn stór fyrirsögn
**feitletrað** feitletrað
*skáletrað* skáletrað
`kóði` kóði
[hlekkur](https://hi.is) hlekkur
- listi punktalisti

Jöfnur með LaTeX

Auk markdown er hægt að skrifa stærðfræði með LaTeX rithætti. Jöfnur inni í texta eru umluktar einu dollaramerki, t.d. $E = mc^2$ sem birtist sem \(E = mc^2\).

Sjálfstæð jafna er umlukt tvöföldu dollaramerki. Þetta:

$$
\bar{x} = \frac{1}{n} \sum_{i=1}^{n} x_i
$$

birtist svona:

\[ \bar{x} = \frac{1}{n} \sum_{i=1}^{n} x_i \]

Kóðabútur og útkoma

Kóðabútur er skrifaður milli þriggja backticks (```) með tungumálinu í slaufusvigum. Þetta skrifar þú í .qmd skrána:

```{r}
1 + 1
```

Þegar Quarto þýðir skrána keyrir það bútinn og sýnir bæði kóðann og niðurstöðuna fyrir neðan:

1 + 1
[1] 2

Einfalt R-dæmi: mtcars

mtcars er innbyggt gagnasafn í R með upplýsingum um 32 bíla. Við skoðum fyrstu línurnar:

head(mtcars)
                   mpg cyl disp  hp drat    wt  qsec vs am gear carb
Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2
Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1

Og reiknum meðaleyðslu (mpg, mílur á gallon) eftir fjölda strokka (cyl):

aggregate(mpg ~ cyl, data = mtcars, FUN = mean)
  cyl      mpg
1   4 26.66364
2   6 19.74286
3   8 15.10000

Athugið: þessar tölur eru ekki slegnar inn handvirkt — þær eru reiknaðar af Quarto í hvert sinn sem síðan er þýdd. Ef gögnin breytast uppfærist taflan sjálfkrafa.

Gagnvirk mynd með plotly

Sama gagnasafn, en núna sem gagnvirk mynd. Prófaðu að sveima yfir punktana og draga til að þysja:

library(plotly)

plot_ly(
  data = mtcars,
  x = ~wt,
  y = ~mpg,
  color = ~factor(cyl),
  type = "scatter",
  mode = "markers",
  text = ~rownames(mtcars),
  marker = list(size = 10)
) |>
  layout(
    title = "Eyðsla eftir þyngd bíls",
    xaxis = list(title = "Þyngd (1000 lbs)"),
    yaxis = list(title = "Mílur á gallon"),
    legend = list(title = list(text = "Strokkar"))
  )

Sama skjalið gefur því bæði statískt úttak (töflur, tölur) og gagnvirkt úttak (plotly) — allt búið til beint úr kóðanum.

Mikilvægt„Gagnvirkt” er ekki það sama og „reactive”

Plotly-grafið er gagnvirkt í þeim skilningi að þú getur sveimað, þysjað og dregið — en það er föst mynd sem var reiknuð einu sinni þegar síðan var þýdd. Kóðinn keyrir ekki aftur þegar þú smellir. Til að úttakið bregðist við aðgerðum notandans (síur, hnappar, valreitir sem endurreikna gögnin) þarf bakenda sem keyrir kóðann á ný — t.d. Shiny. Það er utan þess sem statísk Quarto-síða á GitHub Pages getur gert.

Sem sagt: maður kemst mjög langt með statískum síðum sem eru að einhverju leyti gagnvirkar (plotly-gröf, Leaflet-kort, síanlegar töflur o.þ.h.) — og fyrir flestar skýrslur er það alveg nóg. Það er fyrst þegar úttakið þarf að endurreiknast út frá vali notandans sem bakendi verður nauðsynlegur.

Meira en skýrslur

Quarto er ekki bundið við skýrslur. Sama grunnhugmynd — markdown + kóði — nýtist í fleira:

  • Stílsnið — hægt er að stýra útliti með þemum og eigin CSS/SCSS. Stílsniðið á þessari vefsíðu byggir á hönnunarstaðli Háskóla Íslands og er geymt í skránni styles/hi-book.scss, tengt inn í _quarto.yml undir format: html: theme:.
  • Glærur — Quarto býr til gagnvirkar glærukynningar (reveal.js) úr sömu .qmd skrám. Sjá glærurnar hér í námsefninu — þær eru líka gerðar í Quarto og hýstar á GitHub.
  • Bækur, vefsíður og fleira — þetta námsefni sjálft er Quarto-bók.