Automatisierte Ergebnisberichte

SoSci Survey bietet mit dem Zusatzmoduls „Automatisierte Datenauswertung“ die Möglichkeit, auf Basis der erhobenen Daten einen Ergebnisbericht als PDF zu erstellen. Diese kann die Ergebnisse für einen einzelnen Datensatz zeigen (Teilnehmer-Auswertung) und/oder Statistiken über alle erhobenen Daten aufbereiten (Kunden-Report).

Wichtig: Die Programmierung eines Ergebnisberichts ist mit einem gewissen Aufwand verbunden. Die Verwendung des Ergebnisberichts wird nur dann empfohlen, wenn der Bericht häufig/wiederkehrend erstellt werden muss. Für eine einfache deskriptive Auswertung gibt es die Funktion Datenauswertung online.

Hinweis: Das Zusatzmodul „Automatisierte Datenauswertung“ ist nur auf dem Befragungsserver s2survey.net verfügbar, nicht auf dem Befragungsserver www.soscisurvey.de.

Hinweis: Die Funktion zum automatisierten Erstellen von Ergebnisberichten befindet sich noch in der Entwicklung und wird nur nach gesonderter Freischaltung im Menü angezeigt. Bitte kontaktieren Sie den Server-Betreiber, wenn Sie die Funktion nutzen möchten.

Ergebnisberichte werden ähnlich wie Fragebögen seitenbasiert erstellt. Das heißt, jede Seite wird für sich angelegt. Nach dem Wechsel in den Auswertungsmodus, dem Klick auf Ergebnisberichte und auf Neuen Bericht vorbereiten erscheint die Oberfläche zum Erstellen von Ergebnisberichten.

Ganz oben steht zunächst eine Kennung für den Ergebnisbericht (im Bild „report01“), eine Beschreibung und rechts die Knöpfe für die Vorschau (), Verwaltung und die Einstellungen (). In den Einstellungen kann man dann u.a. auch die Kennung und Beschreibung des Ergebnisberichts anpassen.

Darunter ist eine Leiste, welche die einzelnen Seiten des Ergebnisberichts symbolisiert. Verweilen Sie mit dem Mauszeiger über einer der Seiten, um davor/dahinter eine neue Seite einzufügen oder die Seite zu löschen.

Links von Seite 1 ist eine weitere Seite – die Vorlage für alle anderen Seiten. Hier können der Titel des Reports, die Ausrichtung (Hoch- oder Querformat) und ggf. Seitenränder festgelegt werden. Außerdem können hier PHP-Funktionen definiert werden, die auf allen anderen Seiten zur Verfügung stehen.

Hinweis: Aktuell können Ergebnisberichte ausschließlich mittels PHP-Code erstellt werden. Langfristig ist geplant, dass Inhalte auch direkt per Drag&Drop auf den Seiten platziert werden.

Die wichtigste PHP-Funktion für Ergebnisberichte ist add(). Sie fügt ein Element – etwa einen Textbaustein oder eine Grafik – auf der Seite ein. Tragen Sie folgenden PHP-Code auf der Seite ein…

add(
  text('Hallo Welt')
);

… und klicken Sie auf den Knopf für die Vorschau () oder (weiter unten) den Knopf für die Seiten-Vorschau (). Der Browser wird Ihnen nun eine PDF-Datei zum Download anbieten oder herunterladen, die eine Seite enthält mit dem Text „Hallo Welt“ links oben.

Sie können in der Funktion add() durch Komma getrennt auch weitere Inhalte auf der Seite platzieren:

add(
  text('Hallo Welt'),
  text('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
);

„Platzieren“ ist dabei etwas euphemistisch, denn bisher erscheinen die Inhalte links oben auf der Seite. In der Funktion add() können aber mit einem Array auch weitere Eigenschaften für den Anzeigebereich definiert werden. Zum Beispiel die Position des Anzeigebereichs (Alle Angaben in Millimetern).

add(
  text('Hallo Welt'),
  text('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.'),
  [
      'top' => 50,
      'left' => 50,
      'right' => 50
  ]
);

Hinweis: Die eckigen Klammern [] sind eine alternative Schreibweise für array().

Oben wurde bereits die Funktion text() verwendet, um einen Text direkt im Fragebogen einzubinden. Die folgenden Funktionen können innerhalb von add() verwendet werden:

• text() – Bindet einen Text ein.
• content() – Bindet einen Textbaustein ein, der unter Textbausteine u. Beschriftungen angelegt wurde. Hier ist in eingeschränktem Umfang auch HTML-Code möglich.
• image() – Bindet eine Grafik ein, z.B. PNG, JPG oder SVG.
• externalPage() – Bindet eine Seite aus einer PDF-Datei ein.
• spacing() – Sorgt für vertikalen Abstand zwischen zwei Elementen, als Parameter wird der Abstand im Millimetern angegeben.
• line() – Zeichnet einen Strich oder ein Polygon, als Parameter werden Koordinaten (jeweils als Array mit 2 Elementen) und eventuell weitere Darstellungsparameter übergeben.
• box() – Definiert einen neuen Anzeigebereich innerhalb des übergeordneten Anzeigebereichs und kann (optional) eine Hintergrund- und Rahmenfarbe haben.
• circle() – Zeichnet einen Kreis bzw. eine Ellipse in den definierten Anzeigebereich.

Der PHP-Code einer Seite könnte dann wie folgt aussehen. Dieser Code würde unter den bereits bekannten Texten 6 mm zusätzlichen Abstand lassen, darunter den Textbaustein mit Kennung „text01“ anzeigen und darunter – in einem weiteren Anzeigebereich – ein auf dem Kopf stehendes Dreieck zeichnen.

add(
  text('Hallo Welt'),
  text('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.'),
  spacing(5),
  content('text01'),
  box(
    line([10,10], [60,10], [30,50], [10,10]),
    ['top' => 50]
  ),
  [
    'top' => 60,
    'left' => 50,
    'right' => 50
  ]
);

Von der Funktion spacing() einmal abgesehen erlauben alle diese Funktionen die Angabe weiterer Darstellungsparameter mittels Array, z.B.

add(
  text('Text mit 15 Punkt, fett und grau',
    [
      'family' => 'Times',
      'size' => 15,
      'style' => 'b',  // b=bold, i=italic, u=underline, d=linethrough, o=overline
      'color' => '#7F7F7F'
    ]
  ),
  ['top' => 10, 'left' => 10]
);

Zeilenumbrüche und Einrückungen werden hier zur besseren Lesbarkeit verwendet. Es ist sehr empfehlenswert, auch den eigenen PHP-Code lesbar zu halten, prinzipiell sind die Umbrüche und Einrückungen aber optional:

add(
  text('Text mit 15 Punkt, fett und grau', ['size' => 15, 'style' => 'b', 'color' => '#7F7F7F']),
  ['top' => 10, 'left' => 10]
);

Nachfolgend einige Beispiele für weitere Elemente.

add(
    circle([
        'x' => 10,
        'y' => 10,
        'width' => 20,
        'height' => 20,
        'background-color' => '#FF9900'
    ]),
    line([10,10], [30,30], [
        'color' => '#000000',
        'size' => 2
    ])
);

Die Funktion content() kann auch Platzhalter im angezeigten Inhalt ersetzen.

add(
  content('TX01', [
    '%vorname%' => value('AB01_01'),
    '%nachname%' => value('AB01_02')
  ])
);

Links der ersten Seite kann die Seitenvorlage ausgewählt werden. Diese hat drei Funktionen:

1. Legen Sie hier allgemeine Seitenränder fest.
2. Definieren Sie hier die Standard-Schriftart und -größe für das weitere Dokument.
3. Elemente, die Sie hier mittels add() einbinden erscheinen auf allen Seiten des Ergebnisberichts.
4. Elemente, die mittels template() eingebunden werden erscheinen auf allen Seiten auch wenn diese mehrere Seiten in Anspruch nehmen.
5. PHP-Funktionen, die Sie hier definieren, stehen auf allen folgenden Seiten zur Verfügung.

Die Auswahl an Schriftarten ist eher überschaubar, denn damit Sie eine Schriftart im Ergebnisbericht verwenden können, muss diese auf spezielle Weise vorbereitet und in SoSci Survey eingebunden werden. Zur Verfügung stehen 'aeAlArabiya', 'Courier', die DejaVu-Familie ('DejaVuSans', 'DejaVuSansCondensed', 'DejaVuSans-ExtraLight', 'DejaVuSansMono', 'DejaVuSerif', 'DejaVuSerifCondensed'), 'Fabrikat', 'FreeMono', 'FreeSans', 'FreeSerif', 'Helvetica', 'Jura', 'OpenSans', 'OpenSansSemib', 'Raleway', 'Symbol' und 'Times'. Die Definition der Standard-Schriftart erfolgt mittels set().

set('family', 'Jura');
set('title.family', 'Helvetica');

Der Parameter 'family' setzt die Standard-Schriftart, 'title.family' den Standard für Überschriften. Mit 'line-height' kann die Zeilenhöhe (Standard 1.2) festgelegt werden. Schriftgröße (size), Stil (style) und Farbe (color) können einfacher direkt in das Formular auf der Vorlagen-Seite eingetragen werden.

Die dritte Funktion zum globalen Einbinden von Elementen mittels add() ist naheliegend: Hiermit können Sie eine Kopf- und/oder Fußzeile definieren, die auf allen Seiten erscheint.

Die vierte Funktion können Sie sehr flexibel einsetzen: Zum einen können Funktionen definiert werden, die z.B. Daten abrufen und/oder ein Chart zeichnen und auf den folgenden Seiten um Einsatz kommen.

Zum anderen können Sie unterschiedliche Vorlagen für unterschiedliche Seite definieren. Vielleicht soll die Standard-Kopfzeile mit Titel und Logo auf den meisten Seiten erscheinen, nicht aber auf zwischengeschalteten Titelseiten? Dann würden Sie z.B. zwei Funktionen wie folgt definieren:

function pgContent($title) {
  template(
      // Seitentitel
      text('Phantastischer Bericht', ['top' => 12, 'right' => 10, 'text-align' => 'right', 'style' => 'b', 'line-height' => 1]),
      text($title, ['right' => 10, 'text-align' => 'right']),
      // Seitennummer
      text('%pageNum%/%pageCount%', ['left' => 38, 'width' => 40, 'height' => 10, 'bottom' => 10, 'text-align' => 'left', 'vertical-align' => 'bottom', 'style' => 'B'])
  );
  // Box für Inhalt (muss vor dem add() noch befüllt werden)
  return box(
    ['left' => 40, 'top' => 50, 'bottom' => 25, 'right' => 10, 'border' => 0.0, 'multipage' => true]
  );
}
 
 
function pgTitle($title, $image) {
  add(
    image($image, ['left' => 0, 'top' => 0, 'height' => 215]),
    box(
      text($title, ['style' => 'b', 'top' => 10, 'left' => 36, 'size' => 28, 'color' => '#FFFFFF']),
      ['top' => 100, 'bottom' => 50, 'alpha' => 0.7, 'background-color' => '#FF9900', 'vertical-align' => 'top']
    )
  );
}

Die Funktionen für reguläre Seiten (hier pgContent() bezeichnet) liefert eine box() zurück, welche dann auf den eigentlichen Seiten mit Inhalt befüllt werden kann. Dafür kommt die Funktion addToBox() zum Einsatz:

$content = pgContent('Grundlagen');
 
addToBox(
  $content,
  content('desc-basics')
);
 
add($content);

Die Funktion für die Titelfolie (im Beispiel pgTitle()) erwartet lediglich den Titel und ein Bild, welches im Hintergrund der Seite platziert wird.

pgTitle('1. Grundlagen', 'report.title01.jpg');

SVG-Grafiken sind Vektor-Grafiken, sie können z.B. mit der Software InkScape erstellt werden. Vektor-Grafiken haben gegenüber Pixel-Grafiken (PNG, JPG) zwei große Vorteile:

1. Sie erscheinen auch im Ausdruck des PDFs noch gestochen scharf.
2. Sie können dynamisch manipuliert werden.

Für letzteres stehen in Ergebnisberichten die Funktionen svgPrepare() und svgSetStyle() zur Verfügung. Konkret können damit einzelne Elemente der Grafik ausgeblendet oder nach Bedarf eingefärbt werden. Dies erlaubt sehr ansprechende Charts oder z.B. das vom Befragungsergebnis abhängige Einfärben von Flussdiagrammen.

Die Funktionen werden wie folgt verwendet:

$svg = svgPrepare('chart.svg');
$scores = [
  'alpha' => round(value('IV01_01') / 5 * 100),
  'beta' => round(value('IV01_02') / 5 * 100),
  'gamma' => round(value('IV01_03') / 5 * 100)
);
foreach ($scores as $id => $score) {
  $color = getColor($score);
  svgSetStyle($svg, $id, ['fill' => $color]);
}
add(
  image($svg, [
      '%platzhalter%' => 'Text => Text'
  ]),
  [
      'x' => 0,
      'y' => 40,
      'width' => 150
  ]
);

In diesem Beispiel werden aus einem einzelnen Interview mittels value() die Werte in den Variablen „IV01_01“ bis „IV01_03“ ausgelesen. Anschließend werden sie von 0..5 auf 0..100 transformiert und dann wird mit einer (in der Vorlage definierten) Funktion getColor() aus dem Punktwert eine Farbe bestimmt, die anschließend mit der Funktion svgSetStyle() in die SVG-Elemente mit der ID „alpha“, „beta“ und „gamma“ geschrieben wird.

Die IDs der SCG-Elemente muss man vorab in InkScape manuell festlegen, damit svgSetStyle() sie findet. Zum Ausblenden von Elemente setzt man einfach deren Eigenschaft 'opacity' auf den Wert 0.

Zuletzt wird die angepasste Grafik mittels image() im Ergebnisbericht ausgegeben.

Oben wurde bereits gezeigt, dass mittels value() einzelne Daten aus dem Datensatz abgerufen werden können, so wie auch im Fragebogen selbst. Generell muss man zwei Arten von Daten unterscheiden:

• Daten zum aktiven Interview (Individual-Daten) – diese sind vor allem dann erforderlich, wenn man dem Teilnehmer ein individuelles Feedback geben möchte.
• Daten aus dem kompletten Datensatz oder einer Teilgruppe (Aggregat-Daten) – vor allem für Ergebnisberichte am Ende der Erhebung hilfreich.

Entsprechend den beiden Einsatzbereichen gibt es zwei Möglichkeiten, den Ergebnisbericht zu erzeugen. Entweder per Link im Fragebogen. Die Funktion report() (zur Verwendung unter Fragebogen zusammenstellen) erwartet die Kennung des Ergebnisberichts und liefert eine URL, welche dann im HTML-Code verwendet werden kann:

replace('%reportURL%', reportURL('report'));
text('button_report');
 
option('nextbutton', false);
option('breakbutton', false);
option('progress', false);

Dazu passend der Textbaustein „button_report“:

<p style="text-align: center;">
  <a href="%reportURL%" target="_blank" style="font-weight: bold; text-decoration: none; padding: 1em 0.5em; border: 2px solid;">
  Ihr Ergebnis herunterladen
  </a>
</p>

Es ist mitunter hilfreich, Skalenindizes bereits im Fragebogen mittels valueMean() zu berechnen und mittels put() in einer internen Variable abzuspeichern.

Im Ergebnisbericht stehen die Funktionen value() und valueMean() zur Verfügung, um Daten aus einem einzelnen Fall (CASE) abzurufen.

Zum Testen von Feedback-Ergebnisberichten können Sie in den Einstellungen des Ergebnisberichts () einen Fall (CASE) definieren, der für die Vorschau verwendet wird.

Für die Auswertung des Datensatzes können in den Einstellungen des Ergebnisberichts () zunächst einmal Auswahlkriterien definiert werden. Immerhin sollen ungültige Fälle (Abbrecher, Durchklicker) die Ergebnisse ja nicht verzerren.

Dann sollen vielleicht Teilgruppen für die Analyse definiert werden. Nachfolgend wird klar, weshalb man diesen eine Kennung geben kann (muss).

Für die Auswertung selbst stehen dann folgenden Funktionen zur Verfügung:

• int sampleSize([string GruppenKennung])
  Liefert die Anzahl der Teilnehmer (entsprechend den im Ergebnisbericht definierten Auswahlkriterien), entweder für den gesamten Datensatz oder für die Teilgruppe mit der Kennung GruppenKennung.
• int sampleBase(string VariablenKennung, [string GruppenKennung, boolean NegativeErlauben)
  Liefert die Anzahl gültiger Werte für die Variable mit der Kennung VariablenKennung in der Teilgruppe mit der Kennung GruppenKennung.
• float sampleMean(string VariablenKennung, [string GruppenKennung, boolean NegativeErlauben)
  Liefert den Mittelwert der Antworten bzw. Antwortcodes für die Variable mit der Kennung VariablenKennung.
• float sampleSD(string VariablenKennung, [string GruppenKennung, boolean NegativeErlauben)
  Liefert die Standardabweichung.
• array sampleFrequencies(string VariablenKennung, [string GruppenKennung])
  Liefert ein Array mit den Antworten oder Antwortcodes und der Häufigkeit.
• array sampleResponses(string VariablenKennung, [string GruppenKennung, boolean Sortieren, int MindestLänge, int MaximalLänge])
  Liefert eine Liste aller (offenen) Antworten auf die Variable mit der Kennung VariablenKennung.

Einige PHP-Funktionen stehen im Ergebnisbericht in gleicher Weise zur Verfügung wie beim Fragebogen zusammenstellen.

• debug() – Zur Anzeige von Debugging-Inhalten in der Vorschau.
• getLanguage() – Für mehrsprachige Feedback-Ergebnisberichte.
• dbGet()
• value()
• valueMean()
• stopCreate() – Steuerung, ob ein Ergebnisbericht erzeugt werden soll.