Criteria

Criteria in Ethica is a conditional expression, or a formula, which instructs Ethica whether an action has to happen or not. Ethica allows adding a Criteria to the following elements:
​Eligibility Surveys​
Activities
​Triggering Logics​
Survey Sections
Survey Questions
An Eligibility Survey must have a Criteria. This Criteria specifies who is considered eligible to join the study and who should be excluded.
Other Activities can also contain a Criteria. In this case, Ethica evaluates the Criteria periodically. For those participants that the Criteria is evaluated as True and as long as it remains True, the Activity can be prompted to that participant per its Triggering Logics specification. For those participants that the Activity Criteria is evaluated as False and as long as it remains False, the Activity will not be prompted regardless of its Triggering Logics.
Furthermore, each Triggering Logics also can have a Criteria, which determines whether it should be enabled or not. Similar to the Activity Criteria, TL Criteria is evaluated periodically to determine if a TL is activated or not.
For Survey Sections, and similarly, for Survey Questions, Ethica shows or skips a given section or question depending on whether its Criteria is evaluated as True or False.
By default, the Criteria for the components mentioned above is set to empty. In Ethica an empty Criteria means True. Therefore, these components are active by default. If a Criteria is not empty, but it's invalid due to a syntax error, Ethica evaluates it to False.
Note: While any Activity and any Triggering Logics may have a Criteria, only Survey Questions can be used to construct a Criteria. For example, you can have a Criteria that evaluates the response to a given Survey Question, but you cannot have a Criteria that evaluates a certain value in a cognitive task.
Syntax
Criteria in Ethica is very similar to conditional expressions in any other programming language. It is a set of one or more conditions, which are connected using a logical connective, i.e., AND, OR, or NOT, and may be grouped using parentheses. If the expression is properly constructed, it will always evaluate as True or False. The following line shows a sample Criteria:
Q58_31 == 0 AND Q58_20 > Q58_27
Here the Q58_31 == 0 and Q58_20 > Q58_27 are the conditions and AND is the logical connective. You can have as many conditions as you need. You can also use parentheses to group the conditions. Ethica always evaluates the inner parentheses and works its way out until it evaluates the entire Criteria. For example, consider the following Criteria:
(Q58_31 == 0 AND Q58_20 > Q58_27) OR (Q58_31 == 1 AND Q58_20 < Q58_27)
In the above example, Ethica first evaluates the left-side parentheses to True or False, then moves to the right-side parentheses and evaluates that as well, and then combines the two with OR.
You can also use NOT in front of each condition to negate the result of the evaluation. For example, if Q58_31 == 0 is evaluated as True, NOT Q58_31 == 0 will be evaluated as False. Also, NOT Q58_31 can be used, which is evaluated True when Q58_31 is not responded to, or the answer's type is not supported with conditional expressions, e.g., images. Otherwise, it will be evaluated as False.
Operators
Each condition usually consists of three parts: left operand, operator, and right operand. The operator compares the left and right operands and can be one of the following:
Operator
Meaning
>
Greater than
>=
Greater than or equal to
<
Less than
<=
Less than or equal to
==
Equal
!=
Not equal
Operands
Operands are tokens that Ethica can understand and convert to a number. An operand can be one of the following:
Question Reference: these operands refer to a question in the current Survey or another Survey, e.g. Q58_31.
Keyword: these operands point to a special value, e.g. _days_since_reg_time.
Number: a positive number, greater than or equal to 0, e.g. 22 or 12.5.
Question Reference
An operand can refer to the response to a particular question in a Survey. In this case, Ethica always retrieves the latest response to that question, converts it to a number, and uses that for the Criteria evaluation.
Question Reference operands should always start with the letter Q, followed by two numbers that are separated by an underline. The letter Q helps Ethica to understand this is a reference to a question. The two numbers following Q are pointing to the Survey Activity ID and the question ID that is referenced here, respectively.
Each Survey Activity has a unique ID, automatically assigned to it by Ethica. Each question also has an ID unique within that Survey. So a combination of Survey ID and question ID always points to the same question in your study. For example, the Q58_31 operand is referring to question 31 of Survey Activity #58.
Also, researchers can use a simpler syntax by using Qn instead of Qm_n when the Criteria is being used in the same Survey Activity, where m refers to Survey Activity #m, and n refers to question #n.
Not all questions can be referenced in the Criteria. As Ethica needs to convert the response to a question into a number before evaluation, the question being referenced should be numerical. The following questions can be referenced in a Criteria:
Number: the response is already a number.
Mass: the response in metric will be used for evaluation.
Length: the response in metric will be used for evaluation.
Visual Analog Scale: the response is already a number.
Single Answer: the ID of the selected answer will be used for evaluation.
Multiple Answer: a set of numbers, containing the ID of all chosen answers will be used for evaluation.
The following question types cannot be referenced in a Criteria:
Information
Text
Audio
Image
Video
Audio/Text
Barcode
Calendar
Adding any of the above question references to a condition results in that condition being evaluated as False. Although, the Criteria still may be evaluated as True depending on other conditions in the Criteria.
Note that for Multiple Answer questions, only the != and == operators can be used. Using other operators is not allowed and will be evaluated as False. Also, for those 2 operators, the condition will check if the other operand is among the selected answers for the Multiple Answer question. And if both operands are references to Multiple Answer questions, they'd be equal to each other if the same set of answers are selected for both questions.
Invalid Question References
When Ethica evaluates a question reference in a given condition, it retrieves the latest response to that question and uses that for evaluation. If the question is not responded to so far, the retrieval returns null. Comparing null to any value will be evaluated as False.
For example, consider the Criteria Q1_12 == 2 where Q1_12 refers to a number question. If at the time of evaluation, the participant has not responded to Question 12 of Survey 1 yet, Q1_12 is null, and null == 2 is evaluated as False.
Keyword
Ethica supports a certain set of keywords that point to certain values related to the participation record. Currently, these values include the following:
_seconds_since_reg_time
_minutes_since_reg_time
_hours_since_reg_time
_days_since_reg_time
_weeks_since_reg_time
_months_since_reg_time
_years_since_reg_time
_seconds_since_reg_date
_minutes_since_reg_date
_hours_since_reg_date
_days_since_reg_date
_weeks_since_reg_date
_months_since_reg_date
_years_since_reg_date
The above values store the amount of time spent since the registration date or registration time. For example, _hours_since_reg_time refers to the number of full hours that passed since the exact time that the participant enrolled. So if the participant joins the study at 2020-11-07 20:15:07 local time and the Criteria is being evaluated at 2020-11-09 07:12:00, the duration between the two is 34:56:53, and therefore _hours_since_reg_time will be equal to 34.
As another example, consider _weeks_since_reg_date. Again assume the participant joins the study at 2020-11-07 20:15:07 local time and the Criteria is being evaluated at 2020-12-09 07:12:00. In this case, Ethica compares the evaluation time (2020-12-09 07:12:00) with the registration date (2020-11-07 00:00:00), which is 4w 4d 07:12:00. Therefore _weeks_since_reg_date will be equal to 4.
Note that the above values can only be used in Criteria for Survey Sections and Survey Questions. Using them in a Criteria for Eligibility Survey, or for an Activity or Triggering Logic is evaluated to False.
Condition Evaluation Examples
In order to evaluate a Criteria, Ethica breaks it into a set of conditions, evaluates each condition individually, then combines them using logical connectives. This results in a single True or False value. It's best to explain this using an example Survey. Assume your study contains a Survey Activity with ID 1, and the Survey contains the following question IDs:
Q1_1: Single answer question. It contains three answers: Red (A ID: 1), Green (A ID: 2), and Yellow (A ID: 3).
Q1_2: Multiple answer question. It contains three answers: Red (A ID: 1), Green (A ID: 2), and Yellow (A ID: 3).
Q1_3: Number question
Q1_4: Length question
Q1_5: Mass question
Q1_6: Visual analog scale question
Q1_7: Another Multiple Answer question. It contains four answers: Red (A ID: 1), Green (A ID: 2), Yellow (A ID: 3), and Blue (A ID: 4).
Q1_8: Text question
Q1_9: Audio question
Q1_10: Video question
Q1_11: Image question
Q1_12: Audio/Text question
Q1_13: Barcode question
Q1_14: Calendar question
Q1_15: Information question
The following table lists a set of example conditions, and explains how Ethica evaluates each:
Condition
Evaluation
Q1_1 > 1
If the last response participant gave to Q1_1 is either Green or Yellow, the evaluation will be True, otherwise, it will be False.
Q1_1 == Q1_3
If the number the participant entered for Q1_3 is the same as the ID she selected for Q1_1, True. Otherwise False.
Q1_3 < Q1_1
If the number entered for Q1_3 is less than the ID of the answer chosen for Q1_1, True. Otherwise False.
_days_since_reg_date == Q1_1
If the full days passed since the registration date is the same as the ID of the answer chosen for Q1_1 (either 1, 2, or 3), True. Otherwise False.
Q1_1 == 1.5
This will be always False because the responses to Q1_1 are either 1, 2, or 3, and none of them is equal to 1.5.
Q1_1 == Q1_2
This will be True if the ID of the response to Q1_1 is also chosen for Q1_2. For example, if Q1_1 is Red, as long as Red in Q1_2 is also selected, irrespective of other selected items for Q1_2, the evaluation is True.
Q1_2 == 2
If Green is selected for Q1_2, irrespective of other selected items, will be evaluated as True. Otherwise False.
Q2 == 2
This syntax can be used instead of the Q1_2 == 2 when you want to reference a question inside the current Survey. If Green is selected, will be evaluated as True. Otherwise False.
Q1_2 == Q1_7
This compares the answer set for Q1_2 with the answer set for Q1_7. If they are identical, it evaluates to True. Otherwise False.
Q1_2 > 1
Because of unsupported operators for Multiple Answer questions, this condition evaluates to False.
Q1_2 == Q1_11
As Q1_11 is an Image question, this condition always evaluates to False. The result will also be False for any of the Q1_8 to Q1_15.
Q1_8 <= 12
Same as above. Will always evaluate to False because Q1_8 is a Text question.
NOT Q1_12
Always evaluates to True. That's because Q1_12 always evaluates to False, and NOT will negate that to True.
NOT(Q1_13 < 1)
Same as above. This will always evaluate to True because it negates the result of Q1_13 < 1 which is always False.
_days_since_reg_date > 5
True if the number of days that have passed since the participant registered is greater than 5. Otherwise False.
_hours_since_reg_time < 12
True if the participant is in the first 12 hours of his participation. Otherwise False.
1 == 1
Always True.
2 != 1.1
Always True.

Operator	Meaning
`>`	Greater than
`>=`	Greater than or equal to
`<`	Less than
`<=`	Less than or equal to
`==`	Equal
`!=`	Not equal

Condition	Evaluation
`Q1_1 > 1`	If the last response participant gave to Q1_1 is either `Green` or `Yellow`, the evaluation will be `True`, otherwise, it will be `False`.
`Q1_1 == Q1_3`	If the number the participant entered for Q1_3 is the same as the ID she selected for Q1_1, `True`. Otherwise `False`.
`Q1_3 < Q1_1`	If the number entered for Q1_3 is less than the ID of the answer chosen for Q1_1, `True`. Otherwise `False`.
`_days_since_reg_date == Q1_1`	If the full days passed since the registration date is the same as the ID of the answer chosen for Q1_1 (either 1, 2, or 3), `True`. Otherwise `False`.
`Q1_1 == 1.5`	This will be always `False` because the responses to Q1_1 are either 1, 2, or 3, and none of them is equal to 1.5.
`Q1_1 == Q1_2`	This will be `True` if the ID of the response to Q1_1 is also chosen for Q1_2. For example, if Q1_1 is `Red`, as long as `Red` in Q1_2 is also selected, irrespective of other selected items for Q1_2, the evaluation is `True`.
`Q1_2 == 2`	If `Green` is selected for Q1_2, irrespective of other selected items, will be evaluated as `True`. Otherwise `False`.
`Q2 == 2`	This syntax can be used instead of the `Q1_2 == 2` when you want to reference a question inside the current Survey. If `Green` is selected, will be evaluated as `True`. Otherwise `False`.
`Q1_2 == Q1_7`	This compares the answer set for Q1_2 with the answer set for Q1_7. If they are identical, it evaluates to `True`. Otherwise `False`.
`Q1_2 > 1`	Because of unsupported operators for Multiple Answer questions, this condition evaluates to `False`.
`Q1_2 == Q1_11`	As Q1_11 is an Image question, this condition always evaluates to `False`. The result will also be `False` for any of the Q1_8 to Q1_15.
`Q1_8 <= 12`	Same as above. Will always evaluate to `False` because Q1_8 is a Text question.
`NOT Q1_12`	Always evaluates to `True`. That's because Q1_12 always evaluates to `False`, and `NOT` will negate that to `True`.
`NOT(Q1_13 < 1)`	Same as above. This will always evaluate to `True` because it negates the result of `Q1_13 < 1` which is always `False`.
`_days_since_reg_date > 5`	`True` if the number of days that have passed since the participant registered is greater than 5. Otherwise `False`.
`_hours_since_reg_time < 12`	`True` if the participant is in the first 12 hours of his participation. Otherwise `False`.
`1 == 1`	Always `True`.
`2 != 1.1`	Always `True`.

Triggering Logics

Surveys

Last modified 11d ago