R-Visualisierungen

Hinweis

R-Visualisierungen befinden sich momentan noch im Aufbau. Die genauen Datenformate etc. können sich noch ändern.

R-Visualisierungen stellen eine einfache Möglichkeit dar, um das OLAP-Analyse-Modul von MUSTANG um neue Visualisierungen zu erweitern. Hierzu wird das Ergebnis einer OLAP-Abfrage an eine R-Funktion übergeben, die daraus neue Ergebnisse berechnet und diese als Tabelle oder Grafik MUSTANG zur Verfügung stellt.

In diesem Artikel wird die grundlegende Struktur einer R-Visualisierung für MUSTANG beschrieben. Wie eine R-Visualisierung in MUSTANG verfügbar gemacht werden kann, ist in Artikel MUSTANG-Profile beschrieben.

Tipp

Im Download-Bereich stehen einige R-Visualisierungen zum Ausprobieren bereit.

Struktur

Jede Visualisierung besteht aus einem eigenen Ordner, dessen Name frei gewählt werden kann. Darin befinden sich mindestens folgende beiden Dateien:

plugin.json - Diese Datei enthält sämtliche Metadaten, beispielsweise die Achsenbeschriftungen in MUSTANG, die verfügbaren Einstellungen, etc.
script.r - Diese Datei enthält das eigentliche R-Skript, das ausgeführt wird

Außerdem kann der Visualisierungsordner noch eine Datei enthalten, die das Logo der Visualisierung enthält. Der Dateiname kann frei gewählt werden.

Tipp

Das Visualisierungslogo muss im PNG Format vorliegen und sollte eine Größe von 48x48 Pixeln aufweisen. Wenn kein Icon vorliegt, wird die Visualisierung stattdessen mit einem Standard-Logo versehen.

plugin.json

Im Folgenden ist die plugin.json-Datei für einen Alluvial-Plot beispielhaft dargestellt:

{
    "caption": "Aluvial",
    "description": "Alluvial Plot",
    "rowAxisCaption": "Daten",
    "columnAxisCaption": "Daten 2",
    "pageAxisCaption": "Daten 3",
    "iconPath": "icon.png",
    "settingCategories": {
        "layout": {
            "caption": "Layout",
            "settings": {
                "alpha": {
                    "caption": "Alpha",
                    "description": "Alpha",
                    "type": {
                        "kind": "double",
                        "min": 0,
                        "max": 1,
                        "defaultValue": 0.5
                    }
                },
                "blocks": {
                    "caption": "Blöcke",
                    "description": "Blöcke",
                    "type": {
                        "kind": "enumeration",
                        "values": [
                            {
                                "value": "TRUE",
                                "caption": "Ja"
                            },
                            {
                                "value": "FALSE",
                                "caption": "Nein"
                            },
                            {
                                "value": "bookends",
                                "caption": "An den Enden"
                            }
                        ]
                    }
                },
                "color_theme": {
                    "caption": "Farben",
                    "description": "Farben",
                    "type": {
                        "kind": "colorTheme"
                    }
                },
                "title": {
                    "caption": "Titel",
                    "description": "Titel",
                    "type": {
                        "kind": "string"
                    }
                }
            }
        }
    }
}

Die JSON-Datei enthält auf oberster Ebene folgende Eigenschaften:

Eigenschaft	Beschreibung
`caption`	Der Name der Visualisierung, der in MUSTANG angezeigt wird
`description`	Beschreibung der Visualisierung. Wird in MUSTANG als Tooltip angezeigt
`rowAxisCaption`	Die Beschriftung der Zeilenachse in MUSTANG
`columnAxisCaption`	Die Beschriftung der Spaltenachse in MUSTANG
`pageAxisCaption`	Die Beschriftung der Blätterachse in MUSTANG
`iconPath`	Der Pfad zur Datei mit dem Logo der Visualisierung
`settingCategories`	Liste, die die Einstellungskategorien, die in MUSTANG angezeigt werden, enthält
`sorting`	Der Sort-Index, um die Position in der Visualisierungsliste festzulegen

Im folgenden Bild ist beispielhaft eine Einstellungskategorie Layout dargestellt:

Einstellungskategorien bei OLAP-Visualisierungen

Jede Einstellungskategorie enthält auf oberster Ebene folgende Eigenschaften:

Eigenschaft	Beschreibung
`caption`	Der Name der Einstellungskategorie, der in MUSTANG angezeigt wird
`settings`	Liste mit Einstellungen, die in der Kategorie enthalten sind

Im folgenden Bild sind beispielhaft die in der Einstellungskategorie Layout enthaltenen Einstellungen dargestellt:

Einstellungen bei OLAP-Visualisierungen

Eine Einstellung kann einen der folgenden Typen besitzen:

int - Eine Ganzzahl
double - Eine Fließkommazahl
colorTheme - Ein Farbschema
string - Eine Zeichenkette
bool - Ein boolscher Wert
enumeration - Eine Auswahlliste

Jede Einstellung besitzt folgende Eigenschaften:

Eigenschaft	Beschreibung
`caption`	Der Anzeigename der Einstellung in MUSTANG
`description`	Die Beschreibung der Einstellung
`type`	Ein Typ-Objekt das den Einstellungstyp definiert

Das Typ-Objekt enthält immer folgende Eigenschaft:

Eigenschaft	Beschreibung
`kind`	Der Typ der Einstellung. Einer der Werte aus der vorherigen Liste

Wenn kind den Wert int oder double enthält, können noch folgende Eigenschaften im Typ-Objekt definiert werden:

Eigenschaft	Beschreibung
`min`	Der minimale Wert, den die Einstellung annehmen darf
`max`	Der maximale Wert, den die Einstellung annehmen darf
`defaultValue`	Der Standardwert, den die Einstellung annimmt

Wenn kind den Wert colorTheme enthält, können keine weiteren Eigenschaften im Typ-Objekt definiert werden.

Wenn kind den Wert string enthält, kann noch folgende Eigenschaft im Typ-Objekt definiert werden:

Eigenschaft	Beschreibung
`multiline`	Legt fest, ob die Zeichenkette mehrere Zeilen umfassen darf
`defaultValue`	Der Standardwert, den die Einstellung annimmt

Wenn kind den Wert enumeration enthält, kann noch folgende Eigenschaft im Typ-Objekt definiert werden:

Eigenschaft	Beschreibung
`defaultValue`	Der Standardwert, den die Einstellung annimmt
`values`	Liste, der erlaubten Auswahlmöglichkeiten

Eine Auswahlmöglichkeit enthält folgende Eigenschaften:

Eigenschaft	Beschreibung
`caption`	Der Anzeigename der Auswahlmöglichkeit, der in MUSTANG angezeigt wird
`value`	Der Wert der Auswahlmöglichkeit, der an das R-Skript übergeben wird

script.r

Das eigentliche R-Skript befindet sich in der Datei script.r und kann folgendermaßen aufgebaut werden:

## Benötigte R-Pakete
library(...);

## Einstellungen
if(exists("layout_color_theme")){
  colors <- layout_color_theme
}
alpha_value <- 0.5
if(exists("layout_alpha")){
  alpha_value <- layout_alpha
}

...

## Voraussetzungen prüfen
fctr.cols <- sapply(inputMetadata, is.factor)
inputMetadata[, fctr.cols] <- sapply(inputMetadata[, fctr.cols], as.character)
measure <- inputMetadata[inputMetadata["isMeasure"] == TRUE,]$column
if (length(measure) != 1 || !is.character(measure) || measure == '') {
    stop("Mehr als eine oder keine Kennzahl definiert")
}
hierarchies <- which(names(inputData) != measure)
if(length(hierarchies)<2){
  stop("Weniger als zwei Hierarchien definiert")
}

...

## Plotten
alluvial(inputData[, hierarchies], freq= inputData[, measure], col=inputData$color, gap.width = gap_width,blocks = blocks,alpha = alpha_value);
if(!is.na(title)&& title!= ""){
    title(main=title)
}

Dem R-Skript werden die beiden DataFrames inputData und inputMetadata, sowie die Einstellungen bereitgestellt. inputData enthält die zu visualisierenden Daten. inputMetadata enthält Metadaten zu den einzelnen Spalten in inputData. Das Format von inputMetadata sieht wie folgt aus:

Spalte	Beschreibung
`column`	Name der Spalte in `inputData`
`role`	Achse, auf der die Spalte in MUSTANG aufgetragen wurde. Mögliche Werte sind `Rows`, `Columns`,`Pages` oder `Slicer`
`isMeasure`	`TRUE`, wenn es sich bei der Spalte um eine Kennzahl handelt, ansonsten `FALSE`

Wenn die Voraussetzungen für das Skript nicht erfüllt sind, kann mit Hilfe der stop-Funktion, die Ausführung abgebrochen werden. Die Zeichenkette, die der Funktion übergeben wird, wird in MUSTANG als Fehlermeldung ausgegeben.

Alles was geplottet wird, wird in MUSTANG als Ergebnis dargestellt. Alle Dataframes, die mit result_ beginnen, werden in MUSTANG als Tabelle in einem eigenen Blatt ausgegeben.