Redactarea in timp real a documentelor
Acest workshop este dedicat invatarii RMarkdown, cu scopul de a genera documente reproductibile din punct de vedere computational.
Despre ce e vorba? Pe scurt, Rmarkdown va permite sa compilati datele, sintaxa si proza stiintifica intr-un singur document, urmatorul vostru articol, sau raport stiintific.
papaja impreuna cu Markdown.Separarea instrumentului de calcul de cel al procesarii textului in procesul de raportare creaza o falie ce trebuie trecuta de fiecare data. Doua lucruri se intampla obligatoriu aici: copy-paste si/sau actualizarea manuala. Dar Copy-paste este obositor si inclinat spre erori, ceea ce duce catre introducere manuala a datelor.
Nota: peste 10% din pragurile de semnficatie nu corespund statisticilor din textul respectiv, iar 1.6% din valorile p sunt tratate incorect, adica textul stiintific si valoarea p nu corespund.1
In ceea ce priveste actualizarea manuala, imaginati-va ca raportul dv. cuprinde 50 de diagrame, o serie de tabele, figuri si o serie intreaga de cifre. Aveti aproximativ 100 de clienti ce necesita raportul saptamanal. Rezultatele trebuie generate in acelasi timp cu textul.
Continutul are prioritate iar formatarea este, ca importanta, de ordin secundar. Un instrument orientat spre editare vizuala risca sa schimbe focus-ul dinspre continut spre decorul continutului.
Suplimentar, ar fi ideal daca instrumentul se ocupa singur de toate aspectele formatarii. Cu toate astea, autorul trebuie sa aiba acces la o serie intreaga de optiuni suplimentare.
Cu toate ca indeplineste o serie din conditiile enumerate, \(\LaTeX\), sau HTML nu sunt simplu de invatat si utilizat. Dimpotriva.
Cele mai populare standarde pentru rapoartele create sunt cu singuranta: .pdf, .doc, sau .ppt. In ultimul timp si HTML si EPUB, iar ele sunt de acum obligatorii.
De ex. ubicuitatea tabletelor si cititoarelor pe hartie electronica implica metode diferite. Un document creat pentru tablete sau hartie electronica necesita linii ce se pot rupe independent in functie de rezolutia (ceea ce EPUB si HTML pot sa o faca nativ, dar nu si .pdf).
Un mic bonus: acelasi text poate fi folosit pentru diverse scopuri cu un minim efort.
Documentul astfel pregatit sa fie multumitor dpdv estetic.
Sa fie utilizabil indiferent de platorma de utilizare si de timpul utilizarii.
Problema nu este imediat evidenta, insa evolutia soft-ului in timp o va face simtita.
Experiment: incercati sa deschideti fisiere output SPSS de acum 15 ani si raportati starile emotionale prin care treceti.
Sa fie “puternic,” i.e., sa fie flexibil si sa aiba functii diverse.
Sa fie gratis.
Sa usureze colaborarea.
Sa permita versionarea.
Optional (si nu prea):
5 Tinytex este, spre deosebire de Miktex, un pachet R
… nu poate fi mai simpla:
RMarkdown)R“Head”-erele in fisierele Markdown contin date, informatii despre documentul in care lucrati, si determina o serie de proprietati ale acestuia. In exemplul de mai jos, care este si cel mai simplu cu putinta, YAML contine informatii despre titlu, autor, data6 si a tipului de fisier dorit.
6 Pro-tip: folositi functia Sys.Date() pentru generarea automata a datei.
---
title: "Cum se zice corect: Iran sau Irak?"
author: "George"
date: "Mai 11, 2019"
output: html_document
---Daca doriti un fisier de tip ’.pdf aveti nevoie de software suplimentar.7 O alta solutie este un pachet R, numit Tinytex, ce se instaleaza din interfata R.
7 E vorba de TEX, pe care il puteti gasi la urmatoarea adresa https://miktex.org/
Dupa YAML, Textul este a doua componenta principala. Aici va scrieti proza stiintifica, adnotat cu Markdown (explicat ceva mai jos). Partea frumoasa este ca puteti combina codul R cu textul. In felul urmator:
Incepeti codul din cadrul textului cu `r, dupa care inserati codul dorit si inchideti cu `.8 Un cod R ` r 1+1` va fi rulat odata cu textul, iar rezultatul va fi afisat automat = 2. Vreti sa calculati 27 la puterea a 2-a? Nimic mai simplu: scrieti ` r 27^2`, care va produce = 729.
8 Accentul grav (engl. Backtick) este un semn diacritic folosit in grafierile mai multor limbi contemporane, precum catalana, franceza, etc. Functia sa principala in cazul nostru este de a delimita codul R de text.
RA treia componenta este codul R. Codul se insereaza prin Code->Insert code chunk sau combinatia de taste: CTRL+ALT+I. Codul R atasat Markdown, poate lua doua forme:
Our sample is made out of
` r nrow(esantion)`individuals.
```{r} fit <-lm(Ozone ~ Solar.R + Wind, data = airquality)```
YAML ce fel de document doriti sa creati : .html, .pdf, etc.9 In Markdown, fisierele create si dependente se afla tot timpul in locul unde se afla si fisierul .rmd. De aceea locatia lor este relativa.
Markdown este una dintre cele mai simple si usoare forme de adnotare a textului. Este un standard deschis, ce poate fi convertit in .tex, .docx, .html, .pdf, etc si este atat de usor incat il puteti invata in aproximativ 5 minute! Nu, chiar pe bune.10 Exista si alte linkuri utile precum acest PDF.
Limbajul este pe cat de usor, pe atat de puternic. Iata cateva exemple:
*italic* sau **aldin**.#titlu pentru primul nivel, ##titlu2 nivelul 2, si ###titlu3 pentru nivelul 3.* pentru fiecare item.[text](http://google.com).Pentru o lista completa folositi R Markdown Cheat Sheet11
11 Cheat Sheet
Luati un text oarecare (de ex: o pagina de pe wikipedia) si formatati-l cum credeti de cuviinta. Jucati-va cu toate optiunile posibile, de la text taiat pana la italic sau aldine. (Folositi “fituica” oferita de RStudio)
Citarea in RMarkdown este un proces destul de simplu, dar care trebuie tratat cu atentie. In principiu se folosesc ori Bibtex sau Biblatex, ambele standarde deschise. Cu toate astea, daca nu folositi deja un manager cum ar fi Zotero, va propun sa incepeti cu el.
Rmarkdown foloseste pandoc-citeproc, un filtru pandoc pe care-l aplica in ultimul pas al compilarii. Destul de tehnica explicatie, dar ideea (si avantajul) e ca functioneaza f. bine cu documentele Word si .pdf.
Pentru a incepe, adaugati numele fisierului ce contine bibilografia in parametrul bibliography din YAML, de exemplu (bibliography: literatura_mea.bib). Din acest moment, RMarkdown stie unde sa se uite dupa [@james_1890] si o va genera atat in text ca si la sfarsitul documentului: (James 1890).
Citari multiple trebuie separate de un ; (e.g., [@james_1890; @bem_2011]). Pentru a cita surse in text, nu le puneti in paranteze drepte; de exemplu; scrieti @james_1890 pentru a cita (James 1890).
| Tip citare | Sintaxa | Cum arata? |
|---|---|---|
| Citare in paranteza | [@james_1890] |
(James, 1890) |
| Citari multiple | [@james_1890; @bem_2011] |
(Bem, 2011; James, 1890) |
| Citari in text | @james_1890 |
James (1890) |
| Doar anul | [-@bem_2011] |
(2011) |
In functie de ce doriti sa obtineti in RMarkdown, aveti la dispozitie o serie de instrumente:
| A | B | C |
|:--|:--|:--|
| D | E | F |
| G | H | I |cu urmatorul output:
| A | B | C |
|---|---|---|
| D | E | F |
| G | H | I |
knitr ofera functia kable - tabele rezonabile cu un efort minim. Optiunea digits va ofera ceva control pentru rotunjirea cifrelor.library(kableExtra)
kable(head(mtcars), digits = 2)| mpg | cyl | disp | hp | drat | wt | qsec | vs | am | gear | carb | |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Mazda RX4 | 21.0 | 6 | 160 | 110 | 3.90 | 2.62 | 16.46 | 0 | 1 | 4 | 4 |
| Mazda RX4 Wag | 21.0 | 6 | 160 | 110 | 3.90 | 2.88 | 17.02 | 0 | 1 | 4 | 4 |
| Datsun 710 | 22.8 | 4 | 108 | 93 | 3.85 | 2.32 | 18.61 | 1 | 1 | 4 | 1 |
| Hornet 4 Drive | 21.4 | 6 | 258 | 110 | 3.08 | 3.21 | 19.44 | 1 | 0 | 3 | 1 |
| Hornet Sportabout | 18.7 | 8 | 360 | 175 | 3.15 | 3.44 | 17.02 | 0 | 0 | 3 | 2 |
| Valiant | 18.1 | 6 | 225 | 105 | 2.76 | 3.46 | 20.22 | 1 | 0 | 3 | 1 |
stargazer12 va da rezultate foarte bune. Partea puternica: estetica pentru modele complicate si o curba de invatare lina.Atentie: functia stargazer cere optiunea results="asis" in cod.
fit <- lm (Ozone ~ Solar.R, data=airquality)
fit2 <- update(fit ,.~. + Wind, data=airquality)
stargazer::stargazer(fit, fit2)produce
Putin in afara scopului acestui workshop: daca doriti doar sa generati usor si rapid tabele Word in format APA folositi cu incredere apaTables. De la tabele de corelatii, pana la ANOVA sau regresii, acest pachet le ofera pe toate.
Pachetul papaja ofera functia proprie apa_table(). Puteti folosi si pachetul xtable13, extrem de puternic, dar acesta din urma nu ofera sprijin pentru documente Word si este mai dificil de invatat. Cu putin efort si Google insa puteti sa-l stapaniti.
Graficele sunt mult mai usor de produs si integrat decat tabelele. Unele sunt extrem de simple, cum ar fi o histograma
hist(AirPassengers, breaks=5)
altele ceva mai complexe, de exemplu reprezentarea grafica a unei interactiuni cu pachetul ggplot.
library(ggplot2)
library(dplyr)
tips <- read.csv("https://sebastiansauer.github.io/data/tips.csv")
qplot(x = total_bill, y = tip, data = tips, color = sex) +
geom_smooth(method = "lm")
Ca de obicei, exista o serie de resurse foarte bune atat online14 cat si pe hartie15 ce trateaza problema graficelor in RMarkdown.
15 (Chang 2012)
Situatiile in care va trebui sa raportati formule sunt mai rare, dar exista. Aici intervine \(\LaTeX\). Codul trebuie inchis si deschis cu $, iar rezultatul va arata in felul urmator \(d' = z(\mathrm{H}) - z(\mathrm{FA})\). Exista si ecuatii mai complicate, aici veti folosi $$ pentru a deschide si inchide formula.
\[\frac{n!}{k!(n-k)!} = \binom{n}{k}\]
Codul latex poate fi destul de complex si greu de invatat, dar din fericire exista colectii intregi de formule online: aici.16
De exemplu, daca doriti sa includeti media si deviatia standard intr-un text, puteti folosi functia printnum() din pachetul papaja care va include valoarea numerica, o va rotunji si va elimina zero-ul din fata (cum cere formatul APA).
De exemplu, urmatorul cod:
Marimea esantionului este de de N=
` r nrow(date)`. Varsta medie este de` r printnum(mean(date$varsta))`ani cu o deviatie standard, SD =` r printnum(sd(date$varsta))`.
va produce urmtorul rezultat:
Marimea esantionului este de de N=6. Varsta medie este de 21.83 ani cu o deviatie standard (SD = 0.98).
papaja.Formatul APA este destul de dificil de stapanit. Manualul17 are peste 270 de pagini, cu o serie de informatii (uneori contradictorii) privind cerintele. Sabloane in format .doc circula pe internet, dar putine sunt cele care reusesc sa implementeze toti parametrii. Mai mult, la schimbul documentelor intre autori, sansele ca sablonul sa fie modificat sunt mari.
Frumusetea pachetului papaja este ca preia partea tehnica, creaza si formateaza documentele in stil APA, lasandu-va mai mult timp petnru crearea continutului. Cu toate ca pachetul nu este inca publicat pe CRAN (reteaua oficiala pentru pachete si distributii R), el este destul de stabil incat sa poate fi folosit in munca de zi cu zi.
papajaMomentan, papaja se afla pe GitHub si aveti nevoie de pachetul devtools pentru a-l instala.
# Daca nu-l aveti instalat inca, pachetul devtools este necesar.
if (!"devtools" %in% rownames(installed.packages())) install.packages("devtools")
# Instalati papaja
devtools::install_github("crsh/papaja")Dupa instalarea pachetului papaja18, sablonul APA ar trebui sa apara in meniul destinat crearii de noi documente.
18 Manualul papaja: https://crsh.github.io/papaja_man/index.html
Principiul dupa care functioneaza papaja este identic cu cel pe care l-am observat impreuna in Markdown, cu mentiunea ca papaja ofera o anvelopa suplimentara de functii ce preia formatarea, referintele si analiza statistica in momentul “crosetarii” documentului si le transpune in stilul APA.
Odata creat, documentul este prepopulat cu o serie de infomatii. Veti observa ca YAML (capul documentului) este ceva mai complex, dar auto-suficient de clar, iar in rest se pastreaza logica si sintaxa Markdown.
Atentie papaja este capabil sa exporte atat in fisiere de tip .docx cat si in .pdf, dar exista anumite restrictii, unele dintre ele importante. Pentru ca sistemul Microsoft este proprietar, pandocnu are acces la anumite functii de formatare. De exemplu, in documentele Word, imaginile (figurile) nu vor putea fi aranjate la sfarsitul documentulu (asa cum cere stilul APA).
papajapapaja aduce cateva functii noi ce faciliteaza raportarea analizelor statistice. Poate cea mai importanta este functia apa_print(). Aceasta functie preia continutul obiectelor din R, si le transforma text ce poate fi inserat in document.
Sa vedem un exemplu:
library(papaja)
# regresie lineara
modelfit <- lm(Ozone ~ Solar.R + Wind, data = airquality)
#functia apa_print() preia obiectul "lm" si-l transforma/salveaza
result <- apa_print(modelfit)Rezultatele ar putea fi scrise in felul acesta,
The analysis shows that the levels of Solar radiation significantly predict the levels of ozone concentration (
` r result$estimate$Solar_R`), (` r result$statistic$Solar_R`). Moreover, the same effect can be observed in regard to the levels of wind intensity (` r result$estimate$Wind`), (` r result$statistic$Wind`).
care va produce urmatorul text:
The analysis shows that the levels of Solar radiation significantly predict the levels of ozone concentration (\(b = 0.10\), 95% CI \([0.05, 0.15]\)), (\(t(108) = 3.82\), \(p < .001\)). Moreover, the same effect can be observed in regard to the levels of wind intensity (\(b = -5.40\), 95% CI \([-6.74, -4.07]\)), (\(t(108) = -8.02\), \(p < .001\)).
Pentru unele obiecte R, apa_print() poate genera tabele, dar aici poate pachetele descrise ceva mai sus, au un usor avantaj.
Instalati pachetul papaja, deschideti un sablon nou, salvati documentul si “crosetati-l”.
Includeti cateva elemente de text, precum si cateva calcule folosind atat cod inline cat si bucati mari de cod.
Introduceti un grafic, oricare.
“Crosetati” si observati schimbarile.
sessionInfo()R version 4.6.1 (2026-06-24)
Platform: aarch64-apple-darwin23
Running under: macOS Sequoia 15.8.2
Matrix products: default
BLAS: /Library/Frameworks/R.framework/Versions/4.6/Resources/lib/libRblas.0.dylib
LAPACK: /Library/Frameworks/R.framework/Versions/4.6/Resources/lib/libRlapack.dylib; LAPACK version 3.12.1
locale:
[1] C/UTF-8/C/C/C/C
time zone: Europe/Berlin
tzcode source: internal
attached base packages:
[1] stats graphics grDevices utils datasets methods base
other attached packages:
[1] papaja_0.1.5.9001 tinylabels_0.2.5 dplyr_1.2.1 ggplot2_4.0.3
[5] kableExtra_1.4.1
loaded via a namespace (and not attached):
[1] Matrix_1.7-6 gtable_0.3.6 jsonlite_2.0.0 compiler_4.6.1
[5] tidyselect_1.2.1 xml2_1.6.0 stringr_1.6.0 splines_4.6.1
[9] systemfonts_1.3.2 scales_1.4.0 textshaping_1.0.5 yaml_2.3.12
[13] fastmap_1.2.0 lattice_0.23-1 R6_2.6.1 labeling_0.4.3
[17] generics_0.1.4 knitr_1.52 htmlwidgets_1.6.4 tibble_3.3.1
[21] insight_1.6.0 svglite_2.2.2 pillar_1.11.1 RColorBrewer_1.1-3
[25] rlang_1.3.0 stringi_1.8.9 xfun_0.62 parameters_0.30.0
[29] S7_0.2.2 datawizard_1.4.1 otel_0.2.0 viridisLite_0.4.3
[33] cli_3.6.6 withr_3.0.3 magrittr_2.0.5 mgcv_1.9-4
[37] digest_0.6.39 grid_4.6.1 rstudioapi_0.19.0 effectsize_1.0.3
[41] nlme_3.1-171 lifecycle_1.0.5 vctrs_0.7.3 evaluate_1.0.5
[45] glue_1.8.1 farver_2.1.2 stats4_4.6.1 bayestestR_0.20.0
[49] rmarkdown_2.32 tools_4.6.1 pkgconfig_2.0.3 htmltools_0.5.9