SoSci Survey
Translations of this page:

panelData ()

array panelData()

The function panelData() returns information from the Addresslist if the interview was started by a personalized hyperlink (e.g., from a mailing).

Return Value

The panelData () command returns in an array including the address entries subgroup, the time of the mail dispatch, and the data stored as user-defined data in the address entry.

array (
  0 => (string) Subgroup,
  1 => (string) User-defined data 1,
  2 => (string) User-defined data 2,
  3 => (string) User-defined data 3,
  4 => (string) User-defined data 4,
  5 => (string) User-defined data 5,
  'subgroup' => (string) Subgroup,
  'mailsent' => (int) Unix timestamp when the mail was sent

Important: The function provide a value only, if the interview was started by click at the personalized link in a mass mail (else zero). In case the participant is forwarded automatically to the survey, after an Opt-In-Confirmation, (Multi-Wave Surveys with Self-Recruited Respondents), than this is equivalent to the click at the personalized link in a mailing.

Note: If individual sending times are used for the mailing, the information on the sending time (like certain user-defined data) can remove anonymity and should not be stored in the data set. If the address entry is not anonymous, the sending time is automatically stored in the MAILSENT variable in the data set and 'mailsent' returns the same value as value('MAILSENT').

Example: Importing data

The following example is based on the assumption, that the name of the company is placed in field 1 of the address record. Now, the name of the company should be used as the content of the placeholder %company%.

$data = panelData();
if ($data === null) {
  // Error message and abort of the questionnaire,
  // if the questionnaire was not called up with a personalized link
  text('no data');
$company = $data[1];
replace('%company%', $company);

Example: Experiment in two-wave survey

In this example, participants register themselves for a study (Multi-Wave Surveys with Self-Recruited Respondents). In the following, participants of the control and experimental group will receive different emails as experimental stimulus. Therefore, their address entries must be assigned to different subgroups. This is done by displaying one of two opt-in questions, depending on a randomly drawn code (Random generator).

Note: An [:en:create:questions:opt-in|Opt-in question]] can automatically assign a newly registered participant to a subgroup.

if (value('RG01') == 1) {
  question('OI01'); // Opt-In question OI01 sets subgroup "EG".
} else {
  question('OI02'); // Opt-In question OI02 sets subgroup "CG"

After opt-in confirmation of the e-mail address, the participant is automatically forwarded to a second questionnaire. Depending on the group affiliation, the stimulus from text module “textEG” or “textCG” is to be displayed and either mailing 2 or 3 is to be sent.

$info = panelData();
if ($info) {
  $group = $info['subgroup'];
  if ($group == 'CG') {
    mailSchedule(false, 2);
  } else {
    mailSchedule(false, 3);
} else {
  // Display error message that the questionnaire does not contain a valid participation key.
  // (e.g. when not started from a mailing) or that the address entry was called after
  // the address record had been deleted from the address list

For easier analysis, it would make sense to store the group membership via put() in the data set of the second questionnaire. For example, the following PHP code would be added to the IF part of the previous PHP code after an internal variable IV01_01 was added in the List of Questions.

$group = $info['subgroup'];
put('IV01_01', $group);

Example: Time between invitation and participation

In this example, mailings are sent to the participants at random times as part of random experience sampling. It is important for the evaluation whether the participant has completed the questionnaire within 30 minutes or not. However, the dispatch time should not be saved in the data record because this could jeopardise anonymity.

With the help of panelData () the exact sending time can now be determined and thus the delay between sending the email and the participation. The PHP function time () returns the current time as a Unix timestamp, the difference is the delay in seconds. If the delay is more than 30 minutes (1800 seconds), the code 2 will be stored in the internal variable IV01_01, otherwise the code 1.

If the sending time cannot be determined, code -1 is stored. This can happen if the interview was not started from a mailing link or if the address entry has been deleted in the meantime by the project manager or the respondent.

$info = panelData();
if ($info) {
  $sent = $info['mailsent'];
  $delay = time() - $sent;
  if ($delay <= 1800) {
    put('IV01_01', 1);
  } else {
    put('IV01_01', 2);
} else {
  put('IV01_01', -1);
en/create/functions/paneldata.txt · Last modified: 03.02.2018 22:15 by admin
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
Driven by DokuWiki