Automated Result Reports

With the additional module “Automated data evaluation”, SoSci Survey offers the possibility to create a result report as PDF based on the collected data. This can show the results for a single data set (participant evaluation) and/or prepare statistics on all data collected (customer report).

Important: The programing of a result report is associated with a certain effort. The use of the results report is recommended only if the report needs to be generated frequently/recurrently. For a simple descriptive analysis there is the function Online Data Analysis.

Note: The add-on module “Automated Data Analysis” is only available on the survey server s2survey.net, not on the survey server www.soscisurvey.de.

Note: The function for automated creation of result reports is still under development and will only be displayed in the menu after separate activation. BPlease contact the server operator if you want to use the feature.

Result reports are created in a page-based manner similar to questionnaires. This means each page is created on its own. After switching to Evaluation mode, clicking Result reports and clicking Prepare new report, the interface for creating result reports appears.

At the very top there is first an identifier for the result report (in the image “report01”), a description and on the right the buttons for preview (), administration and the settings (). In the settings you can adjust the identifier and description of the result report.

Below is a bar symbolizing the individual pages of the results report. Hover the mouse cursor over one of the pages to insert a new page before/behind it or to delete the page.

Left of page 1 is another page – the template for all other pages. Here you can define the title of the report, the alignment (portrait or landscape format) and, if necessary, page margins. In addition, PHP functions can be defined here, which are available on all other pages.

Note: Currently, result reports can only be created using PHP code. In the long term, it is planned that content will also be placed directly on the pages using drag & drop.

The most important PHP function for result reports is add(). It inserts an element – such as a text block or graphic – on the page. Enter the following PHP code on the page…

add(
  text('Hello World')
);

… and click the preview button () or (further down) the page preview button (). The browser will now offer you to download or download a PDF file containing a page with the text “Hello World” in the upper left corner.

You can also place additional content on the page in the add() function separated by commas:

add(
  text('Hello World'),
  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.')
);

“Placing” is a bit euphemistic here, because so far the content appears at the top left of the page. However, in the add() function, an array can also be used to define additional properties for the display area. For example, the position of the display range (All values in millimeters).

add(
  text('Hello World'),
  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
  ]
);

Note: The square brackets [] are an alternative notation for array().

Above, the function text() was already used to include a text directly in the questionnaire. The following functions can be used inside add():

• text() – Includes text.
• content() – Inserts a text module that was created under Text modules and labels. Here HTML code is also possible to a limited extent.
• image() – Inserts a grafic, e.g. PNG, JPG oder SVG.
• externalPage() – Inserts a page from a PDF file.
• spacing() – Provides vertical spacing between two elements, as a parameter the spacing is specified in millimeters.
• line() – Draws a line or a polygon, as parameters coordinates (each as array with 2 elements) and possibly further display parameters are passed.
• box() – Defines a new display area within the parent display area and can (optionally) have a background and border color.
• circle() – Draws a circle or an ellipse in the defined display area.

The PHP code of a page could then look like this. This code would leave 6 mm of additional space below the already known texts, display the text module with identifier “text01” below it, and draw an upside-down triangle below it – in another display area.

add(
  text('Hello World'),
  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
  ]
);

Apart from the function spacing() all these functions allow the specification of further display parameters by means of an array, e.g.

add(
  text('Text with 15 point, bold and gray',
    [
      'family' => 'Times',
      'size' => 15,
      'style' => 'b',  // b=bold, i=italic, u=underline, d=linethrough, o=overline
      'color' => '#7F7F7F'
    ]
  ),
  ['top' => 10, 'left' => 10]
);

Line breaks and indentations are used here for better readability. It is highly recommended to keep your own PHP code readable as well, but in principle the wraps and indents are optional:

add(
  text('Text with 15 point, bold and gray', ['size' => 15, 'style' => 'b', 'color' => '#7F7F7F']),
  ['top' => 10, 'left' => 10]
);

Below are some examples of other elements.

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

The function content() can also replace content, using placeholders.

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

On the left of the first page the page template can be selected. This has three functions:

1. Set general page margins here.
2. Define here the default font and size for the rest of the document.
3. Elements that you include here using add() will appear on all pages of the results report.
4. Elements that are included using template() appear on all pages even if they take up multiple pages.
5. PHP functions you define here will be available on all subsequent pages.

The choice of fonts is rather limited, because in order to use a font in the results report, it must be prepared and included in SoSci Survey in a special way. Available are 'aeAlArabiya', 'Courier', the DejaVu-family ('DejaVuSans', 'DejaVuSansCondensed', 'DejaVuSans-ExtraLight', 'DejaVuSansMono', 'DejaVuSerif', 'DejaVuSerifCondensed'), 'Fabrikat', 'FreeMono', 'FreeSans', 'FreeSerif', 'Helvetica', 'Jura', 'OpenSans', 'OpenSansSemib', 'Raleway', 'Symbol' and 'Times'. The definition of the default font is done using set().

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

The parameter 'family' sets the default font, 'title.family' sets the default for headings. With 'line-height' the line height (default 1.2) can be set. Font size (size), style (style) and color (color) can be entered more easily directly into the form on the template page.

The third function to globally include elements using add() is obvious: This allows you to define a header and/or footer that will appear on all pages.

You can use the fourth function very flexibly: On the one hand, functions can be defined which, for example, retrieve data and/or draw a chart and are used on the following pages

On the other hand, you can define different templates for different page. Maybe the default header with title and logo should appear on most pages, but not on intermediate title pages? Then, for example, you would define two functions as follows:

function pgContent($title) {
  template(
      // Pagetitle
      text('Phanstic report', ['top' => 12, 'right' => 10, 'text-align' => 'right', 'style' => 'b', 'line-height' => 1]),
      text($title, ['right' => 10, 'text-align' => 'right']),
      // pagenumber
      text('%pageNum%/%pageCount%', ['left' => 38, 'width' => 40, 'height' => 10, 'bottom' => 10, 'text-align' => 'left', 'vertical-align' => 'bottom', 'style' => 'B'])
  );
  // Box for content (has to be filled bevor add())
  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']
    )
  );
}

The functions for regular pages (here called pgContent()) returns a box(), which can then be filled with content on the actual pages. For this the function addToBox() is used:

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

The function for the title slide (in the example pgTitle()) expects only the title and an image, which is placed in the background of the page.

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

SVG graphics are vector graphics, they can be created e.g. with the software InkScape. Vector graphics have two major advantages over pixel graphics (PNG, JPG):

1. They still appear perfectly sharp in the printout of the PDF.
2. They can be manipulated dynamically.

For the last, the functions svgPrepare() and svgSetStyle() are available in result reports. In concrete terms, this allows individual elements of the graphic to be hidden or colored as required. This allows very appealing charts or e.g. the coloring of flowcharts depending on the survey result.

The functions are used as follows:

$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 this example, the values in the variables “IV01_01” to “IV01_03” are read from a single interview using value(). Afterwards they are transformed from 0..5 to 0..100 and then a function getColor() (defined in the template) is used to determine a color from the point value, which is then written to the SVG elements with the ID “alpha”, “beta” and “gamma” using the function svgSetStyle().

The IDs of the SCG elements have to be set manually in InkScape beforehand so that svgSetStyle() can find them. To hide elements, simply set their 'opacity' property to the value 0.

Finally, the adjusted graphic is output to the result report using image().

Above it was already shown that by means of value() single data can be retrieved from the dataset, as well as in the questionnaire itself. In general, it is necessary to distinguish between two types of data:

• Active interview data (Individual data) – these are especially needed if you want to give individual feedback to the participant.
• Data from the complete data set or a subset (aggregate data) – especially useful for results reports at the end of the survey.

According to the two fields of application, there are two ways to generate the result report. Either via link in the questionnaire. The function report() (for use under Compose questionnaire) expects the identifier of the result report and returns a URL, which can then be used in the HTML code:

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

Suitable for this is the text module “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;">
  download your result
  </a>
</p>

It is sometimes helpful to calculate scale indices already in the questionnaire using valueMean() and store them in an internal variable using put().

In the results report, the functions value() and valueMean() are available to retrieve data from a single case (CASE).

To test feedback result reports, you can define a case (CASE) in the result report settings () that will be used for preview.

For the evaluation of the data set, selection criteria can first be defined in the settings of the result report (). After all, invalid cases (dropouts, click-throughs) should not distort the results.

Then perhaps Subgroups for analysis should be defined. In the following it becomes clear why these can (must) be given an identifier.

The following functions are then available for the evaluation itself:

• int sampleSize([string GroupID])
  Returns the number of participants (according to the selection criteria defined in the result report), either for the entire data set or for the subgroup with the identifier GroupIdentifier.
• int sampleBase(string VariablesID, [string GroupIdentifier, boolean NegativeAllow)
  Returns the number of valid values for the variable with the identifier VariableIdentifier in the subgroup with the identifier GroupIdentifier.
• float sampleMean(string VariablesIdetifiers, [string GroupIdentifier, boolean NegativeAllow)
  Returns the mean value of the answers or answer codes for the variable with the identifier VariableIdentifier.
• float sampleSD(string VariablenKennung, [string GroupIdentifier, boolean NegativeAllow)
  Returns the standard deviation.
• array sampleFrequencies(string VariablesIdentifier, [string GroupIdentifier])
  Returns an array with the answers or answer codes and the frequency.
• array sampleResponses(string VariablesIdentifier, [string GroupIdentifier, boolean Sort, int MinimumLength, int MaximalLength])
  Returns a list of all (open) responses to the variable with the identifier VariablenKennung.

Some PHP functions are available in the result report in the same way as in the Compose questionnaire.

• debug() – To display debugging content in the preview.
• getLanguage() – For multilingual feedback result reports.
• dbGet()
• value()
• valueMean()
• stopcreate – Control whether a report will be created.