====== 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 [[:de:results:analyses]].

**Hinweis:** Das Zusatzmodul "Automatisierte Datenauswertung" ist nur auf dem Befragungsserver [[https://s2survey.net|s2survey.net]] verfügbar, nicht auf dem Befragungsserver [[https://www.soscisurvey.de|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.


===== Bedienoberfläche =====

Ergebnisberichte werden ähnlich wie [[de:create:questionnaire|Fragebögen]] seitenbasiert erstellt. Das heißt, jede Seite wird für sich angelegt. Nach dem Wechsel in den [[:de:results:analyses|Auswertungsmodus]], dem Klick auf **Ergebnisberichte** und auf //Neuen Bericht vorbereiten// erscheint die Oberfläche zum Erstellen von Ergegebnisberichten.

{{ :de:results:scr.report.basic.png?nolink | Oberfläche zum Erstellen von Ergegebnisberichten}}

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 ({{::button.play.png?nolink|Vorschau}}), Verwaltung und die Einstellungen ({{::button.settings2.png?nolink|Einstellungen}}). In den Einstellungen kann man dann u.a. auch die //Kennung// und //Beschreibung// des Ergebnisberichts anpassen.

Daruntern 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.


===== Inhalte auf einer Seite platzieren =====

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...

<code php>
add(
  text('Hallo Welt')
);
</code>

... und klicken Sie auf den Knopf für die Vorschau ({{::button.play.png?nolink|Vorschau}}) oder (weiter unten) den Knopf für die Seiten-Vorschau ({{::button.play-here.png?nolink|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:

<code php>
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.')
);
</code>

"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).

<code php>
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
  ]
);
</code>

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


===== Elemente =====

Oben wurde bereits die Funktino ''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.
  * ''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 Darstellungparameter ü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.

<code php>
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
  ]
);
</code>

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

<code php>
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]
);
</code>

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:


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


===== Die Seitenvorlage =====

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

  - Legen Sie hier allgemeine Seitenränder fest.
  - Definieren Sie hier die Standard-Schriftart und -größe für das weitere Dokument.
  - Elemente, die Sie hier mittels ''add()'' einbinden erscheinen auf allen Seiten des Ergebnisberichts.
  - Elemente, die mittels ''template()'' eingebunden werden erscheinen auf allen Seiten auch wenn diese mehrere Seiten in Anspruch nehmen.
  - 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 'AlArabiya', 'Furat', '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()''.

<code php>
set('family', 'Jura');
set('title.family', 'Helvetica');
</code>

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:

<code php>
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']
    )
  );
}
</code>

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:

<code php>
$content = pgContent('Grundlagen');

addToBox(
  $content,
  content('desc-basics')
);

add($content);
</code>

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

<code php>
pgTitle('1. Grundlagen', 'report.title01.jpg');
</code>


===== SVG-Grafiken =====

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

  - Sie erscheinen auch im Ausdruck des PDFs noch gestochen scharf.
  - 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:

<code php>
$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),
  ['x' => 0, 'y' => 40, 'width' => 150]
);
</code>

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.


===== Daten aus der Befragung =====

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.


==== Feedback für den Teilnehmer ====

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:

<code php>
replace('%reportURL%', reportURL('report'));
text('button_report');

option('nextbutton', false);
option('breakbutton', false);
option('progress', false);
</code>

Dazu passend der Textbaustein "button_report":

<code html>
<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>
</code>

Es ist mitunter hilfreich, [[:de:general:indices|Skalenindizes]] bereits im Fragebogen mittels ''[[:de:create:functions:valuemean]]'' zu berechnen und mittels ''[[:de:create:functions: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 ({{:button.settings2.png?nolink|Einstellungen}}) einen Fall (CASE) definieren, der für die Vorschau verwendet wird.


==== Ergebnisbericht zur Befragung ====

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

Dann sollen vielleicht [[:de:results:analyses#definition_von_teilgruppen|Teilgruppen für die Analyse]] definiert weden. 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//.


===== Weitere PHP-Funktionen =====

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

  * ''[[:de:create:functions:debug]]'' -- Zur Anzeige von Debugging-Inhalten in der Vorschau.
  * ''[[:de:create:functions:getlanguage]]'' -- Für mehrsprachige Feedback-Ergebnisberichte.
  * ''[[:de:create:functions:dbget]]''
  * ''[[:de:create:functions:value]]''
  * ''[[:de:create:functions:valuemean]]''