R4SEO: Automatisierte Reports mit R generieren (Teil 5/5)

In den vorausgehenden Teilen dieser Serie haben Sie alle Datentransformationen und -visualisierungen in „normalen" R-Skripten vorgenommen (Dateien die auf .R enden). Eine Besonderheit von R bzw. RStudio ist, dass es einen weiteren Dateityp zur Verfügung stellt – das sogenannte R-Markdown (Dateiendung .Rmd). R-Markdown bietet die Möglichkeit, R-Code und Markdown (Texte mit einfacher Formatierung) in einem Skript zu vereinen, welches dann in verschiedenen Formaten exportiert werden kann. So lassen sich HTML-, Word- und PDF-Dokumente, aber auch PowerPoint-Präsentationen und sogar Dashboards, Websites und ganze Bücher erstellen. Oder eben ein R-Notebook, welches im Grunde ein HTML-Dokument mit einigen zusätzlichen interaktiven Funktionen ist.

Für den hier beschriebenen Report werden Sie ein HTML-Dokument generieren, da es die denkbar einfachste Variante ist. Grundsätzlich sind Ihnen aber ob der mannigfaltigen Export-Formate kaum Grenzen gesetzt. Das zugrunde liegende Konzept bleibt dabei immer das gleiche: Der Code, der die darzustellenden Daten erzeugt, und der die Darstellungen beschreibende Text liegen immer in einem Dokument vor. Dadurch ergeben sich insbesondere zwei Vorteile hinsichtlich der Nachvollziehbarkeit und Reproduzierbarkeit aller mittels R-Markdown erstellten Dokumente. 1) Der Code ist nicht versteckt, sondern unmittelbar sichtbar. Sollten Sie zu einem späteren Zeitpunkt im Detail nachvollziehen wollen, wie bestimmte Daten für ein Diagramm o. Ä. aufbereitet wurden, müssen Sie nicht lange suchen. 2) Da es sich weiterhin um ein Skript handelt, kann es zu jedem beliebigen Zeitpunkt erneut ausgeführt werden. Von diesem Vorteil machen Sie beim zu erstellenden Report Gebrauch, denn im Grunde werden Sie immer wieder dasselbe Export-Dokument generieren – nur eben mit aktualisierten Daten, die automatisch von den APIs abgefragt werden.

Wie müssen Sie sich ein solches R-Markdown-Dokument resp. R-Notebook nun konkret vorstellen?

Einführung in R-Notebooks

Um eine Vorstellung von so einem Notebook zu bekommen, legen Sie am besten einfach eines an. Innerhalb Ihres Projekts, das Sie bisher auch verwendet haben, navigieren Sie in der Menü-Leiste von RStudio zu Files → New File → R Notebook (Abbildung 1).

Im Panel des Code-Editors wird sich nun ein R-Notebook mit einer Beispiel-Befüllung öffnen (Abbildung 2; 1). Klicken Sie im oberen Bereich des Panels auf Preview (2). Es öffnet sich ein Speicher-Dialog. Speichern Sie das Dokument ruhig schon einmal als report.Rmd, da Sie es nachher mit Ihrem Code befüllen werden. Nach dem Speichern öffnet sich ein weiteres Fenster, das eine Vorschau des gerenderten Notebooks bietet (3).

Hier sehen Sie die wichtigsten Elemente, die ein R-Markdown-Skript auszeichnen. Am Anfang des Skripts werden zwei Meta-Daten im YAML-Form aufgeführt: zum einen der Titel des Dokuments, zum anderen das Ausgabe-Format. Ersteren sehen Sie auch in der Vorschau. Benutzen Sie ruhig das Dropdown-Menü des Preview-Buttons, um bspw. ein Word-Dokument zu erzeugen. Neben der Preview öffnet sich nun auch Word. Ändern Sie danach aber wieder das Format auf ein R-Notebook (output: html_notebook).

Im Anschluss an die Meta-Daten folgt klassisches Markdown. Sie erkennen einen gesetzten Link und einige kursiv formatierte Satzelemente.

Das Besondere an R-Markdown ist der nachfolgende sogenannte R-Code-Chunk. Alles, was in ```{r} ... ``` eingefasst ist, wird als R-Code ausgeführt. Im vorliegenden Chunk wird mittels plot(cars) ein Beispiel-Datenset geplottet. Um den Chunk auszuführen, klicken sie im rechten oberen Bereich auf den grünen Pfeil (Abbildung 3). Anders als sonst beim Plotting erscheint das Diagramm nun im Skript selbst. Drücken Sie erneut auf Preview (Shortcut-Tipp: Strg + Shift + K), aktualisiert sich die Vorschau und auch dort wird das Diagramm jetzt unterhalb des generierenden Code-Snippets angezeigt.

Was Sie hier sehen – das Nebeneinander von Code(-Output) und Text – nennt sich Literate Programming und geht auf die Idee von Donald E. Knuth zurück, Computerprogramme in einer Form zu schreiben, dass sie vor allem für Menschen lesbar sind. Im Wesentlichen greift R-Markdown zwei Aspekte dieses Paradigmas auf: 1) Quellcode und Kommentare können miteinander gemischt werden sowie 2) aus dem Programm und der Beschreibung kann automatisch eine lesbare Dokumentation mit Inhaltsverzeichnis, Verweisen etc. generiert werden. Übertragen auf das Anwendungsfeld explorativer Datenanalysen bietet R-Markdown damit die Möglichkeit, den gesamten Prozess der Datenbeschaffung, -transformation und -visualisierung sowie die darauf aufbauende Analyse in einem Dokument vorzunehmen. Nachvollziehbarkeit und Reproduzierbarkeit einer solchen Analyse sind damit zu jedem Zeitpunkt sichergestellt.

Sie werden im Nachfolgenden den Aspekt der Code-Darstellung ignorieren, denn bei Reports dürfte es die Empfänger herzlich wenig interessieren, wie die Diagramme und Tabellen erstellt wurden. Eine Möglichkeit, den Code auszublenden, sehen Sie bereits in Abbildung 3. Oberhalb eines jeden Code-Snippets findet sich ein Hide-Button, mit der der Code eingeklappt werden kann. Dies müssten Sie allerdings für jedes Snippet manuell machen. Es gibt zwar auch eine Option (klicken Sie dazu auf das Zahnrad-Symbol neben dem Preview-Button → Output-Options → Fold R code chunks → hide), alle Snippets standardmäßig einzuklappen. Allerdings wird der Button weiterhin angezeigt. Das geht auch eleganter. Aber der Reihe nach.

Überführung des bisherigen Codes in ein R-Notebook

Um nicht auf Beispiel-Daten und -Text zu arbeiten, werden Sie nun Ihren bisherigen Code, der in dem Skript visualization.R vorliegt, in das Notebook überführen. Sie werden dazu Schritt für Schritt vorgehen, da vereinzelt kleinere Ergänzungen vorgenommen werden müssen.

Löschen Sie zunächst den gesamten Beispiel-Inhalt des Notebook report.Rmd und beginnen Sie damit, die Meta-Angaben zu definieren (Abbildung 4; 1). Den Titel können Sie natürlich frei wählen. Sie sehen, dass html_notebook nun ebenfalls zwei untergeordnete Konfigurationselemente aufnimmt. Mittels CSS geben Sie den Pfad zu einer CSS-Datei an. Da das Output-Format HTML sein wird, können Sie es natürlich gänzlich via CSS Ihren Wünschen entsprechend anpassen. Die hier verwendete CSS-Datei (Abbildung 5) ist sehr simpel und enthält nur einige Anweisungen, die den Font verändern und die Überschriften unterstreichen. Um die CSS-Datei zu erstellen, gehen Sie über File → New File → Text File und speichern Sie die Datei als style.css in Ihrem aktuellen Working-Directory.

Weiterhin sehen Sie im YAML, dass toc: yes definiert wurde. Dadurch geben Sie an, dass basierend auf den Überschriften im Output-Dokument automatisch ein Inhaltsverzeichnis generiert werden soll. Das Ergebnis mit zwei vom Autor exemplarisch eingefügten Überschriften sehen Sie in Abbildung 6.

Unterhalb des YAML fügen Sie nun Ihren ersten Code-Chunk ein. Wenn Sie Strg + Alt + I (I wie Ida) drücken, fügt RStudio automatisch ein Chunk-Template an der Stelle des Cursors ein. Innerhalb des Chunks definieren Sie (Abbildung 4; 2), dass keine Code-Snippets im Output-Dokument erscheinen sollen, das, was sie generieren – also bspw. Tabellen und Diagramme –, hingegen schon (echo = FALSE). Außerdem unterdrücken Sie die Ausgabe aller Benachrichtigungen (message = FALSE) und Warnungen (warning = FALSE). Benachrichtigungen treten beispielsweise beim Laden von Packages auf. Normalerweise würden sie auf der Console ausgegeben werden. Im Kontext eines R-Notebooks werden sie allerdings unterhalb des verursachenden Code-Chunks angezeigt und wären somit schließlich auch im Output-Dokument vorhanden. Das ist natürlich nicht gewünscht.

Als Nächstes fügen Sie einen weiteren Chunk ein, in den Sie den gesamten Code für die Datenabfrage und -aufbereitung sowie die Definition der zu verwendenden Farbwerte kopieren (Abbildung 7).

Beachten Sie, dass Sie für diesen Chunk noch eine spezifischere Konfiguration der Ausgabe vornehmen müssen. Im vorherigen Chunk haben sie definiert, dass der Code aller Chunks des Notebooks nicht als Code-Snippet im Output-Dokument erscheinen soll (echo =  FALSE). Diese Einstellung unterdrückt allerdings nur das Code-Snippet, nicht die aus dem Code resultierenden Diagramme und Tabellen. Die wollen Sie schließlich in Ihrem Report sehen. Im aktuellen Chunk befinden sich allerdings die Abfragen der GSC- und GA-API, die während des Calls Informationen auf der Console resp. nun im Notebook ausgeben, die durch echo = FALSE nicht unterdrückt werden. Für den gesamten Code innerhalb des Chunks wollen Sie jedoch im Grunde, dass nur der Code ausgeführt, ansonsten aber nichts im Output-Dokument angezeigt wird. Um diese spezifischere Konfiguration vorzunehmen, klicken Sie das Zahnrad-Symbol an und wählen Sie bei Output → Show nothing (run code) aus (Abbildung 8). Sie sehen, dass am Anfang des Chunks nun {r include=FALSE}, also die spezifischere Output-Anweisung, die die globale überschreibt, eingefügt wurde.

Falls Sie es bisher noch nicht getan haben, führen sie die beiden Chunks aus (Shortcut: Strg + Alt + R) und nehmen Sie sich die Zeit, ein bisschen mit der Output-Konfigurationen der Chunks zu experimentieren.

Wenn Sie der Anleitung bis hierher gefolgt sind und die Preview des Notebooks anzeigen, sollten Sie nichts sehen – bis auf den Titel des Reports natürlich. Im Nachfolgenden beginnen Sie jetzt damit, den Code hinzuzufügen, der für die Generierung der Diagramme und Tabellen verantwortlich ist.

Einbinden der Plots und Tabellen in den Report

Als Erstes wollen Sie aber mit Sicherheit wissen, für welche Domain der Report eigentlich gilt und welchen Berichtszeitraum er abdeckt. Fügen Sie dazu den Satz aus Abbildung 9 in Ihr Notebook ein. Sie sehen, dass er nicht ```{R} ...``` eingefasst ist, da Sie nun reinen Text schreiben, bzw. nicht ausschließlich Text, denn innerhalb des Satzes finden Sie mit `r ...` umfasste Variablen, die Sie bereits kennen. Mit R-Markdown können Sie also auch Inline-Code-Chunks verwenden, die kurze R-Statements ausführen. In diesem Fall geben Sie einfach den Inhalt der Variablen wieder, die sie bereits zur Datenabfrage verwendet haben und die die Domain resp. das Start- und Enddatum des Berichtszeitraums enthalten.

Gerade in Reports – aber durchaus auch in Analysen – bieten diese Inline-Chunks eine willkommene Flexibilität. Stellen Sie fest, dass Sie immer wieder die gleichen Textbausteine verwenden, bei denen sich nur die Zahlenwerte ändern, tragen Sie Letztere einfach als Variablen ein, die sich mit jeder neuen Report-Generierung selbst aktualisieren. Klassische Anwendungsfälle sind die exponierte Darstellung des aktuellen Sichtbarkeitsindexes oder Sätze wie: Das prozentuale Delta der Clicks zur Vorwoche beträgt: ...

GA- & GSC-Diagramme einbinden

Wie Sie einen Plot in R-Markdown einbinden, haben Sie bereits oben anhand der Beispiel-Befüllung des Dokuments gesehen. Sie müssen einfach nur den Code, der den Plot generiert, in einem Code-Chunk einfassen. Und genau das machen Sie nun für die Diagramme der Google-Analytics- und Google-Search-Console-Daten (Abbildung 10).

Damit die Diagramme einen automatischen Eintrag im Inhaltsverzeichnis erhalten, stellen sie den Code-Chunks jeweils eine Überschrift voran. Den einzufügenden Code kennen Sie bereits aus dem vorherigen Skript und dieser muss nicht angepasst werden. Führen Sie die Code-Chunks aus und sehen Sie sich die Preview des Dokumentes noch einmal an (Abbildung 11).

Tabellen einfügen und gestalten

Sie erinnern sich vielleicht, für die GSC-Daten haben Sie auch zwei Tabellen erstellt, die die Top-10-Pages resp. -Queries der Vorwoche aufführen. Diese werden sie als Nächstes im Report integrieren. Alles, was Sie dafür machen müssen, ist, die entsprechenden Variablen gsa_top_10_pages und gsa_top_10_queries in separate Code-Chunks einzufassen (Abbildung 12). Führen Sie auch diese Chunks aus und gucken Sie sich erneut den Output in der Preview an.

In Abbildung 13 sehen Sie oberhalb der Tabelle einen Satz, der kurz die zugrunde liegende Datenbasis beschreibt (1). Die ISO-Kalenderwoche fügen Sie hier erneut mittels Inline-Chunk ein, um sie nicht jedes Mal manuell anpassen zu müssen. Dann gibt es noch einige Elemente in der Tabelle, die etwas Politur bedürfen. Zum einen wird unterhalb der Spaltenüberschriften der Datentyp ausgewiesen (2). Der dürfte nun wirklich niemanden interessieren. Zum anderen werden die Zahlen aktuell ohne Tausender-Trennzeichen (3) und mit englischem Dezimal-Trennzeichen (4) dargestellt. Zum Schluss sehen Sie bei (5), dass die Tabelle paginiert ist. Standardmäßig gibt R-Markdown beim Rendern von Tabellen zehn Zeilen je Seite aus. In der aktuellen HTML-Vorschau können Sie hier dynamisch durchblättern. Wenn Sie allerdings ein PDF erzeugen möchten, geht das natürlich nicht. (Hinweis: Ihre Tabelle kann durchaus nur zehn Zeilen enthalten, immerhin geht es hier um die Top-10. Dass im Beispiel elf Zeilen ausgegeben werden, ist dem Umstand geschuldet, dass zwei Seiten fünf Clicks aufweisen.)

Sie möchten Ihre Tabelle also noch etwas formatieren. Die zugrunde liegende Rendering-Engine knitr, die das R-Markdown-Skript in das gewünschte Output-Format überträgt, bietet dazu einige rudimentäre Optionen, die für dieses Beispiel genügen sollen. Wollen Sie Ihre Tabellen auch farblich, mit Icons oder sogar konditional formatieren, schauen Sie sich das Package kableExtra an (http://haozhu233.github.io/kableExtra/).

In Abbildung 14 sehen Sie den um die Tabellen-Formatierung ergänzten Code. knitr::kable lädt die benötigte Funktion aus dem Package. Als erstes Argument wird die zu formatierende Tabelle definiert. Im Anschluss geben Sie format = "markdown" an, wodurch die Paginierung unterdrückt wird. Innerhalb der format.args folgen dann die von Ihnen gewünschten Tausender- und Dezimal-Trennzeichen. Zum Schluss runden Sie alle Werte der Tabelle auf zwei Nachkommastellen (digits = 2) – erkennbar bei der CTR. Sie erinnern sich vielleicht, dass Sie die Werte der Tabelle bereits weiter oben im Skript mittels round() gerundet haben. Das Runden diente dort der Vorstellung der Funktion. Im Allgemeinen ist es sinnvoller, die Repräsentation der Daten erst beim Rendern zu formatieren, statt die zugrunde liegenden Daten selbst zu manipulieren.

Einbinden des Sistrix-Plots

Nun bleibt nur noch das Diagramm des Sistrix-Sichtbarkeitsindexes übrig. Wie Sie dieses einbinden, dürfte sie an dieser Stelle nicht mehr überraschen und ist in Abbildung 15 zu sehen.

Report via E-Mail verschicken

Fertig! Sie haben nun ein Skript erstellt, dass automatisch verschiedene APIs anfragt und die Daten in einem HTML-Report aufbereitet. Fertig? Nicht ganz. Sie möchten das Skript natürlich nicht jede Woche manuell anstoßen, sondern hätten den Report gern morgens, wenn Sie ins Büro kommen, bereits in Ihrem E-Mail-Postfach liegen.

Um das Skript automatisch auszuführen und per E-Mail zu verschicken, benötigen Sie nun noch zwei Komponenten. Zum einen ein Mail-Skript, das das Report-Skript ausführt und das gerenderte Output-Dokument per Mail verschickt, zum anderen einen Trigger, der wiederum das Mail-Skript zu einem bestimmten Zeitpunkt anstößt.

Beginnen Sie mit dem Mail-Skript, indem sie ein neues R-Skript erzeugen und mit mail_skript.R benennen. Der Inhalt des Mail-Skripts ist in Abbildung 16 zu sehen. Zunächst laden Sie das Package mailR, mit dem Sie – wie Sie sich wahrscheinlich schon gedacht haben – Mails verschicken können (1). Wahrscheinlich müssen Sie das Package zunächst noch via install.packages("mailR") installieren. Im Anschluss (2) laden Sie die Funktion render() aus dem rmarkdown-Package und geben als erstes Argument das zu rendernde Report-Skript an. Das Argument encoding = "utf-8" sorgt dafür, dass bspw. Umlaute erhalten bleiben. sender nimmt die Mail-Adresse des Versenders auf und recipients einen oder mehrere Empfänger (3). In der Funktion send.mail() (4) definieren Sie noch den Betreff, den Mail-Inhalt, den anzuhängenden Report sowie Ihre Zugangsdaten.

Wie funktioniert das Mail-Skript nun genau? Beim Ausführen wird zunächst das Report-Skript gerendert und das Output-Dokument in Ihrem Working-Directory abgespeichert. Führen Sie ruhig die Render-Funktion manuell aus. Sie sehen auf der Console, dass das R-Markdown-Skript durchläuft. In Ihrer Datei-Übersicht sehen Sie das gespeicherte Output-Dokument report.nb.html. Letzteres geben Sie in der Mail-Funktion als Anhang an (attach.files).

Als Trigger zur Ausführung verwenden Sie schließlich den Windows-Aufgabenplaner. Rufen Sie diesen auf, klicken Sie in der Navigation auf Aktion → Aufgabe erstellen ...  Im ersten Reiter Allgemein des Konfigurations-Dialogs vergeben Sie eine Benennung der Aufgabe wie bspw. R_report. Im zweiten Reiter Trigger definieren Sie, zu welchem Zeitpunkt die Aufgabe laufen soll – etwa jede Woche Mittwoch um 01:00 Uhr. Zu diesem Zeitpunkt muss Ihr Computer natürlich an sein. Unter Aktionen legen Sie eine neue Aktion: Programm starten an (Abbildung 17). Bei Programm/Skript geben Sie den Pfad Rscript.exe an, als Argument des Programms das gerade von Ihnen erstellte mail_skript.R. Starten in definiert, wo das Mail-Skript liegt. Klicken Sie nun auf OK, um die Konfiguration abzuschließen. In der Übersicht sehen Sie nun die erstellte Aufgabe. Um sie zu testen, können Sie sie mit der rechten Maustaste anklicken und Ausführen. Hat alles geklappt, erscheint ein CMD-Fenster, in dem die Ausführung des Skripts angezeigt wird und das sich nach dem Versand der Mail automatisch wieder schließt.