1 R Markdown

1.1 Mardown

“Markdown is a lightweight markup language for creating formatted text using a plain-text editor. John Gruber and Aaron Swartz created Markdown in 2004 as a markup language that is appealing to human readers in its source code form Markdown is widely used in blogging, instant messaging, online forums, collaborative software, documentation pages, and readme files.”

https://en.wikipedia.org/wiki/Markdown

1.2 R Markdown, knit

Pozwala na elastyczne łączenie tekstu, Markdown, TeXa, R i html w jednym pliku i utworzenie dokumentu wyjściowego w formacie m.in. html i pdf (wszystkie laboratoria przygotowane zostały w ten sposób).

1.3 Pierwszy plik R Markdown

Z menu File wybieramy New File, a następnie pozycję R Markdown

Powinien otworzyć się okno:

gdzie możemy nadać Tytuł tworzonego dokumentu oraz autora. Możemy też wybrać rodzaj dokumentu wyjściowego (zostawmy HTML, PDF wymaga zainstalowanego MiKTeXa - zobaczymy na miejscu czy działa).

Powinien utworzyć się nowy dokument, który obowiązkowo zapisujemy pod wybraną nazwą w osobnym folderze. Będziemy generować dodatkowe pliki, które automatycznie zapiszą się w tym folderze, więc wybór “Pulpitu” nie jest dobrym wyborem (choć nie zakazanym, po prostu zły pomysł). Powinno pojawić się nowe okno z przykładową treścią:

Po zapisaniu pliku klikamy przycisk Knit:

aby skompilować dokument. Po chwili powinno się pojawić okno wbudowanej przeglądarki z naszym dokumentem. Dokument ten (o ile nic nie zostało zmienione) powinien się też zapisać w tym samym folderze - plik HTML.

Obok przycisku Knit znajduje się strzałka - umożliwia kompilacje pliku do formatu pdf lub worda (sprawdzić, czy działa).

1.3.1 Struktura pliku R Markdown

1.3.1.1 Preambuła w języku YAML

W górnej części automatycznie utworzonego pliku znajduje się preambuła w języku YAML. Ograniczona jest dwoma zestawami po 3 minusy, tj. ---.:

---
title: "Mój tytuł"
author: "M B"
date: "29 11 2022"
output: html_document
---

Poszczególne elementy nie wymagają chyba komentarza.

Przydatne - aby automatycznie wstawiana była data z dnia kompilacji dokumentu linijka date powinna mieć postać:

date: "`r format(Sys.time(), '%d %B, %Y')`"

Zadanie

Przeczytać o YAML:

https://pl.wikipedia.org/wiki/YAML

1.3.1.2 Opcje dokumentu

Globalne ustawienia, fragment kodu:

#```{r setup, include=FALSE}
#knitr::opts_chunk$set(echo = TRUE)
#```

Parametr echo odpowiada za wyświetlanie kodu. Zamiana na FALSE spowoduje, że żaden kod R się nie wyświetli, a jedynie wyniki działania tych kodów. Taka opcja została wykorzystana w niektórych zadaniach jako przykładowe wyniki, by pokazać wynik działania kodu, ale bez samego kodu.

Inne parametry:

#```{r setup, include=FALSE}
#knitr::opts_chunk$set(echo = TRUE, warning=FALSE, message =FALSE, eval=TRUE)
#```

warning - w dokumencie wyjściowym nie będą wypisywane ostrzeżenia (np. że jakichś danych brakuje)

message - w dokumencie wyjściowym nie będą wypisywane komunikaty typu że “pakiet blalblabla został zbudowany w wersji 1.1.1).

eval - decyduje, czy kod R zostaje wykonany w dokumencie R Markdown, czy też nie (sam tekst kodu, bez jego wykonania)

Elementy te można na koniec przetestować, jak już będziemy mieli jakiś własny kod.

1.3.1.3 Właściwy dokument

Dokument zawierający właściwą treść - przykładową można skasować :)

1.3.2 Edytor - tryb tekstowy i ‘visual’

Za pomocą skrótu klawiaturowego Ctrl (lewy)+ Shift(lewy)+F4 możemy przełączyć edytor między trybami tekstowym i ‘visual’. Ten drugi tryb jest nieco bardziej intuicyjny, pozwala na proste wybranie Nagłówków, pogrubienia, itp wstawianie obiektów oraz Tabele.

Najprostszy sposób przełączania między trybami to skorzystanie z przycisków:

Inny sposób przełączanie trybu tekstowego i ‘visual’ to przycisk trybika koło przycisku Knit:

1.3.2.1 Przydatne:

Wpisanie slasha:

/

w trybie ‘visual’ otwiera menu z dostępnymi elementami do wstawienia (nagłówki, tabele, kody…)

1.4 Wstawianie kodu w R do dokumentu

Kod R do dokumentu możemy wstawić na 2 sposoby

1.4.1 Krótka wstawka

W kodzie dokumentu możemy wstawić instrukcję R, w przykładzie sample(1:6,1), otoczoną znakami `r oraz ` :

`r sample(1:6,1) `

gdzie ten “apostrof” to tzw. grawis, symbol ten najczęściej jest pod znakiem Esc na klawiaturze Windows (Mac-podobne urządzenia mają ten klawisz w innym miejscu). Skompilowanie dokumentu skutkuje tutaj zastąpieniem kodu wynikiem jego działania, tutaj wylosowaniem liczby z zakresu od 1 do 6.

Zadanie:

Umieścić powyższy kod u siebie w dokumencie. Skompilować dokument. Sprawdzić “wylosowaną” wartość. Skompilować dokument ponownie - wylosowana wartość (w założeniu) powinna być inna niż poprzednio (z prawdopodobieństwem 1/6 możemy dostać znowu to samo - jeśli tak, to powtórzyć eksperyment).

1.4.2 Długa wstawka

Dłuższy kod R umieszczamy między znacznikami ```{r} - potrójny grawis, nawias klamrowy i litera r oraz ``` - potrójny grawis:

```{r}
x=seq(0,2*pi,length.out=2*100)
y=sin(x) #komentarz, że liczymy sinusa
plot(x,y)

```

Po kompilacji powinniśmy znaleźć w dokumencie powyższy kod oraz skutek jego działania, czyli wykres.

Zadanie

Wypróbować powyższy kod w swoim dokumencie.

1.4.3 Zadanie

Jaki efekt będzie, gdy przy r w powyższym kodzie dodamy echo=FALSE, a dokładniej:

```{r echo=FALSE}
x=seq(0,2*pi,length.out=2*100)
y=sin(x) #komentarz, że liczymy sinusa
plot(x,y)

```

Jest to opcja, gdy chcemy się podzielić wynikiem działania kodu R, ale sam kod chcemy ukryć.

Podobnie można w danej wstawce ustawić eval, warning, message w zależności od potrzeb.

1.4.4 Długa wstawka - guzik w RStudio

Łatwiej wstawić kod za pomocą przycisku

guzik do wstawiania kodu
guzik do wstawiania kodu

w górnej części okna, po prawej stronie. Jak widać, można dodawać kod także w innych językach.

Nie trzeba kompilować całego dokumentu za każdym razem, bieżący blok kodu możemy “uruchomić” zieloną strzałką po prawej stronie:

pojawi się też wynik działania kodu, tutaj wykres.

Przycisk obok zielnej strzałki:

pozwala na uruchomienie wszystkich bloków kodów powyżej (może się przydać, gdy inny blok ładuje na przykład biblioteki)

Zadanie:

Umieścić w swoim kodzie wybrany fragment z innego laboratorium (np. generowanie wykresu z zadania 5.1 z laboratorium 7, pamiętając o bibliotekach).

1.4.5 Wstawki R z błędami

Jeżeli wstawka R zawiera błędy, to cały dokument się nie skompiluje.

1.5 TeX w R Markdown

Kod TeXa możemy dodać w standardowy sposób, albo otaczając go pojedynczymi znakami dolara w przypadku wzoru w tekście lub podwójnymi znakami dolara, w przypadku gdy chcemy wzór wyeksponować:

Tekst z kodem jak niżej:

Funkcja $f \colon \mathbb{R} \to \mathbb{R}$ jest nieparzysta.

wyprodukuje nam linijkę postaci:

“Funkcja \(f \colon \mathbb{R} \to \mathbb{R}\) jest nieparzysta.”

Przykład wzoru wyeksponowanego:

$$
\left\{
\begin{array}{ccccccr}
x_1  &+&2x_2&+&5x_3&=&-4\\
3x_1 &+&x_2&-&4x_3&=&7\\
4x_1 &+&3x_2&+&x_3&=&3\\
-2x_1&-&2x_2&+&x_3&=&-3
\end{array}
\right.
$$

wyprodukuje nam:

\[ \left\{ \begin{array}{ccccccr} x_1 &+&2x_2&+&5x_3&=&-4\\ 3x_1 &+&x_2&-&4x_3&=&7\\ 4x_1 &+&3x_2&+&x_3&=&3\\ -2x_1&-&2x_2&+&x_3&=&-3 \end{array} \right. \]

UWAGA: Kliknięcie we wzór uruchomi tryb edycji równania

Praktyczna wskazówka:

W trybie “visual” RStudio zdarzają się pewne problemy z interpretacją wstawek TeXa. Może się zdarzyć, że kodu otoczonego dolarami edytor nie zamieni na wzór, zamiast tego zostanie nam np. coś takiego:

Wzór $\sin x$ - nie chce się wyświetlić prawidłowo.

W trybie edytora tekstowego znajdujemy problem - znaki dolara zostały zinterpretowane jako symbole, a nie znaczniki końca równania, o czym świadczą dodatkowe slashe przy tych znakach:

\$\\sin x\$

Rozwiązanie: w trybie tekstowym usunąć niepotrzebne slashe przed znakami dolara (UWAGA: przy sinusie też jest ekstra slash, też go trzeba usunąć).

Dzieje się tak, gdy chcemy sobie ułatwić życie i chcąc wstawić równanie w tekście (niewyeksponowane) od razu wpiszemy oba znaki dolara (otwierający i zamykający), a następnie wzór między tymi dolarami.

1.6 Wstawianie plików graficznych

Najłatwiejszy sposób na wstawienie grafiki to przeciągnięcie pliku graficznego z folderu (bieżącego) do okna RStudio w trybie “visual”

Zadanie:

Wstawić do swojego dokumentu dowolny obrazek

Po kliknięciu wstawionego obrazka mamy dostępne pewne opcje, taka jak zmiana wysokości i szerokości obrazka, jednostka, lock ratio oraz … trzy kropki. Trzy kropki dają dostęp do dalszych opcji, w tym umożliwiają nadanie wykresowi tytułu i opisu:

Link to pozwala na dodanie adresu internetowego, działającego po kliknięciu obrazka.

1.6.1 Wstawianie grafiki - drugi sposób

Inny sposób na wstawienie grafiki (oraz innych elementów) to użycie Insert:

albo ikonki obrazka.

1.6.2 Wstawianie grafiki - trzeci sposób

Wpisanie w trybie ‘visual’ znaku

/

rozwinie menu, które ma pozycję wstawiania obrazka…

1.7 Wstawianie kodu

W celach demonstracyjnych przydatna jest możliwość wstawienia kodu, który się nie wykona przy kompilacji (jak w tym pliku w celu wyjaśnienia, jak wstawić kod R). Kod taki jak niżej:

'r runif(50)'

wstawimy poprzez wybranie code block z pierwszego menu insert.

Jeżeli powyższy kod wpiszemy bez code block, to przy kompilacji wykona się on i dostaniemy wynik jego działania (Zadanie: sprawdzić co się stanie.).

1.8 Preambuła

W moim testowym pliku preambuła ma postać

---
title: "Mój tytuł"
author: "M B"
date: "29 11 2022"
output: html_document
---

Wybrane dodatki - sugeruję dodawanie elementów typu toc, theme itd po kolei. Ich opisy znajdują się poniżej. Uwaga: preambuła jest wrażliwa na wcięcia akapitowe itp. formatowanie.

---
title: "Mój tytuł"
author: "M B"
date: "29 11 2022"
output:
  html_document:
    toc: yes
    theme: cerulean
    highlight: tango
    df_print: paged
    code_folding: hide


---

Elementy, które można dodać to m.in.:

toc : yes - toc = table of contents - spis treści, ale umieszczony jako opcja dla html, tj.:

theme: cerulean zmienia ogólny wygląd dokumentu. Galerie theme można znaleźć np. pod adresem

galeria theme

niektóre dodatkowe theme wymagają zainstalowania dodatkowych pakietów i wymagają specjalnego wpisu w preambule, tj. np:

output:
  prettydoc::html_pretty:
    theme: cayman

ale dzięki temu wygląd dokumentu staje się ciekawszy.

Zadanie:

przejrzeć materiały spod linku z theme, zmienić theme swojego dokumentu.

highlight: tango - zmienia kolorowanie składni w pliku wyjściowym. Dostępne:

default, tango, pygments, kate, monochrome, espresso, zenburn, haddock, breezedark oraz textmate

df_print - sposób wyświetlania ramek danych.

Zadanie:

Wstawić ramkę danych iris do swojego dokumentu (bez definiowania df_print w preambule). W dokumencie wyjściowym powinna pojawić się cała ramka.

Sprawdzić działanie opcji df_print na argumentach kable, tibble, paged.

code_folding: hide powoduje, że kod R jest umieszczony w dokumencie, ale jest ukryty. Czytelnik dokumentu może “odkryć” ten kod. Alternatywna wartość to code_folding: show. Wtedy czytelnik dokumentu widzi od razu kod programu, ale może go ukryć

1.9 R Markdown w trybie tekstowym

Za odpowiednie formatowanie tekstu w dokumencie wyjściowym odpowiedzialne są odpowiednie znaczniki (znaczniki działają też w trybie ‘visual’):

  • poprzedzenie tekstu znakiem # zmieni tekst na tytuł rozdziału

  • poprzedzenie tekstu znakiem ## zmieni tekst na tytuł podrozdziału

  • itd aż do 6x #

  • wyróżnienie elementu następuje poprzez otoczenie go znakami gwiazdki * (pojedynczymi, podwójnymi…)

  • otoczenie tekstu grawisami powoduje wyeksponowanie tekstu (szare pole)

  • wyliczenie powstaje poprzez rozpoczęcie nowej linii od gwiazdki * lub minusa -

  • link do strony www dodajemy poprzedzając go http:// lub https://

1.10 Markdown i kod html

Możliwe jest użycie wielu elementów html, np. do zmiany czcionki czy jej koloru:

<span style="font-family: 'Comic Sans MS', 'Comic Sans'; color:red">Comic Sans przykład</span>
<span style="font-family: 'Times New Roman', serif; color:green">Times New Roman przykład</span>
<span style="font-family: Verdana; color:blue">Verdana przykład</span>
Zwykły przykład

da nam:

Comic Sans przykład Times New Roman przykład Verdana przykład Zwykły przykład

a kod

<ul>
<li>jeden</li>
<li>dwa</li>
<li>trzy</li>
</ul>
<ol style="list-style-type: lower-alpha;">
<li>lista a</li>
<li>lista b</li>
<li>lista c</li>
</ol>

da nam

  • jeden
  • dwa
  • trzy
  1. lista a
  2. lista b
  3. lista c

1.11 Markdown a TeX i pdf

Powyżej umówiliśmy niektóre opcje HTML jako formatu wyjściowego. W przypadku pdf po dodatkowe opcje odsyłam do materiałów

https://bookdown.org/yihui/rmarkdown/pdf-document.html

warto zwrócić uwagę na sekcję dotyczącą keep_tex, która pozwala na zapisanie kodu TeXowego wygenerowanego dokumentu pdf - może być przydatne np. do pracy magisterskiej.

Poza kodem zapisywane są też wykresy/rysunki, co też może być przydatne (oczywiście, każdy rysunek wygenerowany w R też możemy zapisać do pliku bezpośrednio, nie potrzebny jest Markdown).

1.12 Markdown a beamer (TeX)

Beamer to klasa TeXa służąca do przygotowywania prezentacji, więcej na

https://pl.wikipedia.org/wiki/Beamer_(LaTeX)

W przypadku R Mardown możemy wybrać opcje Presentation a następnie format pdf beamer. W nowym dokumencie znajdzie się przykład, który jako podstawa powinien zupełnie wystarczyć. Mankament - standardowo generowana prezentacja jest “brzydka”.

2 Zadania

2.1 Zadanie 1

Przygotować dokument R Markdown na temat całki Riemanna korzystając z artykułu wikipedii, z uwzględnieniem elementów:

  • tytuł dokumentu, autor, data itp

  • wybrany theme żeby było kolorowo

  • podanie źródła danych/materiałów

  • podział na sekcje/podsekcje (ze dwie)

  • formatowanie tekstu

  • wzory - mają być ładne, texowe

  • wstawić obrazek (z wiki, podając źródło)

2.2 Zadanie 2

Przygotować dokument R Markdown, który zaprezentuje połączenie tekstu ze wstawkami R. Inwencja własna, można wykorzystać wcześniejsze laboratoria. Wymaganie:

  • ma być wyjaśnione, co to jest ramka danych w R, jak ją stworzyć oraz przykład utworzenia ramki danych

  • opis, jak narysować wykres w ggplot2 (jakiś prosty) + przykład takiego rysunku (wraz z kodem).

  • zadbać o estetykę (tytuł, autor)