Luku 6 Bookdown ja Rmarkdown
Bookdown- R-paketti “paketoi” RMarkdownin tulostutoiminnot (output) ja sen monet säädettävät optiot. Samat Rmd-dokumentit saadaan koottua moneen eri formaattiin: html- sivuiksi, PDF-dokumentiksi tai Ebook-kirjaksi. Kaikissa tulostusvaihtoehdoissa on monia eri vaihtoehtoja. Html-tulostuksessa voi valita yhden tai useamman html-sivun lisäksi gitbook- tai Tufte- vaihtoehdon. Ne on toteutettu css-tyylitiedostoilla ja JavaScript-kirjastoilla. Tässä on käytetty gitbook-formaattia.
LaTeX-formaatti renderöidään jollain LaTeX-vaihtoehdolla PDF-tiedostoksi. ToDo PDF-formaattejakin on useita variantteja, mikä niistä. Tässä vaihtoehdossa konfigurointimahdollisuudet ovat käytännössä rajattomat, sillä välitulosteena syntyvää TeX-tiedostoa voi muokata ja muuntaa sen sitten PDF-muotoon.
Prosessissa on monta vaihtetta, ja eri parametrien yhteisvaikutusta on vaikea hahmottaa.
Kuva 6.1: Tulostiedoston prosessointi - png
Perusopas bookdown paketin käyttöön on Yihui Xien “bookdown: Authoring Books and Technical Documents with R Markdown”". Siinä pääidea on tuottaa yhdellä Rmd-koodilla kuvan 6.1 kolme vaihtoehtoista tulostiedostoa mahdollisimman yksinkertaisesti. Knitr- ohjelma “kutoo” Rmd-tiedoston r-koodilohkojen tulokset ja tekstin markdown-tiedostoksi (md). Rmd-tiedostojen YAML-asetukset siirtyvät Pandocille, joka täydentää niillä omia mallitiedostojaan (template).
Asetuksia on useammassa paikassa. YAML- asetuksista bd-kirja kertoo näin: ”More bookdown configuration options in _bookdown.yml are explained in Section 4.4. Besides these configurations, you can also specify some Pandoc-related configurations in the YAML metadata of the first Rmd file of the book, such as the title, author, and date of the book, etc.” Tärkeintä on yksikertaisuus, lopullista ulkoasua voi hioa kun kokonaisuus on valmis.
Laajempi ja tarkempi opas ilmestyi 15.7.2018, kolmen kirjoittajan “R Markdown: The Definitive Guide”. Siinä eri asetusten hierarkia on kuvattu tarkemmin ja selkeämmin. Tulostusvaihtoehtoja esitellään laajemmin, bookdown on vain yksi luku.
R Studiolla alkuun pääse helposti, kun lataa bookdown-paketin, ja luo uuden bookdown-projektin. Xien ensimmäisen kirjan alku-luvut ja uudemman teoksen johdattelut auttavat jatkoon.
Käytännön vinkkejä
Kuvasuhde pitää olla 1:1 . Ehkä hankalin juttu Rmarkdownin kanssa työskennellessä, mutta aina voi avata oman grafiikkaikkunan. Dataa analysoidessa voi tallentaa kuvat pdf-muodossa, lisäillä kommentteja yms. Lopullisessa dokumentissa kuvasuhden pitää erikseen tarkista, säätämiseen on monta vipua.
Bookdown-työskentelyssä pdf-tuloste ei ole kätevä, yleensä analyysiä hiotaan Rmd-tiedosto kerrallaan. R Studio voi yllättää aina joskus! Knit-napin takaa löytyy kuitenkin eri renderöintifuktiot kuin oikean laidan yläikkunan “Build Book” - valikosta. Knitr-funktiota kannattaa käyttää, jos haluaa katsoa yhden Rmd-tiedoston tulostetta. Tarkista kuitenkin, että (a) Rmd-tiedostoon ei automaattisesti lisäillä YAML-headereita ja (b) projektin hakemistoon ei ilmesty ylimääräisiä Rmd-tiedostoja. Joskus bookdown R Studion kanssa kasaa yhden Rmd-tiedoston tulostuksessa “väliaikaiseksi” tiedostoksi koko dokumentin yhteen
.Rmd -tiedostoon. Jos bookdown-projektiin kuuluvia Rmd-tiedostoja ei eksplitsiittisesti luetella (suositeltavaa, laita bookdown.yml - tiedostoon lista) syntyy hassua sotkua. Koko raportin tulostus html-muodossa käy kätevimmin “Build book” - valikon html-book- funktiolla/formaatilla. Tämä pitää tsekata! (4.12.18)
Suositus: koko dokumentit tulostukset aina “puhtaalta pöydältä”, käynnistä R uudelleen. Myös silloin, kun tulostat ensin vaikka gitbookin ja sitten pdf-tiedoston.
Windows-ympäristössä (Windows 10) MikTeXin kanssa voi tulla ongelmia, jos käytät konetta tavallisen käyttäjän oikeuksilla. Bookdown-paketin kanssa on kätevää käyttää tinytex - r-pakettia, ja konfiguroida oman koneen MikTeX - asennus asentamaan tarvittavat paketit “lennossa”. Peruskäyttäjän omat paketit voivat vaatia päivitystä, mutta oikeudet eivät riitä. Pulman voi ratkaista, kun käynnistää MikTeXin paketinhallintasovelluksen (jolla on monta nimeä, admin console jne) peruskäyttäjänä, ja katsoo mitä päivityksiä on tarjolla. Nämä paketit voi sitten asentaa admin-oikeuksilla.
Kokeillaan vielä PDF-kuvan liittämistä dokumenttiin. Ei näy html-tulosteessa.
Kuva 6.2: Tulostiedoston prosessointi - pdf
Testataan koodilohkojen listausta, näyttää toimivan mutta vaatii vielä säätämistä. Ohje löytyi Yihui Xienin blogista (luettu 26.10.2018).
# pitääkö kirjastot ladata tässä, vai jokaisen rmd-tiedoston alussa? library(rgl)
library(ca)
library(rgl) # ongelmia jossain vaiheessa, kokeillaan toimiiko nyt (18.2.20)
library(haven)
library(dplyr)
library(knitr)
library(tidyverse)
library(lubridate)
library(rmarkdown)
library(ggplot2)
library(furniture)
library(likert)
library(scales) # G_1_2 - kuva
library(reshape2) # G_1_2 - kuva
library(printr) #19.5.18 taulukoiden ja matriisien tulostukseen - onkohan tarpeen? (29.6.2019)
# library(stargazer) # 28.5.2018, ei käytetetä joten pois (18.2.20)
library(bookdown)
library(tinytex)
system("pdflatex --version")
rmarkdown::pandoc_version()
knitr::kable(smoke[,1:4], booktabs = TRUE,
caption = 'CA-paketin smoke-data (keinotekoinen)'
)
# Taulukkoon viittaaminen tekstissä \@ref(label)
# riviprofiilit
smoke.rpro <- smoke / rowSums (smoke)
# keskiarvoprofiili
smoke.avrpro <- colSums(smoke) / sum(smoke)
knitr::kable(
list(smoke.rpro, t(smoke.avrpro) ), digits = 3,
caption = 'Riviprofiilit ja keskiarvoprofiili', booktabs = TRUE
)
smokeCA <- ca(smoke)
#temp1 <- smokeCA tämä kai tarpeeton ? (4.12.2018)
numres1CA1 <- summary(smokeCA)
#str(smokeCA)
#knitr::kable( smokeCA,
# digits = 3,
# caption = 'Riviprofiilit ja keskiarvoprofiili', booktabs = TRUE
#)
#str(temp1)
#stargazer(temp2$rows, type = "text", title = "CA-tuloksia")
# LateX-tulostuksessa float vaatii jotain tällaista:Table: (\#tab:cataul1)
#str(temp2)
#str(temp2$scree)
#temp2$scree
numres1CA1
knitr::kable( numres1CA1$rows,
digits = 3,
caption = 'Korrespondenssianalyysin diagnostiikkaa - rivit', booktabs = TRUE
)
knitr::kable( numres1CA1$columns,
digits = 3,
caption = 'Korrespondenssianalyysin diagnostiikkaa - sarakkeet', booktabs = TRUE
)
knitr::kable( numres1CA1$scree,
digits = 3,
caption = 'Korrespondenssianalyysin diagnostiikkaa - ominaisarvot', booktabs = TRUE
)
plot(smokeCA)
str(numres1CA1$scree)
test2 <- as.table(numres1CA1$scree)
#str(test1$V1)
str(test2)
test2[[dimnames]]
# Vielä kokeilua!
knitr::include_graphics('BookdownProc.png')
knitr::include_graphics('BookdownProc.pdf')“New line” vaaditaan koodilohkon jälkeen.