R jak raport

Wstęp

Tytułowe raporty, sprawozdania, artykuły można pisać/tworzyć przy pomocy wielu narzędzi. Najpopularniejszym jest pakiet MS Office. Dane z prób, eksperymentów wprowadzamy do Excela, przeprowadzamy obliczenia, analizy, a następnie wyniki kopiujemy do Worda. To najczęściej wykorzystywany sposób postępowania. Prosty i skuteczny. Przynajmniej w przypadku niewielkiej ilości raportów.

Duże ilości raportów można tworzyć w sposób programowy, np. przy użyciu narzędzia dla języka Python -- ReportLab. Jest to rozwiązanie trudniejsze, ale niezwykle efektywne.

Trzeci sposób, będący tematem tego wpisu, to rozwiązanie pośrednie, kompromis pomiędzy wygodą, a efektywnością.

R jak raport

Sweave jest narzędziem pozwalającym na osadzenie kodu R w dokumentach LaTeX. GNU R jest językiem programowania (dialektem S) i środowiskiem do obliczeń statystycznych, analizy danych oraz wizualizacji wyników.

Podstawowa wersja R dostępna jest na stronie R-project jako produkt open source. Na podstawie wersji otwartoźródłowej rozwijane są również komercyjne edycje enterprise jak np. Revolution Analytics.

Środowisko R dostępne jest dla systemów Linux, Mac OS oraz Windows. Użytkownicy edytora Emacs (opisywanego wcześniej na blogu) mogą skorzystać z rozszerzenia ESS (Emacs Speaks Statistics). R ceniony jest za dojrzałość i stabilność. Stanowi pewien standard w środowisku statystyków. Często wykorzystywany jest też w innych dziedzinach nauki, np. biologii.

Wpis ten nie jest kursem R, a jedynie niewielkim pokazem możliwości środowiska R i pakietu Sweave. Mnóstwo informacji na temat R‑project znajduje się w internecie (również w języku polskim). Ze swojej strony polecam dwie świetne pozycje wydanictwa O'REILLY: R Cookbook oraz R in a Nutshell.

Instalacja i pierwsze uruchomienie

Wymagania: Zainstalowane środowisko LaTeX, np. MiKTeX dla Windows.

Instalacja R w środowisku Windows nie wyróżnia się niczym szczególnym. Pobieramy instalator i instalujemy podobnie jak inne programy. Sweave jest aktualnie częścią pakietu R.

Sweave

Sweave można zapisać matematycznie jako Sweave = R . LaTeX, gdyż jest to w pewnym sensie złożenie R i LaTeX-a. Ściśle rzecz ujmując, Sweave jest narzędziem, które pozwala na osadzenie kodu R w dokumentach LaTeX. Celem Sweave jest tworzenie dynamicznych raportów, które są automatycznie aktualizowane, jeśli dane lub przeprowadzana analiza ulega zmianie.

Dokumenty Sweave posiadają zazwyczaj rozszerzenie .Rnw, .rnw, .Snw, .snw. Fragmenty kodu R zawarte w tych plikach są wykonywane w R, a rezultaty, wykresy, tabele itp. automatycznie wstawiane w końcowym dokumencie -- czyli pliku .tex, który wystarczy skompilować przy pomocy LaTeX-a.

Zasada działania polecenia Sweave:

foo.snw -> (Sweave) -> foo.tex -> (PDFLaTeX) -> foo.pdf

Fragmenty kodu R zaczynamy od znacznika <<name>>= lub po prostu <<>>=, a kończymy znakiem @. Nazwane fragmenty kodu możemy wykorzystać ponownie przy pomocy <<name>>. Cała reszta dokumentu jest traktowana przez R jako komentarz.

Innym sposobem zapisu (bardziej intuicyjnym dla użytkowników LaTeX-a) są znaczniki \begin{Scode} \end{Scode} (Scode, ponieważ R jest dialektem języka S). Pliki uwzględniające tę formę zapisu posiadają najczęściej rozszerzenie .Stex.

Ten opis powinien wystarczyć, aby rozpocząć pracę ze Sweave. Cała reszta to kwestia nauki LaTeX-a i R. Jeśli znasz już podstawy LaTeX-a szybko odkryjesz moc i wygodę drzemiącą w R.

Zalety Sweave

* Powtarzalność wyników * Efektywność * Niezawodność

Sweave wpisuje się w koncepcję Literate programming, o której była już mowa na tym blogu.

Przykład

Teorię najlepiej zrozumieć na przykładzie. Prześledźmy zatem najczęściej przytaczany przykład.

\documentclass[a4paper]{article}

\title{Sweave Example 1}
\author{Friedrich Leisch}

\begin{document}

\maketitle

In this example we embed parts of the examples from the
\texttt{kruskal.test} help page into a \LaTeX{} document:

<<>>=
data(airquality)
kruskal.test(Ozone ~ Month, data = airquality)
@
which shows that the location parameter of the Ozone 
distribution varies significantly from month to month. Finally we
include a boxplot of the data:

\begin{center}
<<fig=TRUE,echo=FALSE>>=
boxplot(Ozone ~ Month, data = airquality)
@
\end{center}

\end{document}

Przykład a) plik Snw

To samo przy użyciu znaczników Scode możemy zapisać jako:

\documentclass[a4paper]{article}

\title{Sweave Example 1}
\author{Friedrich Leisch}

\begin{document}

\maketitle

In this example we embed parts of the examples from the
\texttt{kruskal.test} help page into a \LaTeX{} document:

\begin{Scode}
data(airquality)
kruskal.test(Ozone ~ Month, data = airquality)
\end{Scode}
which shows that the location parameter of the Ozone 
distribution varies significantly from month to month. Finally we
include a boxplot of the data:

\begin{center}
\begin{Scode}{fig=TRUE,echo=FALSE}
boxplot(Ozone ~ Month, data = airquality)
\end{Scode}
\end{center}

\end{document}

Przykład b) Plik Stex

Opcja echo=FALSE oznacza, że fragment ten nie będzie zawarty w wynikowym pliku.

Zapisujemy przykład w wybranym katalogu, uruchamiamy R i wpisujemy polecenie:

Sweave("C:\\Users\\Krystian\\Desktop\\raport\\example-1.Snw")

uwzględniając właściwą ścieżkę. Po wciśnięciu klawisza Enter powinien pojawić się rezultat jak na zrzucie ekranu poniżej:

W wyniku działania polecenia w katalogu Dokumenty powstają dwa pliki: plik tex oraz plik pdf z wykresem.

Otwieramy plik tex w ulubionym edytorze LaTeX-a, kompilujemy przy pomocy PDFLaTeX i...

! LaTeX Error: File `Sweave.sty' not found.

Spokojnie, bez paniki;) Plik Sweave.sty znajduje się w katalogu R. Zwykle jest to  [code]C:\Program Files\R\R-2.13.0\share\texmf\tex\latex\[/code] Skopiuj go do tego samego folderu, w którym znajduje się źródło .tex wygenerowane przez polecenie Sweave, czyli domyślnie Dokumenty w systemie Windows Vista/7.

Po kompilacji otrzymujemy następujący plik PDF.

Bonus

Programistów/hobbystów programowania w języku Python może zainteresować pakiet Pweave oraz pyreport. Literate programming with Python.