Actions

Difference between revisions of "Show logic file"

From LimeSurvey Manual

m (Cdorin moved page Show Logic File to Show logic file without leaving a redirect)
m
 
(27 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
<languages />
 
<languages />
 
<translate>
 
<translate>
 +
 
<!--T:1-->
 
<!--T:1-->
 
__TOC__
 
__TOC__
  
<!--T:2-->
 
<div class="simplebox">This feature is available in Version 1.92 or later.</div>
 
  
 
=General= <!--T:3-->
 
=General= <!--T:3-->
 +
 +
 +
<!--T:70-->
 +
An important option that helps you create and easily maintain complex surveys is '''Survey Logic File'''.
  
 
<!--T:69-->
 
<!--T:69-->
Throughout development and testing of the survey, and before activating it, it is very important to validate the survey logic. This is especially true because you can write complex relevance, tailoring, and validation equations, and need to be sure that nothing will break when you run the survey.  
+
Throughout development and testing of the survey, and before activating it, it is very important to validate the survey logic. This is especially true when you use complex relevance, tailoring, and validation equations - you need to be sure that nothing will break when you run the survey.  
  
 
<!--T:4-->
 
<!--T:4-->
This feature lets you quickly validate the accuracy of your survey, group, or question.  It is available via the Survey Properties menu after you selected a survey.
+
This feature lets you quickly validate the accuracy of your survey, group(s), and question(s). It can be accessed from the top bar menu options located under the survey-related settings. It is available via the '''Tools''' menu:
 +
 
  
 
<!--T:5-->
 
<!--T:5-->
 
[[File:show_logic_file.jpg]]
 
[[File:show_logic_file.jpg]]
  
<!--T:6-->
+
 
----
+
<!--T:71-->
 +
As you can observe above, you can run this option four times, for each language used within a survey.
 +
 
  
 
=Description= <!--T:7-->
 
=Description= <!--T:7-->
 +
  
 
<!--T:8-->
 
<!--T:8-->
The Survey Logic File shows everything that you specified for each question (e.g. name, text, help, conditions/relevance, validation rules, defaults, sub-questions, answers) in a convenient tabular format.  It highlights any errors, and lets you click on the question and group IDs (or variables used within equations) to open new browser tabs to edit those questions or groups.  This makes it easy to quickly edit any errors and refresh the logic file to confirm the accuracy of the survey before activating it.
+
The '''Survey Logic File''' shows everything that you specified for each question and group (e.g., name, text, help, conditions/relevance, validation rules, defaults, subquestions, answers) in a convenient tabular format. It highlights the errors, and lets you click on the question and group IDs (or variables used within equations) to open new browser tabs to edit those questions or groups. This makes it easy to quickly edit any errors and refresh the logic file to confirm the accuracy of the survey before activating it.
  
 
<!--T:9-->
 
<!--T:9-->
The display is also designed to be be readable by researchers and study sponsors so that they can validate the accuracy of the survey design and logic. Show logic file update the cache for all expression for active survey.
+
The display is also designed to be be readable by researchers and study sponsors so that they can validate the accuracy of the survey design and logic. Show Logic File updates the cache for all expressions used within an active survey.
  
 
<!--T:10-->
 
<!--T:10-->
 
It includes the following columns:
 
It includes the following columns:
 +
 +
<!--T:72-->
 
*'''#''' - shows the Group and Question sequence counts, starting from 0.
 
*'''#''' - shows the Group and Question sequence counts, starting from 0.
*'''Name <nowiki>[</nowiki>ID]''' - shows the variable name for the group/question/sub-question, using qcode naming convention (these are the names by which you can refer to your variables in [[Expression Manager|Expression Manager]] compliant equations).  '''ID''' is the question id (QID), or group id (GID).  This field also shows the question type (e.g. Multiple choice [M])).
+
 
 +
<!--T:73-->
 +
*'''Name <nowiki>[</nowiki>ID]''' - shows the question code for the group/question/subquestion. These codes can be used as variables within [[Expression Manager - presentation|expressions]]. '''ID''' is the question id (QID), or group id (GID). This field also shows the [[Expression_Manager_-_presentation#Qcode_variable_naming|question type]] (e.g., Multiple choice [M])).
 +
 
 +
 
 +
<!--T:74-->
 +
{{Note|To find out more about which variables can be used within expressions, read the following [[Expression_Manager_-_presentation#Access_to_Variables|wiki subsection]].}}
 +
 
 +
 
 +
<!--T:75-->
 
*'''Relevance <nowiki>[</nowiki>Validation] (Default)''' - shows the following:
 
*'''Relevance <nowiki>[</nowiki>Validation] (Default)''' - shows the following:
**'''Relevance''' - the syntax-highlighted relevance equation for the question or group.  If it is always true, the value will be '''1'''.
+
**''Relevance'' - the syntax-highlighted [[Expression_Manager_-_quick_start_guide#Relevance_.28Controlling_Navigation.2FBranching.29|relevance equation]] for the question or group. If it is always true (to be shown in any scenario), the value will be '''1'''.
**'''Validation''' - Expression manager automatically generates the validation equation based upon the selected question attributes (e.g. min/max number of answers, min/max/equals sum values, min/max individual values, regular expression validation).  This section shows the generated validation equation so that you can detect if there are any errors (e.g. undefined variables).
+
**''Validation'' - Expression manager automatically generates the [[Expression_Manager_-_quick_start_guide#Validation|validation equation]] based upon the selected question attributes (e.g., min/max number of answers, min/max/equals sum values, min/max individual values or regular expression validation). This section shows the generated validation equation so that you can detect if there are any errors (such as undefined variables).
 
***Question-level validation shows the equation needed to verify the above-described question attributes
 
***Question-level validation shows the equation needed to verify the above-described question attributes
***Sub-Question-level validation shows the equation needed to implement array_filter, array_filter_exclude, and exclusive_option.
+
***Subquestion-level validation shows the equation needed to implement [[QS:Array_filter|array_filter]], [[QS:Array_filter_exclude|array_filter_exclude]], and [[QS:Exclusive_option|exclusive_option]]
**'''Default''' - if the question has a default value, it is shown here, syntax-highlighted (since the default could be an expression).
+
**''Default'' - if the question has a default value, it is shown here, syntax-highlighted (since the default could be an expression).
*'''Text <nowiki>[</nowiki>Help] (Tip)''' - shows the following
+
 
**'''Text''' - the text of the group, question, sub-question, or answer.  They are syntax-highlighted to show any embedded tailoring, thus letting you verify that you have declared all of the variables you plan to use in the tailoring.
+
<!--T:76-->
**'''Help''' - this shows the help text for the question, also syntax-highlighted.
+
*'''Text <nowiki>[</nowiki>Help] (Tip)''' - shows the following:
**'''Tip''' - this shows the internally generated validation tip, based upon the question attributes.  This same tip is used in all survey styles, plus in the printable survey and data entry screens.
+
**''Text'' - the text of the group, question, subquestion, or answer. It is syntax-highlighted to show any embedded [[Expression_Manager_-_presentation#Tailoring.2FPiping|tailoring]], thus letting you verify that you have declared all the variables you plan to use in the tailoring.
**'''Question Attributes''' - this shows a table of all relevant question attributes for this question.  Attributes that might be equations are syntax-highlighted so that you can validate their accuracy.
+
**''Help'' - this shows the help text for the question, also syntax-highlighted.
 +
**''Tip'' - this shows the internally generated validation tip, based upon the question attributes. This same tip is used in all survey styles, plus in the printable survey and data entry screens.
 +
**''Question Attributes'' - this shows a table of all relevant question attributes for this question. Attributes that might be equations are syntax-highlighted so that you can validate their accuracy.
  
 
<!--T:11-->
 
<!--T:11-->
Line 49: Line 69:
 
*'''Groups''' - are shown with a light grey background
 
*'''Groups''' - are shown with a light grey background
 
*'''Questions''' - are shown with a light green background
 
*'''Questions''' - are shown with a light green background
*'''Sub-Questions''' - are shown with a pale yellow background
+
*'''Subquestions''' - are shown with a pale yellow background
 
*'''Answers''' - are shown with a plain white background
 
*'''Answers''' - are shown with a plain white background
  
 
<!--T:12-->
 
<!--T:12-->
Answers have an additional attribute in the '''Relevance''' column
+
Answers have an additional attribute in the '''Relevance''' column:
*'''Value''' - this is the default internal value used by calculations.  If you are using Assessments, this will be the assessment value.  Otherwise, this will be the same as the Answer name.
+
*'''Value''' - this is the default internal value used by calculations. If you are using [[Assessments]], this will be the assessment value. Otherwise, this will be the same as the answer name.
 +
 
 +
 
 +
<!--T:77-->
 +
{{Note|The survey description, welcome and end messages, end URL, Survey data policy notice and label are listed within the Survey Logic File (above the table) if their corresponding fields are not empty!}}
 +
 
  
 
=Usage= <!--T:13-->
 
=Usage= <!--T:13-->
 +
  
 
<!--T:14-->
 
<!--T:14-->
At the top of the page, there is a summary message.  If all is well, it will say "No syntax errors detected in this survey", or "This group" or "This question", "by itself, does not contain any syntax errors".  Otherwise, it will say "X questions have syntax errors that need to be corrected".
+
At the top of the page, there is a summary message. If all is well, it will say "No syntax errors detected in this survey", or "This group" or "This question", "by itself, does not contain any syntax errors". If the opposite is true, it will say "X questions have syntax errors that need to be corrected".
  
 
<!--T:15-->
 
<!--T:15-->
Each question that has syntax errors will be color-coded red in the leftmost column (e.g. Q-1).  The following errors are common:
+
Each question that has syntax errors gets the background of its leftmost column (i.e. '''#''') color-coded red. Also, a warning stating the number of minimum errors of a question will be displayed under the '''Name [ID]''' column. The following errors are common:
*Bad variable name - if your question code has non alpha-numeric values, or is used more than once in the survey, it is an error.  However, to support legacy instruments, this is tolerated for now.  Such questions will be shown as with red qcode names, boxed in purple, but the question itself is not flagged as an error.
 
*Undefined variable - if you have not defined all of your variables, or are using a mis-typed array_filter (or different sets of answer options for array_filter), then some of your validation questions will show errors.  Undefined variables are shown in red text, boxed with a red line.
 
*Bad syntax - as you start to use relevance equations, you may use too many or too few parentheses.  Such syntax problems are highlighted and boxed in red. If you hover the mouse over any such red-boxed text, a tool-tip will describe the error.
 
  
<!--T:16-->
+
<!--T:78-->
Here are many good examples of using [[Expression Manager HowTos#Syntax Highlighting|syntax highligting]].
+
*[[Show logic file#Undefined variable|Undefined variable]] - if you have not defined all of your variables, or mistyped array_filter (or different sets of answer options for array_filter), then some of your validation questions will show errors. Undefined variables are shown in red text, boxed with a red line.
  
<!--T:17-->
+
<!--T:79-->
Here is an example of a survey that has errors:
+
*[[Show logic file#Bad syntax|Bad syntax]] - as you start to use relevance equations, you may use too many or too few parentheses. Such syntax problems are highlighted and boxed in red. If you hover the mouse over any such red-boxed text, a tool-tip will describe the error.
  
<!--T:18-->
 
[[File:logic_file_errors.jpg]]
 
  
<!--T:19-->
+
==Undefined Variables== <!--T:20-->
The following types of warnings and errors are present:
 
  
==Undefined Variables== <!--T:20-->
 
  
 
<!--T:21-->
 
<!--T:21-->
The variable name will be color-coded in red and surrounded by a red line.  If you hover your mouse over the variable name, it will say  "Undefined variable".
+
If undefined variables are used, the respective variable name will be color-coded in red and surrounded by a red line. If you hover your mouse over the variable name, it will say "undefined variable":
 +
 
  
 
<!--T:22-->
 
<!--T:22-->
[[File:undefined_varaible.jpg]]
+
<center>[[File:undefined_varaible.jpg]]</center>
 +
 
 +
 
 +
<!--T:80-->
 +
{{Alert|title=Attention|text=Please note that LimeSurvey does not allow survey administrators to create questions that use the same question code. However, it could happen to have similar question codes within a survey if you import a question group or a question that uses the same question code as one of your already-defined questions. The question can still be imported because the question ids are different. However, if you wish to export the survey results to further explore the [[Exporting_results|survey results]] (R or SPSS), be careful because the question code is seen as a variable!}}
 +
 
 +
 
 +
<!--T:81-->
 +
<center>[[File:same_code_name_not_recommended.png]]</center>}}
 +
 
 +
==Bad syntax== <!--T:82-->
 +
 
  
==Obsolete variable names== <!--T:23-->
+
<!--T:83-->
 +
Most of the expression-related mistakes are related to bad syntax. This is related to the fact that survey administrators usually miss to add a curly bracket, to properly make use of parentheses, or they use expressions wrongly:
  
<!--T:24-->
 
Starting in 1.92, the preferred naming of question codes is [a-Z][0-9a-Z_]* - meaning it must start with a letter, and can contain letters, numbers, or underscores.  However, for backwards compatibility, we are are only flagging invalid variable names via a warning for now.   We expect to give the option to disallow those old variable names in the future, since many of the new features (along with proper SPSS / R export) require unique and properly formatted question codes.
 
  
<!--T:25-->
+
<!--T:84-->
These warnings appear as a pink line surrounding the variable name in the Name [ID] column.  If you hover the mouse over the variable name, you will see this message:
+
<center>[[File:Syntax_highlighting_parantheses.png]]</center>
  
<!--T:26-->
+
<!--T:85-->
[[File:invalid_variable_name.jpg]]
+
<center>[[File:Syntax_highlighting_extra_comma.png]]</center>
  
<!--T:27-->
 
Clicking on the link for the variable name opens up a new browser tab in which you can fix the error. You can have as many tabs open as you want, so you can simply click on all of the errors, fix and save them all, then re-run the Show Logic File report to confirm that you have fixed all of the errors.
 
  
==Bad custom JavaScript== <!--T:28-->
+
<!--T:16-->
 +
Here are many good examples on the usage of [[Expression_Manager_how-tos#Syntax_Highlighting|syntax highlighting]].
  
<!--T:29-->
 
If your survey contains custom JavaScript, you may see situations like this, where the question is flagged as having an error, but you don't see any "red-boxed" variable names.
 
  
<!--T:30-->
+
===Bad custom JavaScript=== <!--T:28-->
[[File:javascript_error.jpg]]
 
  
<!--T:31-->
 
If you click on the question ID, you will see the problem JavaScript in the Help text:
 
  
<!--T:32-->
+
<!--T:29-->
[[File:javascript_error2.jpg]]
+
The JavaScript errors will also be highlighted in the logic file:
  
<!--T:33-->
 
Any time you add custom JavaScript (e.g. to the Group, Question, Help, or Answer), Expression Manager parses it looking for expressions.  This is desirable, since it lets you do variable substitution within the JavaScript.  However, it can be easy to misspell variable names, or forget to add a newline or space after opening curly braces within your JavaScript.  That is the case here.  If you simply remove the "script" tags from within the Help section, and save the question, Expression Manager will show you the parse errors.  In this case, since there was no space after the opening curly brace, Expression Manager warns that "document" is an undefined variable, and "write" is an undefined function.
 
  
<!--T:34-->
+
<!--T:30-->
[[File:javascript_error3.jpg]]
+
<center>[[File:javascript_error.jpg]]</center>
 +
 
  
 
=Speeding editing and validation= <!--T:35-->
 
=Speeding editing and validation= <!--T:35-->
 +
  
 
<!--T:36-->
 
<!--T:36-->
All of the syntax-highlighted text has embedded tool-tips, and is clickable.
+
All of the syntax-highlighted text has tooltips embedded, which are clickable:
#Tool Tips
+
#Tooltips
#*Functions - hovering the mouse lets you see the purpose and syntax definition of the function
+
#*Functions - hovering the mouse lets you see the purpose and syntax definition of the function;
#*Variable Names - hovering the mouse lets you see the position (group and question sequence), question text, and allowable answers for the question
+
#*Variable Names - hovering the mouse lets you see the position (group, question sequence), question text, and allowable answers for the question.
 
#Actions
 
#Actions
#*Variable Names - clicking on the variable name opens a new window that lets you edit the question.  This makes it easy to navigate and verify logic - simply keep clicking on variable names of relevance or validation criteria for the question to see where they come from and how they are used.
+
#*Variable Names - clicking on the variable name opens a new window that allows you to edit the question. This makes it easy to navigate and verify logic - simply keep clicking on variable names of relevance or validation criteria for the question to see where they come from and how they are used.
 +
 
 +
 
 +
=Examples= <!--T:37-->
  
=Screen shots= <!--T:37-->
 
  
 
<!--T:38-->
 
<!--T:38-->
The following examples are taken from the [[Expression Manager Sample Surveys|Expression Manager Sample Surveys]].  You can find screen-shots of running surveys, explanations, and downloads on that page.
+
The following examples are taken from the [[Expression Manager sample surveys|Expression Manager sample surveys]]. You can find screenshots of running surveys, explanations, and downloads on that page.
 +
 
  
 
==Body Mass Index== <!--T:39-->
 
==Body Mass Index== <!--T:39-->
 +
  
 
<!--T:40-->
 
<!--T:40-->
Here are [[Expression Manager Sample Surveys#Screen Shots|screen shots]] of this example.
+
Here are [[Expression Manager sample surveys#Screenshots|screenshots]] of this example.
  
 
<!--T:41-->
 
<!--T:41-->
This is the Question-Reorder view of the Body Mass Index calculation.  You can see the relevance equations (which are after the variable name, within square brackets - like <nowiki>[</nowiki>1] for weight, and <nowiki>[</nowiki>!is_empty(height) && !is_empty(weight)]) for BMI.  You can also see the tailored text of the questions.
+
This is the question-reorder view of the Body Mass Index calculation. You can see the relevance equations for weight, height, and BMI under the ''Question'' column:
 +
 
  
 
<!--T:42-->
 
<!--T:42-->
[[File:BMI_reorder.jpg]]
+
<center>[[File:BMI_reorder.jpg]]</center>
 +
 
  
 
<!--T:43-->
 
<!--T:43-->
The logic file provides additional information, including question type, and lists of sub-questions and answer options, plus all question attributes.
+
For a better survey overview, check the survey logic file:
  
<!--T:44-->
 
Note that the (VALIDATION: ) section is automatically generated for you from the question attributes you have selected.  This lets you see what validation logic is being applied, but you never have to specify or edit that validation logic directly.
 
  
 
<!--T:45-->
 
<!--T:45-->
[[File:BMI_logic1.jpg]]
+
<center>[[File:BMI_logic1.jpg]]</center>
 +
 
  
 
<!--T:46-->
 
<!--T:46-->
This has a good example of nested if() statements to generate the weight_status.
+
This survey example is also a good example of nested if() statements to generate the "weightstatus".
 +
 
  
 
<!--T:47-->
 
<!--T:47-->
[[File:BMI_logic2.jpg]]
+
<center>[[File:BMI_logic2.jpg]]</center>
  
 
==Cascading logic== <!--T:48-->
 
==Cascading logic== <!--T:48-->
 +
  
 
<!--T:49-->
 
<!--T:49-->
Here are [[Expression Manager Sample Surveys#Cascading Array Filters|screen shots]] of this example.
+
Here are [[Expression Manager sample surveys#Cascading Array Filters|screenshots]] of this example.
  
 
<!--T:50-->
 
<!--T:50-->
This example shows the sub-question validation logic that is automatically generated when you use array_filter and array_filter_exclude.  This example also shows how you can substitute the tailored "Other" value (the answer for Q02_other is Q01_other).
+
It shows the subquestion validation logic that is automatically generated when you use [[QS:Array_filter|array_filter]] and [[QS:Array_filter_exclude|array_filter_exclude]]. This example also shows how you can substitute the tailored "Other" value (the answer for Q02_other is Q01_other).
 +
 
  
 
<!--T:51-->
 
<!--T:51-->
[[File:cascading_logic1.jpg]]
+
<center>[[File:cascading_logic1.jpg]]</center>
 +
 
  
 
<!--T:52-->
 
<!--T:52-->
Q05 in this example shows simultaneous use of array_filter and array_filter_exclude on Q01 and Q02, respectively.  This is part of how this example demonstrates cascading array_filter capabilities.  Note that one of the main reasons for showing the question and sub-question level VALIDATION criteria is to help ensure you have not made any typos in specifying the array_filter or array_filter_exclude variable names (or in case you use different variable names for your list of filtered sub-questions).  If you have such typos, you all of the invalid variable names will appear in red indicating that they are undefined, letting you quickly fix the problem.
+
Q05 in this example shows simultaneous use of array_filter and array_filter_exclude on Q01 and Q02, respectively. This example demonstrates cascading array_filter capabilities. Note that one of the main reasons for showing the question and subquestion level '''validation''' criteria is to help ensure you have not made any typos in specifying the array_filter or array_filter_exclude variable names (or in case you use different variable names for your list of filtered subquestions). If you have such typos, all the invalid variable names will appear in red indicating that they are undefined, letting you quickly fix the problem.
 +
 
  
 
<!--T:53-->
 
<!--T:53-->
[[File:cascading_logic2.jpg]]
+
<center>[[File:cascading_logic2.jpg]]</center>
 +
 
  
 
==Dynamic relevance== <!--T:54-->
 
==Dynamic relevance== <!--T:54-->
 +
  
 
<!--T:55-->
 
<!--T:55-->
This example demonstrates dynamic, cascading relevance logic to control display of question visibility.  You can download this example [[Expression Manager Sample Surveys#Download|here]].
+
This example demonstrates dynamic cascading relevance logic to control display of question visibility. You can download this example [[Expression Manager sample surveys#Download|here]].
  
<!--T:56-->
+
<!--T:57-->
All questions starting with Q-20 (age) have a relevance equation.  Q-22 (yearsMarried) also has a validation equation which uses the max_num_value_n advanced question attribute, but passes it an equation (age-5) rather than a fixed number.
+
Also note that questions are displayed only if certain validation criteria are met. For example, if a person states that she has 2 kids, certain questions have to be filled in by the respondent (kid1 and kid2).
  
<!--T:57-->
 
Also note that questions kid1-kid3 are mandatory.  However, if the question is not relevant, the mandatory requirement is ignored (which makes sense, since why would you force someone to answer an irrelevant question).  These questions can be  considered "conditionally mandatory".
 
  
 
<!--T:58-->
 
<!--T:58-->
[[File:dynamic_relevance_logic1.jpg]]
+
<center>[[File:dynamic_relevance_logic1.jpg]]</center>
  
 
==Group-level relevance== <!--T:59-->
 
==Group-level relevance== <!--T:59-->
 +
  
 
<!--T:60-->
 
<!--T:60-->
This example shows how group-level relevance appears in the logic file.  Here are [[Expression Manager Sample Surveys#Sample Census|screen shots]] of the working demo.
+
This example shows how group-level relevance appears in the logic file. Here are [[Expression Manager sample surveys#Sample Census|screenshots]] of the example described below.
  
 
<!--T:61-->
 
<!--T:61-->
Line 202: Line 237:
  
 
<!--T:62-->
 
<!--T:62-->
You may also notice that all of the questions are mandatory.  However, if the group is irrelevant, so are all of its questions, so those questions are only truly mandatory if the group is relevant.
+
You may also notice that all of the questions are mandatory. However, if the group is irrelevant, so are all its questions. As a result, those questions are only truly mandatory if the group is relevant.
 +
 
 +
<!--T:86-->
 +
You may also note that certain questions are displayed only if the answer to the previous question is not empty. You may see below that if p2_sex is not filled in, p2_name is not going to be displayed, even though it is a mandatory questions. The mandatory question p2_age is also not going to be displayed if p2_name is not filled in. These questions can be considered "conditionally mandatory".  
  
 
<!--T:63-->
 
<!--T:63-->
Additionally, note that the TIP messages are also automatically created for you.  They are organized by value range (min/max), sum value range (min/max/equals), number of answers (min/max), etc.  Sometimes you want to validate an answer range but don't want to display what might appear to be silly validation tips to the user.  In such cases, you can use the hide_tip advanced question option (as in this case, to avoid telling the user that the age must be between 0 and 115 unless they try to enter a bad value).
+
Additionally, note that the '''tip''' messages are also automatically created for you. They are organized by value range (min/max), sum value range (min/max/equals), number of answers (min/max), etc (it depends on the used question type and active attributes). Sometimes you want to validate an answer range but don't want to display what might appear to be silly validation tips to the user. In such cases, you can use the [[QS:Hide_tip|hide_tip]] question option (as in this case, to avoid telling the user that the age must be between 0 and 115 unless they try to enter a bad value - see p2_age).
 +
 
  
 
<!--T:64-->
 
<!--T:64-->
[[File:person2_logic.jpg]]
+
<center>[[File:person2_logic.jpg]]</center>
  
 
==Comma as radix (decimal) separator== <!--T:65-->
 
==Comma as radix (decimal) separator== <!--T:65-->
 +
  
 
<!--T:66-->
 
<!--T:66-->
This demo shows that although LimeSurvey 1.92 now fully supports use of comma as the radix (decimal) separator at run-time, you must still use a decimal as the radix separator at design-time (e.g. when specifying min/max values in advanced question attributes). The working example is [[Expression Manager Sample Surveys#Using Comma as Radix Separator (Decimal Point)|found here]].
+
Although LimeSurvey fully supports the use of comma as radix (decimal) separator at run-time, you must still use a decimal as the radix separator at the design-time (e.g., when specifying min/max values in advanced question attributes). The working example can be [[Expression Manager sample surveys#Using Comma as Radix Separator (Decimal Point)|found here]].
  
 
<!--T:67-->
 
<!--T:67-->
Also, remember, the VALIDATION logic is created for you automatically from the advanced question attributes. The equations can look overwhelming, but you don't need to worry about them.
+
Also, remember that the '''validation''' logic is created for you automatically from the enabled question attributes. The equations may look overwhelming, but you don't need to worry about them.
 +
 
  
 
<!--T:68-->
 
<!--T:68-->
[[File:radix_logic1.jpg]]
+
<center>[[File:radix_logic1.jpg]]</center>
 
</translate>
 
</translate>

Latest revision as of 16:57, 14 November 2018

Other languages:
Deutsch • ‎English • ‎日本語 • ‎Nederlands


General

An important option that helps you create and easily maintain complex surveys is Survey Logic File.

Throughout development and testing of the survey, and before activating it, it is very important to validate the survey logic. This is especially true when you use complex relevance, tailoring, and validation equations - you need to be sure that nothing will break when you run the survey.

This feature lets you quickly validate the accuracy of your survey, group(s), and question(s). It can be accessed from the top bar menu options located under the survey-related settings. It is available via the Tools menu:


Show logic file.jpg


As you can observe above, you can run this option four times, for each language used within a survey.


Description

The Survey Logic File shows everything that you specified for each question and group (e.g., name, text, help, conditions/relevance, validation rules, defaults, subquestions, answers) in a convenient tabular format. It highlights the errors, and lets you click on the question and group IDs (or variables used within equations) to open new browser tabs to edit those questions or groups. This makes it easy to quickly edit any errors and refresh the logic file to confirm the accuracy of the survey before activating it.

The display is also designed to be be readable by researchers and study sponsors so that they can validate the accuracy of the survey design and logic. Show Logic File updates the cache for all expressions used within an active survey.

It includes the following columns:

  • # - shows the Group and Question sequence counts, starting from 0.
  • Name [ID] - shows the question code for the group/question/subquestion. These codes can be used as variables within expressions. ID is the question id (QID), or group id (GID). This field also shows the question type (e.g., Multiple choice [M])).


Help.pngTo find out more about which variables can be used within expressions, read the following wiki subsection.


  • Relevance [Validation] (Default) - shows the following:
    • Relevance - the syntax-highlighted relevance equation for the question or group. If it is always true (to be shown in any scenario), the value will be 1.
    • Validation - Expression manager automatically generates the validation equation based upon the selected question attributes (e.g., min/max number of answers, min/max/equals sum values, min/max individual values or regular expression validation). This section shows the generated validation equation so that you can detect if there are any errors (such as undefined variables).
    • Default - if the question has a default value, it is shown here, syntax-highlighted (since the default could be an expression).
  • Text [Help] (Tip) - shows the following:
    • Text - the text of the group, question, subquestion, or answer. It is syntax-highlighted to show any embedded tailoring, thus letting you verify that you have declared all the variables you plan to use in the tailoring.
    • Help - this shows the help text for the question, also syntax-highlighted.
    • Tip - this shows the internally generated validation tip, based upon the question attributes. This same tip is used in all survey styles, plus in the printable survey and data entry screens.
    • Question Attributes - this shows a table of all relevant question attributes for this question. Attributes that might be equations are syntax-highlighted so that you can validate their accuracy.

Rows are color coded as follows:

  • Groups - are shown with a light grey background
  • Questions - are shown with a light green background
  • Subquestions - are shown with a pale yellow background
  • Answers - are shown with a plain white background

Answers have an additional attribute in the Relevance column:

  • Value - this is the default internal value used by calculations. If you are using Assessments, this will be the assessment value. Otherwise, this will be the same as the answer name.


Help.pngThe survey description, welcome and end messages, end URL, Survey data policy notice and label are listed within the Survey Logic File (above the table) if their corresponding fields are not empty!


Usage

At the top of the page, there is a summary message. If all is well, it will say "No syntax errors detected in this survey", or "This group" or "This question", "by itself, does not contain any syntax errors". If the opposite is true, it will say "X questions have syntax errors that need to be corrected".

Each question that has syntax errors gets the background of its leftmost column (i.e. #) color-coded red. Also, a warning stating the number of minimum errors of a question will be displayed under the Name [ID] column. The following errors are common:

  • Undefined variable - if you have not defined all of your variables, or mistyped array_filter (or different sets of answer options for array_filter), then some of your validation questions will show errors. Undefined variables are shown in red text, boxed with a red line.
  • Bad syntax - as you start to use relevance equations, you may use too many or too few parentheses. Such syntax problems are highlighted and boxed in red. If you hover the mouse over any such red-boxed text, a tool-tip will describe the error.


Undefined Variables

If undefined variables are used, the respective variable name will be color-coded in red and surrounded by a red line. If you hover your mouse over the variable name, it will say "undefined variable":


Undefined varaible.jpg


Important.png
Attention : Please note that LimeSurvey does not allow survey administrators to create questions that use the same question code. However, it could happen to have similar question codes within a survey if you import a question group or a question that uses the same question code as one of your already-defined questions. The question can still be imported because the question ids are different. However, if you wish to export the survey results to further explore the survey results (R or SPSS), be careful because the question code is seen as a variable!


Same code name not recommended.png

}}

Bad syntax

Most of the expression-related mistakes are related to bad syntax. This is related to the fact that survey administrators usually miss to add a curly bracket, to properly make use of parentheses, or they use expressions wrongly:


Syntax highlighting parantheses.png
Syntax highlighting extra comma.png


Here are many good examples on the usage of syntax highlighting.


Bad custom JavaScript

The JavaScript errors will also be highlighted in the logic file:


Javascript error.jpg


Speeding editing and validation

All of the syntax-highlighted text has tooltips embedded, which are clickable:

  1. Tooltips
    • Functions - hovering the mouse lets you see the purpose and syntax definition of the function;
    • Variable Names - hovering the mouse lets you see the position (group, question sequence), question text, and allowable answers for the question.
  2. Actions
    • Variable Names - clicking on the variable name opens a new window that allows you to edit the question. This makes it easy to navigate and verify logic - simply keep clicking on variable names of relevance or validation criteria for the question to see where they come from and how they are used.


Examples

The following examples are taken from the Expression Manager sample surveys. You can find screenshots of running surveys, explanations, and downloads on that page.


Body Mass Index

Here are screenshots of this example.

This is the question-reorder view of the Body Mass Index calculation. You can see the relevance equations for weight, height, and BMI under the Question column:


BMI reorder.jpg


For a better survey overview, check the survey logic file:


BMI logic1.jpg


This survey example is also a good example of nested if() statements to generate the "weightstatus".


BMI logic2.jpg

Cascading logic

Here are screenshots of this example.

It shows the subquestion validation logic that is automatically generated when you use array_filter and array_filter_exclude. This example also shows how you can substitute the tailored "Other" value (the answer for Q02_other is Q01_other).


Cascading logic1.jpg


Q05 in this example shows simultaneous use of array_filter and array_filter_exclude on Q01 and Q02, respectively. This example demonstrates cascading array_filter capabilities. Note that one of the main reasons for showing the question and subquestion level validation criteria is to help ensure you have not made any typos in specifying the array_filter or array_filter_exclude variable names (or in case you use different variable names for your list of filtered subquestions). If you have such typos, all the invalid variable names will appear in red indicating that they are undefined, letting you quickly fix the problem.


Cascading logic2.jpg


Dynamic relevance

This example demonstrates dynamic cascading relevance logic to control display of question visibility. You can download this example here.

Also note that questions are displayed only if certain validation criteria are met. For example, if a person states that she has 2 kids, certain questions have to be filled in by the respondent (kid1 and kid2).


Dynamic relevance logic1.jpg

Group-level relevance

This example shows how group-level relevance appears in the logic file. Here are screenshots of the example described below.

As you can see, the group-level relevance equation (cohabs > 1 && p1_rel != "") appear in the grey Person 2 row for G-2.

You may also notice that all of the questions are mandatory. However, if the group is irrelevant, so are all its questions. As a result, those questions are only truly mandatory if the group is relevant.

You may also note that certain questions are displayed only if the answer to the previous question is not empty. You may see below that if p2_sex is not filled in, p2_name is not going to be displayed, even though it is a mandatory questions. The mandatory question p2_age is also not going to be displayed if p2_name is not filled in. These questions can be considered "conditionally mandatory".

Additionally, note that the tip messages are also automatically created for you. They are organized by value range (min/max), sum value range (min/max/equals), number of answers (min/max), etc (it depends on the used question type and active attributes). Sometimes you want to validate an answer range but don't want to display what might appear to be silly validation tips to the user. In such cases, you can use the hide_tip question option (as in this case, to avoid telling the user that the age must be between 0 and 115 unless they try to enter a bad value - see p2_age).


Person2 logic.jpg

Comma as radix (decimal) separator

Although LimeSurvey fully supports the use of comma as radix (decimal) separator at run-time, you must still use a decimal as the radix separator at the design-time (e.g., when specifying min/max values in advanced question attributes). The working example can be found here.

Also, remember that the validation logic is created for you automatically from the enabled question attributes. The equations may look overwhelming, but you don't need to worry about them.


Radix logic1.jpg