Skip to main content

cattolicadown:
An UCSC Thesis
Template for R Markdown

2 R Markdown basics

Ecco una breve introduzione all’uso di R Markdown. Markdown è una semplice sintassi di formattazione per la creazione di documenti HTML, PDF e MS Word e molto altro ancora. R Markdown offre la flessibilità di Markdown con l’implementazione di input e output R. Per maggiori dettagli sull’utilizzo di R Markdown, vedere http://rmarkdown.rstudio.com.

2.1 Sintassi di base Markdown

2.1.1 Whitespace

Fai attenzione al distanziamento. Sebbene lo spazio bianco sia in gran parte ignorato, a volte fornisce segnali su come procedere. Come abitudine, cerca di mantenere tutto allineato a sinistra quando possibile, specialmente mentre compili un nuovo paragrafo. In altre parole, non è necessario indentare il testo di base nel documento Rmd (in effetti, se lo fai, il tuo testo potrebbe sclerare).

2.1.2 Corsivo e grassetto

  • Corsivo si fa così *this* o _this_
  • Grassetti si fa così **this** o __this__
  • Grassetto e corsivo si fa così ***this***, ___this___, o (il più comprensibile) **_this_**

2.1.3 Codice Inline

  • Codice Inline si fa coi backticks, così `questo`

2.1.4 Pedice e Apice

pedice2 e apice2 sono fatti così ~2~ e ^2^

2.1.5 Barrato

  • Barrato si fa così ~~ barrato ~~

2.1.6 ‘Escaping’ (aka “se avessi bisogno di un aterisco?”)

  • Per includere un asterisco *, _ or \, aggiungi un altro \ prima del solito: \*, \_, \\

2.1.7 Endash (–), emdash (—)

  • – e — con -- e ---

2.1.8 Blocco citazione

Fai così:

Metti un > prima della linea di citazione.

2.1.9 Intestazioni

Le intestazioni delle sezioni vengono create con # di numero crescente, ad es.

  • # Intestazione di primo livello
  • ## Intestazione di secondo livello
  • ### Etc.

Nell’output PDF, un’intestazione di livello cinque si trasformerà in un’intestazione di paragrafo, ad esempio \paragraph{La mia intestazione di livello cinque}, che appare in grassetto sulla stessa riga del paragrafo successivo.

2.1.10 Elenchi puntati e numerati

Le liste senza ordine inziamo * o con -:

  • Item 1
  • Item 2

Le liste ordinate invece iniziano con un numero. Nota che puoi etichettare erroneamente i numeri e Markdown eseguirà comunque l’ordine direttamente nell’output:

  1. Item 1
  2. Item 2

Per creare una sottolista, indenta leggermente i valori (almeno quattro spazi o una tabulazione):

  1. Item 1
  2. Item 2
  3. Item 3
    • Item 3a
    • Item 3b

2.1.11 Interruzioni linea

Il modo ufficiale Markdown per creare interruzioni di riga è terminare una riga con più di due spazi.

Le rose sono rosse. Le violette sono blu.

Questo appare sulla stessa riga nell’output, perché non abbiamo aggiunto spazi dopo il rosso.

Le rose sono rosse. Le violette sono blu.

Questo appare con un’interruzione di riga perché ho aggiunto spazi dopo il rosso.

Trovo che questo sia fonte di confusione, quindi consiglio il modo alternativo: terminare una riga con una barra rovesciata creerà anche un’interruzione di riga:

Le rose sono rosse.
Le violette sono blu.

Per creare un nuovo paragrafo, metti una riga vuota.

Pertanto, questa riga inizia il proprio paragrafo.

2.1.12 Collegamenti ipertestuali

  • Questo è un collegamento ipertestuale a google creato scrivendo il testo che vuoi trasformare in un collegamento cliccabile tra [parentesi quadre seguite da a](https://hyperlink-in-parentheses)

2.1.13 Note a piè di pagina

  • Vengono creati1 scrivendo ^[testo della mia nota a piè di pagina] per fornire il contenuto della nota a piè di pagina in linea, o qualcosa come [^a-random-footnote-label] e fornendo il testo altrove nel formato mostrato sotto [^test-note]:

[^a-random-footnote-label]: questo è un test casuale.

2.1.14 Commenti

Per scrivere commenti all’interno del testo che non verranno effettivamente inclusi nell’output, utilizzare la stessa sintassi utilizzata per scrivere commenti in HTML. Cioè, <!-- questo non sarà incluso nell’output -->.

2.1.15 Matematica e formule (sintassi)

La sintassi per scrivere matematichese è stata rubata da LaTeX (il cui strumento di render è MathJax). Per scrivere un’espressione matematica che verrà mostrata inline, racchiudila tra i segni del dollaro. - Questo: $A = \pi*r^{2}$ Diventa: \(A = \pi*r^{2}\)

Per scrivere un’espressione matematica che verrà mostrata in un blocco, racchiudila tra due segni di dollaro.

Questo: $$A = \pi*r^{2}$$

Diventa:

\[A = \pi*r^{2}\]

Per creare equazioni numerate, mettile in un ambiente ‘equazione’ e assegna loro un’etichetta con la sintassi (\#eq:label), in questo modo:

\begin{equation} 
  f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k}
  (\#eq:binom)
\end{equation}

Diventa: \[\begin{equation} f\left(k\right)=\binom{n}{k}p^k\left(1-p\right)^{n-k} \tag{2.1} \end{equation}\]

Per ulteriori informazioni (ad esempio come teoremi), vedere ad es. la documentazione su bookdown.org ## Blocchi di codice eseguibile {#code} La magia di R Markdown è che possiamo aggiungere codice eseguibile all’interno del nostro documento per renderlo dinamico.

Lo facciamo sia come blocchi di codice (generalmente utilizzati per caricare librerie e dati, eseguire calcoli e aggiungere immagini, grafici e tabelle) o codice in linea (generalmente utilizzato per riportare dinamicamente i risultati all’interno del nostro testo).

La sintassi di un blocco di codice è mostrata nella figura 2.1.

Code chunk syntax

Figure 2.1: Code chunk syntax

Le opzioni di blocco comuni includono (vedi ad esempio bookdown.org):

  • echo: se visualizzare o meno il codice nell’output knitted
  • eval: se o per eseguire il codice nel blocco durante il lavoro a maglia
  • include: se includere qualcosa da un pezzo di codice nel documento di output
  • fig.cap: didascalia della figura
  • fig.scap: didascalia con cifre brevi, che verrà utilizzata nell’“Elenco delle cifre” nella prima parte del PDF

IMPORTANTE: non utilizzare i trattini bassi nelle etichette dei blocchi - se lo fai, è probabile che venga visualizzato un errore nell’output PDF che dice qualcosa come “! Errore didascalia pacchetto: \caption outside float”.

2.1.16 Pezzi di configurazione: configurazione, immagini, grafici

Un documento R Markdown di solito inizia con un pezzo che viene utilizzato per caricare le librerie e per impostare le opzioni di blocco predefinite con knitr::opts_chunk$set.

Nella tua tesi, questo accadrà probabilmente in index.Rmd e/o come parti di apertura in ciascuno dei tuoi capitoli.

```{r setup, include=FALSE}
# don't show code unless we explicitly set echo = TRUE
knitr::opts_chunk$set(echo = FALSE)

library(tidyverse)
```

2.1.17 Comprese le immagini

I blocchi di codice vengono utilizzati anche per includere immagini, con include_graphics dal pacchetto knitr, come in Figura 2.2

knitr::include_graphics("figures/sample-content/cattolica-logo.png")
UCSC logo

Figure 2.2: UCSC logo

Utili opzioni di blocco per le figure includono:

  • out.width (usare con una percentuale) per impostare la dimensione dell’immagine
  • se hai un’immagine che diventa mooolto grande nel tuo output, sarà vincolata alla larghezza della pagina impostando out.width = "100%"

Rotazione figura

Puoi usare l’opzione chunk out.extra per ruotare le immagini.

La sintassi è diversa per LaTeX e HTML, quindi per comodità potremmo iniziare assegnando la stringa giusta a una variabile che dipende dal formato in cui stai eseguendo l’output:

if (knitr::is_latex_output()){
  rotate180 <- "angle=180"
} else {
  rotate180 <- "style='transform:rotate(180deg);'"
}

Quindi puoi fare riferimento a quella variabile come il valore di out.extra per ruotare le immagini, come in Figura 2.3.

UCSC logo, rotated

Figure 2.3: UCSC logo, rotated

2.1.18 Mettere i grafici

Allo stesso modo, i blocchi di codice vengono utilizzati per includere grafici generati dinamicamente. Usi il codice ordinario in R o in altri linguaggi - La figura 2.4 mostra un grafico del set di dati cars delle distanze di arresto per le auto a varie velocità (questo set di dati è integrato in R ).

cars %>% 
  ggplot() +
    aes(x = speed, y = dist) +
    geom_point()
A ggplot of car stuff

Figure 2.4: A ggplot of car stuff

In automatico il grafico viene incluse nel tuo documento, così come le immagini. Questo succede tutte le volte che costruisci i.e. buildi il libro (bookdown bookdown::serve_book()) o fai knit i.e.knitr::knit un capitolo, i plots vengono generati automaticamente a partire dal tuo codice, poi salvati come immagini, quindi inclusi nel documento di output.

2.1.19 Tabelle

Le tabelle sono solitamente incluse con la funzione kable del pacchetto knitr.

La tabella ?? mostra le prime righe dei dati del dataset mtcars.

cars %>% 
  head() %>% 
  knitr::kable(caption = "A knitr kable table")
  • Gotchas: quando si utilizza kable, i sottotitoli sono impostati all’interno della funzione kable
  • Il pacchetto kable viene spesso utilizzato con il pacchetto kableExtra

2.1.20 Controllo del posizionamento

Una cosa che potrebbe essere fastidiosa è il modo in cui R Markdown gestisce i “fluttuanti” come tabelle e figure. Li chiamo fluttuanti perchè prendo a prestito la notazione LaTeX che li chiama proprio così. Nel tuo output PDF, LaTeX cercherà di trovare il posto migliore per mettere il tuo oggetto in base al testo che lo circonda e finché non hai davvero finito di scrivere dovresti semplicemente lasciarlo dove si trova.

In generale, dovresti consentire a LaTeX di farlo, ma se hai davvero veramente bisogno di una figura da posizionare dove inserisci nel documento, puoi fare in modo che LaTeX tenti di farlo con l’opzione chunk fig.pos=" H", come in Figura 2.5:

knitr::include_graphics("figures/sample-content/cattolica-logo.png")
An UCSC logo that LaTeX will try to place at this position in the text

Figure 2.5: An UCSC logo that LaTeX will try to place at this position in the text

Come sa chiunque abbia provato a giocare manualmente con il posizionamento di figure in un documento di Word, questo può avere effetti collaterali tipo spaziatura extra su altre pagine, ecc. Pertanto, generalmente non è una buona idea farlo - fallo solo quando hai davvero bisogno di assicurarti che un’immagine segua direttamente sotto il testo dove ti riferisci ad essa (in questo documento, dovevo farlo per Figure @ref( fig:latex-font-sizing) nella sezione 4.1.4). Per maggiori dettagli, leggi la sezione pertinente del R Markdown Cookbook.

2.2 Codice in linea eseguibile

“Codice in linea” significa semplicemente inclusione di codice all’interno del testo. La sintassi per farlo è `r R_CODE` Ad esempio, `r 4 + 4` produrrà 8 nel tuo testo.

Di solito lo utilizzerai nelle parti della tua tesi in cui riporti i risultati: leggi i dati o i risultati in un blocco di codice, archivia le cose che vuoi segnalare in una variabile, quindi inserisci il valore di quella variabile nel tuo testo. Ad esempio, potremmo assegnare il numero di righe nel dataset cars a una variabile:

num_car_observations <- nrow(cars)

Potremmo quindi scrivere:
“Nel set di dati cars, abbiamo osservazioni `r num_car_observations`.”

Che genererebbe:
“Nel set di dati cars, abbiamo osservazioni 50.”

2.3 Codice eseguibile in linguaggi diversi da R

Se desideri utilizzare linguaggi diversi da R, come Python, Julia C++ o SQL, consulta la sezione pertinente del R Markdown Cookbook.