-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy path05.Rmd
140 lines (97 loc) · 16.9 KB
/
05.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
# Повторливи документи / извештаи со писмено програмирање (R + markdown) {#rmd}
Во претходното поглавје, се запознавме со некои од главните методи за обезбедување на нашиот програмски код со цел да биде фунцкионален и на нечиј друг компјутер. Разгледавме ситуација со една скрипта и една табела со резултати, но доколку се запрашаме, сигурно ќе се согласиме дека речиси никогаш не е доволно да се испрати (или објави) само една табела или пресметка. Наспроти, често потребно е да се додаде текстуално објаснување или некаков друг контекст на податоците. Исто така, во многу случаи, нашите визуелизации во форма на табели или графици, или нашите статистички резултати (t-вредности, p-вредности, равенки за регресија), треба да ги прикажеме заедно со програмскиот код кој сме го напишале за да дојдеме то тие резултати.
За едноставно комбинирање на код, податоци, резултати и текст во еден документ, светот на `R` се користи [`rmarkdown`](https://www.rdocumentation.org/packages/rmarkdown/versions/2.6) [@R-rmarkdown]. `rmarkdown` овозможува комбинирање на сите елементи на едно истражување во документ погоден за понатамошно споделување. Патем, така е напишан и овој прирачник, кој исто така цели да биде повторлив.
## Форматирање на текст со markdown
Markdown, за разлика од _markup_ програмски јазици како `HTML` или `LaTeX` има за цел да го поедностави процесот на форматирање на текст. За детална референца на филозофијата и синтаксата на `markdown`, погледнете ги официјалните вебсајти нa [оригиналната спецификација](https://daringfireball.net/projects/markdown/syntax) или поновата [стандардизирана спецификација](https://commonmark.org/). Во контекст на `R` и `Rstudio` погледнете го поглавјето за [Rmarkdown во книгата R for Data Science]( https://r4ds.had.co.nz/r-markdown.html) или [овој блогпост](https://emilyriederer.netlify.app/post/rmarkdown-driven-development/) (и линковите таму) посветен на процесот на развивање на `R` код, или развивање на една анализа низ призмата на писмено програмирање со `rmarkdown` („писмено“ го преведуваме од англиското 'literate programming').
Тука, накратко ќе ги споменеме најчестите компоненти. На пример, обичниот текст со мала декорација прикажан тука:
```
Оваа _реченица_ е напишана во **markdown** но не е процесирана за да се покаже синтаксата.
На [овој линк](https://kbroman.org/knitr_knutshell/pages/Rmarkdown.html) или
[овој линк](https://rmarkdown.rstudio.com/authoring_quick_tour.html) можете да
прочитате повеќе за пишување `Rmarkdown`.
За директни калкулации во текстот, користите ja следната синтакса: `р 3.14 * 2`.
Kаде што првиот елемент на парчето (chunk) укажува како да го процесираме кодот што следи.
**За `R` користете `r`**. (Во ова не-процесирано парче, не користиме кирилично `р` токму со
цел на тоа да ја покажеме синтакста без да го конвертираме кодот во пресметаната вредност)
За прикажување математичка нотација, користете: $P = r^2 * \pi$
```
по процесирањето ќе биде конвертиран во следниот параграф:
> Оваа _реченица_ е напишана во **markdown** но не е процесирана за да се покаже синтаксата.
На [овој линк](https://kbroman.org/knitr_knutshell/pages/Rmarkdown.html) или
[овој линк](https://rmarkdown.rstudio.com/authoring_quick_tour.html) можете да
прочитате повеќе за пишување `Rmarkdown`.
> За директни калкулации во текстот, користите ja следната синтакса: `r 3.14 * 2`.
Kаде што првиот елемент на парчето (chunk) укажува како да го процесираме кодот што следи.
**За `R` користете `r`**. (Во ова не-процесирано парче, ние користиме кирилично `р` токму со
цел на тоа да ја покажеме синтакста без да го конвертираме кодот во пресметаната вредност.)
> За прикажување математичка нотација, користете: $P = r^2 * \pi$
Забележуваме дека е навистина еднотавно да се куца обичен текст кој во `HTML`, `PDF`, или `MS Word` документ ќе биде прикажан како задебелен, курзив, со линкови, итн.
## Плетење на текст, код, и резултати со `knitr`
Досега видовме како можеме лесно да маркираме обичен текст кој ќе биде процесиран во убаво форматиран документ. Она што ни недостасува е комбинирање (плетење) на ваквиот текстот со програмски код и резултатите од тој код. `rmarkdown` го прави овој чекор супер едноставен. Се што е неопходно е да додадеме парче код кое почнува со нотацијата ` ```{r} ` и завршува со нотацијата ` ``` `. Тогаш `R` и пакетот [`knitr`](https://www.rdocumentation.org/packages/knitr/versions/1.30) [@knitr1;@knitr2;@knitr3] ќе се обидат да го интерпретираат и извршат сиот текст во ова парче како `R` код или коментари што почнуваат со `#`. Доколку извршувањето на тој код резултира со табела или график, `knitr` ќе го прикаже тој елемент веднаш под извршениот код.
Ова е далеку полесно со пример:
Откако ќе го сплетеме овој документ, добиваме:
Ова навистина само ја допира површината на тоа што е можно да се направи со алатките како `rmarkdown` и `knitr`. Имајќи во предвид дека крајните документи се `HTML`, `LaTex`, или `MS Word`, голем дел од богатсвото на можности на овие далеку поопширни `markup` системи ќе ви бидат достапни кога пишувате анализи во `rmarkdown`. Така да, ако сакате да вклучите лого од вашата организација, посебен фонт, специјално форматирње на маргини, пагинација, итн, сето тоа ќе можете тоа да го направите со стандардни методи достапни во `HTML` или `LaTeX`.
## Извештаи со параметри
Она што за нас е посебно корисно и интересно, е користењето на оваа платформа за писмено програмирање за пишување на [параметризирани извештаи](https://rmarkdown.rstudio.com/developer_parameterized_reports.html%23parameter_types%2F). Што значи ова? Па доколку имате некоj стандарден сет на анализи кои треба да ги повторите за сите градови во Македонија, можете да го извршите вашиот `Rmd` извештај со параметар за тоа кој град треба да биде обработен. Во самиот изворен код на извештајот, дефинирате [`yaml`](https://yaml.org/spec/1.2/spec.html) преамбула налик на следната:
```
---
title: Мој Извештај
output: html_document
params:
grad: Tetovo
---
```
Ова креира листа на параметри со името `params` која е достапна во `R` средината за време на извршувањето на документот, чијшто елементи може да ги употребите на следниот начин:
```{r, eval=FALSE}
params$grad
```
Доколку имаме некоја функција во нашиот извештај која се извршува пред правење на некој график за одреден град:
```{r, eval = FALSE}
library(dplyr)
filtriraj_gradovi <- function(podatoci, potreben_grad) {
podatoci %>% dplyr::filter(grad == potreben_grad)
}
```
Тогаш можете параметарот даден во преамбулата да го искористите при повикувањето на фунцкијата, и сите натамошни резултати ќе бидат посветени на градот што сме го пратиле како параметар:
```{r, eval = FALSE}
# претходен код и текст
filtriraj_gradovi(podatoci = moi_podatoci, potreben_grad = params$grad)
# натамошен код и текст
```
За да ги направиме сите извештаи побрзо, во можеме да го повикуваме извршувањето во `R` конзола:
```{r, eval = FALSE}
rmarkdown::render(input = "mojizvestaj.Rmd", params = list("Tetovo"))
```
Оттука, можеме дури и да напишеме `for` циклус со кој што ќе ги процесираме сите градови наеднаш и ќе генерираме посебен `HTML`, `PDF` или `MS Word` документ се секој град:
```{r, eval = FALSE}
gradovi <- c("Tetovo", "Gostivar", "Debar", "Berovo", "Dojran") # ...
for ( i in gradovi) {
message("Подготвувам извештај за: ", i)
rmarkdown::render(input = "pateka/do/mojizvestaj.Rmd", params = list(i))
}
```
Како оваа стратегија ја подобрува повторливоста на нашите анализи? Доколку немаме извештаи со параметри можеме да замислиме две стратегии. Првата, имаме еден главен `izvestaj.Rmd` којшто никогаш не го менуваме и правиме копии за секој град, така што набрзо нашата работна средина станува невозможна за менаџирање на долг рок:
```
izvestaj.Rmd
tetovo-izvestaj.Rmd
debar-izvestaj.Rmd
skopje-izvestaj.Rmd
skopje-izvestaj-juni.Rmd
skopje-izvestaj-juni-specijalen-so-logo.Rmd
kichevo-izvestaj-avgust-2019.Rmd
kicevo-izvestaj-avgust.Rmd
```
Втората, имаме еден `izvestaj.Rmd` којшто го менуваме директно и секогаш мора да го отвориме, промениме, и извршиме рачно. Така да кога ќе стигнат новите податоци следниот месец имаме 2-3 часа работа да го промениме градот во функцијата горе триесетина пати.
Дури и да го имате потребното време за вакви активности, очигледно е дека со овие опции е далеку полесно да направите грешка отколку со извештајот со параметри, којшто го пишувате еднаш и можете да го користите секогаш кога ќе ви треба без да го менувате изворниот код. Доколку треба да се измени или подобри извештајот, тоа се прави со промена на само еден документ, не треба да се сетите дека `kopje-izvestaj-juni-specijalen-so-logo.Rmd` треба да се промени засебно бидејќи има нешто специфично.
## Следни чекори
Околината на `rmarkdown` и `knitr` е особено богата со алатки за посебни намени што навистина можат да придонесат кон поголема транспарентност и повторливост на вашите анализи и генерално кон поголема продуктивност во вашата работа. Подолу наведуваме само неколку од овие алатки:
- креирање презентации (на пример: [тука](https://rmarkdown.rstudio.com/lesson-11.html) или [тука](https://bookdown.org/yihui/rmarkdown/xaringan.html))
- креирање [_интерактивни_ `Rmd`](https://rmarkdown.rstudio.com/lesson-14.html) документи што користат [`Shiny`](https://shiny.rstudio.com/) [@R-shiny] во позадина
- креирање стилизирани HTML документи со [`prettydoc`](https://prettydoc.statr.me/)
- креирање на книги со [`bookdown`](https://bookdown.org/) (како овој текст)
- креирање на едноставни [`rmarkdown` вебсајти](https://rmarkdown.rstudio.com/lesson-13.html) со `rmarkdown::render_site`
- креирање на дашбоарди со [`flexdashboard`](https://rmarkdown.rstudio.com/lesson-12.html)
## Резиме
Технички гледано, користењето на писмено програмирање, дали со `rmarkdown` + `knitr` или [`Sweave`](https://www.rdocumentation.org/packages/utils/versions/3.6.2/topics/Sweave) во `R` или [`Jypiter`](https://jupyter.org/) тетратки во `Python` (или некој од другите подджани јазици), додава зависности на нашиот код, и со самото тоа, до некоја мера оди наспроти идејата за правење што помалку претпоставки за контекстот во кој нашиот код ќе биде користен. Но од друга страна, придобивките од комбинирањето на текст, код, и резултати во истиот документ кој лесно може да биде објавен како веб страница веројатно се доволно големи да додавањето на овие зависности во вашиот повторлив проект е оправдано. Без разлика дали пишувате домашна задача или дисертација, можноста да направите корекции во кодот или текстот и да го извршите вашиот `Rmd` со една команда е секако далеку по-повторливо отколку да копирате бројки помеѓу два или повеќе различни програми пазејќи да замените на сите неопходни места.