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:

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 to True and as long as it remains True, the activity can be prompted to that participant per its Triggering Logic specification. For those participants that the activity criteria is evaluated to False and as long as it remains False, the activity will not be prompted regardless of its Triggering Logic.

Furthermore, each Triggering Logic 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 the 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 to 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.

While any activity and any triggering logic 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 are very similar to conditional expressions in any other programming language. It is a set of one or more conditions, which are connected together using a logical connective, i.e. AND, OR, or NOT, and may be groupped using parentheses. If the expression is properly constructed, it will always evaluate to 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, and 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 evaluation. For example, if Q58_31 == 0 is evaluated to True, NOT Q58_31 == 0 will be evaluated to False.

Operators

Each condition 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 them and convert them to a number. An operand can be one of the following:

  • Question Reference: these operands refer to a question in the current survey or in 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 of 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's 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, Q58_31 operand is referring to question 31 of survey activity #58.

Not all questions can be referenced in a criteria. As Ethica needs to convert the response to a question into 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 that condition to be evaluated to False. Although, the criteria still may be evaluated to True depending on other conditions in the criteria.

Note that for Multiple Answer questions, only the != and == operators can be used. Using other operators are not allowed and will be evaluated to False.

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 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 to False.

Keyword

Ethica supports a certain set of keywords that they 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 registration date or registration time. For example, _hours_since_reg_time refers to the number of full hours 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 compare 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 the logical connectives. This results 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: A1, A2, and A3.
  • Q1_2: Multiple answer question. It contains three answers: A1, A2, and A3.
  • 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: A1, A2, A3, and A4.
  • 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 A2 or A3, 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 is 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 A1, as long as A1 in Q1_2 is also selected, irrespective of other selected items for Q1_2, the evaluation is True.
Q1_2 == 2 If A2 is selected for Q1_2, irrespective of other selected items, will be evaluated to 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 Only != and == operatos are supported for Multiple Answer questions. Therefore 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 participant is on the 5th day of his participation or more. 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