====== Rotation ======

Rotation is used to present items and options in a question in a different order (at random) to each participant. Each participant will also see a unique sequence of the questions. 

Rotation is used in a survey to reduce bias that might be introduced by the order in which choices are listed on the page. Primacy and recency effects are well-known: rotation is particularly useful when the order of questions or items is likely to distort response behaviour in the overall sample. As a rule, when it comes to rotation, the sequence applied in each case is irrelevant for analysis.

This is different to [[randomization|randomization]], in which participants are assigned at random to experimental groups. The order of questions can be changed deliberately here as well, however, this means the sequence used is generally crucial to the analysis.   

**Tip:** Read the chapters [[php|Introduction to PHP]] and [[array|Introduction to Arrays]] for a better understanding of the complex example codes shown below.

===== When is Rotation Useful? =====

Take care: using rotation is not always the most sensible option. Problematic measurement errors can be incurred by rotating items. 

It __makes sense__ to use rotation if the aggregate is to be projected onto the main unit. For example, if you want to compare which option in a multiple choice question was selected the most or which item was rated most highly on a scale. Statistically speaking, bias in the aggregate is more likely to be removed by the order effect. 

It __does not make sense__ to use rotation if you want to compare participants. This is the case for virtually all forms of correlation. For example, the question regarding whether satisfaction with a particular television genre (compiled in a scale together with other items) is indicative of the duration of television use. If the items in the scale are rotated, then some of the participants appear to be more satisfied with the television programme due solely to the order effect. There is a measurement error in this instance as a result of rotation.

Measurement error as a result of rotation declines with the number of items with which a participant measures a construct. There is less measurement error in the BFI-S personality scale with three items for every personality trait than for the above example with only one item. The pros and cons have to be weighed up insofar it is desirable to calculate correlations and compare the items to each other. Before using rotation, take a quick break and think about the aim of the question.

===== Rotation of Items or Options in a Question =====

Randomization or rotation of items in a question is activated as follows: open the question in the **List of Questions** and, either in the first tab or in //Items Setting// by //Items Order//, select the option "Shuffle/rotate randomly". Randomization will then be activated immediately in the preview after saving the question.

If individual items (e.g. "other") should be excluded from the rotation, then open the item in the **List of Questions** or with the {{:button.edit.gif?nolink|edit}}symbol and select the option //exclude this item during sorting/shuffling//.

**Advice:** Obviously, rotation only affects how the questionnaire is presented. Participants' responses to a specific item will always be saved under the same ID.

===== Rotation of Items over Multiple Pages =====

If you have a lot of items in one question, you may want to spread them out over multiple pages. Normally, you do this by pasting the question as many times as you need in **Compose Questionnaire** and entering the different items for each one in Display Settings by clicking on the ({{:button.settings.png?nolink|Anzeige-Einstellungen}} button), e.g. "1-10", "11-20", etc.

If you want to combine item distribution with randomization then a few lines of [[php|PHP Code]] are needed.

<code php>
// isset() prevents rotation being changed due to missing answers
if (!isset($itemsAB01)) {
  // list all items in question AB01
  $itemsAB01 = getItems('AB01', 'all');
  // shuffle list
  shuffle($itemsAB01);
  // divide list into lists of 20 items
  $itemsAB01 = array_chunk($itemsAB01, 20);
  // make variable available for other pages
  registerVariable('itemsAB01');
}

// spread items over multiple pages
$i = loopPage(count($itemsAB01));
question('AB01', $itemsAB01[$i]);
</code>

By using the ''[[:en:create:functions:looppage|loopPage()]]'' function, multiple pages can be displayed within one page of the questionnaire. As an alternative to the last two lines, the number of pages required in the questionnaire can be inserted, as well as the corresponding item section for each one:

<code php>
// first page
question('AB01', $itemsAB01[0]);

// second page
question('AB01', $itemsAB01[1]);

// third page
question('AB01', $itemsAB01[2]);
</code>

Please note that the index in the square brackets is the only thing that will change on each page. The index begins with 0, not with 1 (see example above).

**Note:** Starting a page directly with items in **Compose a Questionnaire** results in the error message variable "''$itemsAB01'' is not known being displayed. To test this, always start from the page where randomization, and therefore the variable ''$itemsAB01'', is defined.

===== Rotation of Multiple Questions =====

In rare cases, the questions themselves have to be rotated as well; not just their items. This requires a bit of programming using [[php|PHP code]].

The following example shows how the order of five questions on the page of a questionnaire can be rotated (see [[filter-items#arrays|Use Selected Items in Another Question]] for an explanation on arrays):

<code php>
if (!isset($questions)) {
  $questions = array(  // list of question IDs
    'AB01',
    'AB02',
    'CC03',
    'DE01',
    'DE02'
  );
  // shuffle list randomly
  shuffle($questions);
  // cache rotation in case page is repeated 
  registerVariable('questions');
  
}
// go through list of questions ID for ID
// and show corresponding question each time 
foreach ($questions as $id) {
  question($id);
}
</code>

**Advice:** If you use a similar rotation at different points within the questionnaire then the name of the variable ''$questions'' must be varied. For example, ''$questions1'' for the first time it is used and ''$questions2'' for the second time.  
===== Rotating Questions over Multiple Pages =====

Rotating questions over multiple pages is only slightly more challenging. The following example shows how six questions can be distributed over two pages:

<code php>
// PHP code on page 1

// shuffle list just once 
if (!isset($questions)) {
  // make a list of question IDs
  $questions = array(
    'AB01', 'AB02',
    'CC02', 'CC03',
    'DE01', 'DE02'
  );
  // shuffle list randomly
  shuffle($questions);
  // make lists available on all pages
  registerVariable('questions');
}

// show first three IDs of the list
question($questions[0]);
question($questions[1]);
question($questions[2]);
</code>

<code php>
// PHP code on page 2

// show next three IDs of the list
question($questions[3]);
question($questions[4]);
question($questions[5]);
</code>

If you want to display questions one at a time, with each one on their own page, then this is fairly simply to achieve by using ''[[:en:create:functions:looppage|loopPage()]]''. The following code example is entered after the order is defined (i.e. two rows below the ''registerVariable()''in the PHP code above). 

<code php>
$i = loopPage(count($questions));
question($questions[$i]);
</code>


===== Rotating Questions Together with Additional Content =====

You have to go one step further to rotate additional data (e.g. an image as a stimulus) together with the questions. For example, if "bild1.png" should always be displayed before question 1 and "bild2.gif" should always be displayed before question 2. However, the principle is the same. In the following example each page displays only one combination of image and question -- but (as in the previous example), several questions can be included on a page. 

<code php>
if (!isset($blocks)) {
  $blocks = array(  // list of question IDs and images belonging to them
    array('AB01', 'image1.png'),
    array('AB02', 'image2.gif'),
    array('AB03', 'image3.jpg'),
    array('AB04', 'image4.png')
  );

  // shuffle list
  shuffle($blocks);
  // make lists available on all pages
  registerVariable('blocks');
}

// display blocks
$i = loopPage(count($blocks));
// display picture
html('<p><img src="'.$blocks[$i][1].'" alt="election poster"></p>');
// display question
question($blocks[$i][0]);
</code>

Alternatively, multiple pages can be added to the questionnaire, each displaying one block. This can be useful when the blocks should not be displayed directly one after the other.

<code php>
html('<p><img src="'.$blocks[0][1].'" alt="election poster"></p>');
question($blocks[0][0]);
</code>

<code php>
html('<p><img src="'.$blocks[1][1].'" alt="election poster"></p>');
question($blocks[1][0]);
</code>


===== Multiple Questions per Stimulus =====

Multiple questions per block are also possible, and can usually be achieved more easily by using ''[[:en:create:functions:setpageorder|setPageOrder()]]''. Different pages of the questionnaire will then be presented at random. 

The page order has to be set on the page __before__ the first page to be rotated. Furthermore, each page in **Compose a Questionnaire** must be assigned a unique ID. In the following example, this is "B1", "B2", ... "B5". The following page also must be given an ID (e.g. "SD").

<code php>
if (!isset($pages)) {
  // define list of pages
  $pages = array('B1','B2','B3','B4','B5');
  // shuffle list
  shuffle($pages);
  // add page where the questionnaire continues
  $pages[] = 'SD';
  // cache page order to prevent changes later on
  registerVariable('pages');
}
setPageOrder($pages);
</code>

**Advice:** Every time you use ''isset()'' to avoid a change later on in the order (e.g. by using the Back button), you can only use the variable (here: ''$pages'') once in the questionnaire. If you need to use more, vary the name of the variable, e.g. ''$pages1'' und ''$pages2''.   

===== Rotation of Question Blocks =====

Just like individual pages, blocks can be rotated onto multiple pages. The only difference here being that each of these blocks is assigned an ID on the first and last page in **Compose a Questionnaire** (e.g. "B1Start" and "B1End", "B2Start" and "B2End" and so on). The first page following this area is also given an ID ("SD").

**Note:** If you want to rotate multiple pages (blocks) in the questionnaire, use the command ''[[:en:create:functions:setpageorder|setPageOrder()]]''instead of the following PHP code.

<code php>
if (!isset($blocks)) {
  // define list of pages
  $blocks = array('B1Start-B1End','B2Start-B2End','B3Start-B3End');
  // shuffle list
  shuffle($blocks);
  // add page where the questionnaire continues
  $blocks[] = 'SD';
  // cache page order to prevent changes later on
  registerVariable($blocks);
}
setPageOrder($blocks);
</code>