# Criteria

**URL:** <https://forum.avicennaresearch.com/t/criteria/1236>\
**Category:** Reference\
**Created:** [June 16, 2025, 9:18am UTC](https://forum.avicennaresearch.com/t/criteria/1236 "2025-06-16T09:18:45Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![mojtaba](https://forum.avicennaresearch.com/letter_avatar_proxy/v4/letter/m/e56c9b/32.png) [@mojtaba](https://forum.avicennaresearch.com/u/mojtaba)\
**Post date:** [June 16, 2025, 9:18am UTC](https://forum.avicennaresearch.com/t/criteria/1236/1 "2025-06-16T09:18:45Z")

</div>

Criteria in Avicenna is a [conditional expression](https://en.wikipedia.org/wiki/Conditional_%28computer_programming%29), or formula, that instructs Avicenna whether an action should occur (or whether a study section should be shown or activated) based on the participant’s context, which eventually increases participant compliance rates.

Avicenna allows adding criteria to the following elements:

- [Eligibility Surveys](https://forum.avicennaresearch.com/t/eligibility-screening/1273/1)
- [Activities](https://forum.avicennaresearch.com/t/activities/1237/1)
- [Triggering Logics](https://forum.avicennaresearch.com/t/triggering-logics/1238/1)
- [Survey Sections](https://forum.avicennaresearch.com/t/flow-control/1285#p-2912-using-criteria-to-control-survey-flow-1)
- [Survey Questions](https://forum.avicennaresearch.com/t/flow-control/1285#p-2912-using-criteria-to-control-survey-flow-1)
- [Notification Templates](https://forum.avicennaresearch.com/t/notifications/1277#p-2904-notification-templates-1)

### Survey Criteria

Survey sections and questions can include criteria that control their visibility. Avicenna shows or skips a section or question based on whether its criteria evaluates to `True` or `False`.

> [!note] Note  
> An eligibility survey must have a criteria. This criteria specifies who is considered eligible to join the study and who should be excluded.

### Activity Criteria

Activities can have criteria that control whether they are available to a participant. Avicenna evaluates activity criteria whenever the condition or values of its parameter change. The activity must be prompted to the participant during its triggering time if the criteria is evaluated to `True`.  
The criteria is not considered only when researchers manually release the activity.

### Triggering Logic Criteria

Each TL can also have a criteria that determines whether it should be enabled. Similar to activity criteria, TL criteria is evaluated whenever the condition or values of its parameter change.

### Notification Template Criteria

Notification templates can include criteria that controls when notifications are sent. Notifications associated with a template are triggered only when the template’s criteria evaluates to `True`.

By default, the criteria field for all components mentioned above is empty. In Avicenna, an empty criteria evaluates to `True`, meaning the component is active by default. If a criteria is not empty but contains a syntax error, Avicenna evaluates it to `False`.

> [!info]  
> Only survey questions can be used in criteria; other sources, like cognitive tasks, are not supported.

## Syntax

A criteria is composed of one or more conditions connected by logical operators such as `AND`, `OR`, and `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](https://en.wikipedia.org/wiki/Boolean_data_type).

> [!note]  
> When composing criteria in Avicenna, it is important to consider the order of evaluation. The system follows standard logical operator precedence: expressions in parentheses are evaluated first, followed by `NOT`, then `AND`, and finally `OR`. Parentheses can be used to override the default precedence, enabling more complex and precise criteria definitions.

You can combine multiple conditions using logical operators.

> [!example] Basic AND Condition
> 
> ```plaintext
> Q58_31 == 0 AND Q58_20 > Q58_27
> 
> ```
> 
> In this example, `Q58_31 == 0` and `Q58_20 > Q58_27` are the conditions, and `AND` is the logical operator that connects them.

Conditions may also include negative values and negated expressions.

> [!example] Using NOT and Negative Values
> 
> ```plaintext
> 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 use parentheses to group conditions and build more complex logic.

> [!example] Grouping Conditions with Parentheses
> 
> ```plaintext
> (Q58_31 == 0 AND Q58_20 > Q58_27) OR (Q58_31 == 1 AND Q58_20 < Q58_27)
> 
> ```
> 
> In this 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`.

### Negating a Condition

You can use `NOT` to negate the result of a condition. For example, if `Q58_31 == 0` evaluates to `True`, then `NOT Q58_31 == 0` evaluates to `False`.  
You can also apply `NOT` directly to a question reference. In this case, `NOT Q58_31` evaluates to `True` when `Q58_31` has not been answered or when its response type is not supported by conditional expressions (e.g., images). Otherwise, it evaluates to `False`.

### Operators

Each condition typically consists of three parts: **a left operand** , **an operator** , and **a right operand**. The operator compares the left and right operands and determines the result of the condition. Supported operators are listed below:

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

### Operands

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

#### Question Reference

An operand can reference the response to a specific question in a survey. In this case, Avicenna always retrieves the most recent response to that question, converts it to a numeric value, and uses it for criteria evaluation.

A question reference operand must start with the letter `Q`, followed by two numbers that are separated by an underscore. The letter `Q` helps Avicenna understand that the operand refers to a question. The first number represents the [survey ID](https://forum.avicennaresearch.com/t/activities/1237/1) and the second number represents the [question ID](https://forum.avicennaresearch.com/t/view-responses/1287#p-2914-response-metadata-22) that is referenced here.

Each survey has a unique, system-assigned ID, and each question has an ID that is unique within that survey. Therefore, the combination of survey ID and question ID always identifies the same question in the study. For example, the `Q58_31` refers to question `31` of survey with ID `58`.

When a criteria is defined within the same survey, a simplified syntax can be used. In this case, `Qn` may be used instead of `Qm_n`.

Only questions whose responses can be represented as numbers can be referenced in criteria. The following question types are supported:

- **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 criteria:

- Information
- Text
- Audio
- Image
- Video
- Audio/Text
- Barcode
- Calendar

> [!note] Note  
> If a question of an unsupported type is referenced in a condition, that condition evaluates to `False`. However, the overall criteria may still evaluate to `True` depending on the other conditions.

> [!note] Note  
> For [multiple answer questions](https://forum.avicennaresearch.com/t/questions/1291#p-2918-multiple-answer-15), only the `!=` and `==` operators can be used. Using any other operator causes the condition to evaluate to `False`. When using `==` or `!=`, the condition checks whether the other operand is included in the selected answers. If both operands reference multiple answer questions, they are considered equal only if the same set of answers was selected for both questions.

**Invalid Question References**

When Avicenna evaluates a question reference in a condition, it retrieves the latest response to that question and uses it for evaluation. If the question has not been answered yet, the retrieved value is `null`. Comparing `null` to any value evaluates to `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` evaluates to `False`.

#### Keyword

Avicenna supports a set of keywords that point to certain values related to the participation record. Supported keywords include:

- `_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`

These values represent the amount of time that has passed since the participant’s registration date or registration time.

> [!example] Example: `_hours_since_reg_time`  
> `_hours_since_reg_time` refers to the number of full hours that passed since the exact time the participant enrolled. If a participant joins the study at `2020-11-07 20:15:07` (local time) and the criteria is evaluated at `2020-11-09 07:12:00`, the duration between the two is `34:56:53`. Therefore `_hours_since_reg_time` will be equal to `34`.

> [!example] ` Example: _weeks_since_reg_date`  
> `_weeks_since_reg_date` refers to the number of full weeks that have passed since the participant’s registration date. If a 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`, 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]Note  
> These keywords can be used only in criteria for **Survey Sections** and **Survey Questions**. When used in criteria for an **Eligibility Survey** , **Activity** , or **Triggering Logic** , they are always evaluated as `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)**:

2. **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.

Assume your study contains a survey 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 enables researchers and practitioners to define precise conditions for the execution of various elements within a study. By understanding the criteria syntax and evaluation logic, 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 illustrate how different types of conditions and logical connectives are evaluated, helping users construct and troubleshoot their criteria. As Avicenna continues to evolve, the criteria system will remain a core component in ensuring accurate and meaningful participant engagement.

For further assistance or questions, please [contact our support team](mailto:support@avicenna.com).