Skip to main content

Criteria

Criteria in Avicenna is a conditional expressions, or a formula, which instructs Avicenna whether an action has to happen or not. Avicenna 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, Avicenna evaluates the criteria periodically. For those participants that the Activity 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 should be activated or not.

For Survey Sections, and similarly, for Survey Questions, Avicenna shows or skips a given section or question depending on whether its criteria is evaluated as True or False.

Additionally, Notification Templates can have a criteria. Notifications related to a template will be triggered only when the template's criteria is evaluated as True.

By default, the Criteria field for the components mentioned above is set to empty. In Avicenna 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, Avicenna evaluates it to False.

info

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 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. Conditions can include both positive and negative values. If the expression is properly constructed, the evaluation results in a Boolean value.

note

When composing criteria in Avicenna, it's important to consider the order of evaluation. The system adheres to a combined approach of logical operator order precedence and natural precedence. Logical operators AND, OR, and NOT have their inherent precedence order, with AND having the highest precedence, followed by OR, and then NOT. Additionally, expressions enclosed in parentheses are evaluated first, providing a means to override the default precedence. This ensures a balance between logical rigor and intuitive expression composition, allowing for more complex and nuanced criteria definitions.

The following lines show 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.

And an example that includes a negative value in the condition:

Q58_31 == -10 AND NOT Q58_20 > -5

In this example, the condition will be True if the value of Q58_31 is -10 and the value of Q58_20 is less than or equal to -5.

You can have as many conditions as you need. As explained earlier, Avicenna evaluates conditions within parentheses first, then works its way out. 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, Avicenna 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 as 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:

OperatorMeaning
>Greater than
>=Greater than or equal to
<Less than
<=Less than or equal to
==Equal
!=Not equal

Operands​

Operands are tokens that Avicenna can understand and convert to a number. An operand can be one of the following:

Question Reference​

An operand can refer to the response to a particular question in a Survey. In this case, Avicenna 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 Avicenna 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 Avicenna. 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.

As mentioned before, only questions with numerical responses can be referenced in the criteria. 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. However, 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 were selected for both questions.

Invalid Question References

When Avicenna 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​

Avicenna 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, Avicenna 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.

Setting a Criteria​

In Avicenna, there are two ways to set a criteria for the various elements mentioned above:

  1. Manual Typing (Typing mode):

    • Users with a good understanding of the syntax can type out the criteria manually.
    • This mode provides a text field where users can type in their criteria using the correct syntax.
    Setting criteria using Typing mode
    Setting criteria using Typing mode

  2. Interactive mode:

    • Users can construct criteria using a graphical interface that provides buttons and dropdown menus.
    • This interface allows users to select questions, operators, and values from dropdown menus and buttons, making it easier to construct criteria without having to remember the exact syntax.
    Setting criteria using Interactive mode
    Setting criteria using Interactive mode

Both methods are designed to cater to different user preferences and levels of familiarity with Avicenna's criteria syntax. The manual typing mode is more flexible and may be faster for experienced users, while the interactive mode provides a more guided and structured way of creating criteria, which may be more beneficial for newer or less technical users.

Condition Evaluation Examples​

In order to evaluate a Criteria, Avicenna breaks it into a set of conditions, evaluates each condition individually, and 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 Avicenna 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. | | Q1_3 < 0 | Evaluates to True when the response to Q1_3 is a negative number. False otherwise. | | Q1_6 == -10 | Is True only when the participant's score on the VAS (Q1_6) is exactly -10. Otherwise, it is False. | | Q1_6 > -20 | Becomes True if the participant's score on the VAS (Q1_6) is greater than -20. In all other cases, it's False. | | NOT Q1_6 > -5 | True only when the participant's score on the VAS (Q1_6) is less than or equal to -5. If not, the condition is False. | | Q1_3 < -10 AND Q1_6 > -20 | This condition checks if the response to Q1_3 is less than -10 and the score on the VAS (Q1_6) is greater than -20. If both conditions are met, it's True. If not, it's False. | | Q1_5 == -1 | Always evaluates to False as the response to a Mass question (Q1_5) cannot be a negative number. | |

The criteria system in Avicenna is a robust and flexible framework that empowers researchers and practitioners to define precise conditions for the execution of various elements within a study. By understanding the syntax and the evaluation logic of criteria, users can effectively tailor the behavior of eligibility surveys, activities, triggering logics, survey sections, and survey questions to meet the specific requirements of their studies. The examples provided clarify how different types of conditions and logical connectives are evaluated, assisting users in constructing and troubleshooting their criteria. As Avicenna continues to evolve, the criteria system will remain a pivotal component in ensuring accurate and meaningful engagement with participants.

For further assistance or inquiries, feel free to contact our support team at support@avicenna.com.