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 criteria is evaluated
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
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, Avicenna shows or
skips a given section or question depending on whether its criteria is evaluated
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
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.
Criteria is a set of one or more conditions, which are connected using a logical
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.
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
their inherent precedence order, with
AND having the highest precedence,
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
The following lines show a sample criteria:
Q58_31 == 0 AND Q58_20 > Q58_27
Q58_31 == 0 and
Q58_20 > Q58_27 are the conditions and
AND is the
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
and the value of
Q58_20 is greater than or equal to
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
False, then moves to the right-side parentheses and evaluates that as well,
and then combines the two with
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
NOT Q58_31 == 0 will be evaluated as
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
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:
|Greater than or equal to|
|Less than or equal to|
Operands are tokens that Avicenna can understand and convert to a number. An operand can be one of the following:
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
pointing to the Survey Activity ID and the
question ID that is referenced
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
Q58_31 operand is referring to question 31 of Survey Activity
Also, researchers can use a simpler syntax by using
Qn instead of
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:
Adding any of the above question references to a condition results in that
condition being evaluated as
False. Although, the Criteria still may be
True depending on other conditions in the Criteria.
Note that for Multiple Answer questions, only the
== operators can be
used. Using other operators is not allowed and will be evaluated as
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 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 to any value will be evaluated as
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,
null == 2 is evaluated as
Avicenna supports a certain set of keywords that point to certain values related to the participation record. Currently, these values include the following:
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
34:56:53, and therefore
_hours_since_reg_time will be equal to
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
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
Setting a Criteria
In Avicenna, there are two ways to set a criteria for the various elements mentioned above:
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
- Users can construct criteria using a graphical interface which 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
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 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, then combines them using logical
connectives. This results in a single
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:
|If the last response participant gave to Q1_1 is either |
|If the number the participant entered for Q1_3 is the same as the ID she selected for Q1_1, |
|If the number entered for Q1_3 is less than the ID of the answer chosen for 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), |
|This will be always |
|This will be |
|This syntax can be used instead of the |
|This compares the answer set for Q1_2 with the answer set for Q1_7. If they are identical, it evaluates to |
|Because of unsupported operators for Multiple Answer questions, this condition evaluates to |
|As Q1_11 is an Image question, this condition always evaluates to |
|Same as above. Will always evaluate to |
|Always evaluates to |
|Same as above. This will always evaluate to |
|Evaluates to |
|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 |
|Always evaluates to |
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 firstname.lastname@example.org.